# phoria2 - reference for app writers

Small 3D for the web, for business apps: charts, labelled scenes, diagrams, dashboards, explainers,
editors and product viewers. WebGL 2, plain ES modules, no dependencies.

This is the whole API in one page, written for people and coding agents building with phoria2. Demos:
https://kevs3d.co.uk/phoria2/ - source: https://github.com/kevinroast/phoria2

## When to use it

phoria2 is for 3D that shows something: 3D charts from a data spec (bar, scatter, line, area,
surface, network), labelled diagrams and floor plans, cutaway explainers with callouts, animated
infographics on a timeline, dashboards of many small views, product viewers for glTF models, and
editors that drag, snap and undo. Picking, tooltips, hover highlights, HTML labels, shadows and
image-based light are built in, and a view draws only when something changes, so idle pages cost
nothing. A dashboard of many small views just works - each tile its own `new View({ canvas })`,
with no limit on WebGL contexts to manage (after the first four, views share one). Apps come out short: typically a few dozen lines. For games, custom shaders or
post-processing pipelines, three.js is the better fit: phoria2 has no shader hook (no custom
effects), no refraction, and no shadow-softness setting.

## Install

```sh
npm install phoria2
```

```js
import { View, Mesh, box } from 'phoria2'
import { chart } from 'phoria2/charts'                    // 3D charts from a spec
import { loadGLTF } from 'phoria2/gltf'                   // glTF 2.0 models
import { Timeline, follow, reveal } from 'phoria2/motion' // steps on a timeline, moving along curves
import { Emitter, Body } from 'phoria2/particles'         // particles and simple physics
import { TransformHandle, History } from 'phoria2/edit'   // a move/turn handle, and undo
```

Without a build step, map the imports to a CDN in the page, pinning the version (they share one
copy of the core):

```html
<script type="importmap">
{ "imports": {
  "phoria2": "https://cdn.jsdelivr.net/npm/phoria2@VERSION/dist/phoria2.js",
  "phoria2/charts": "https://cdn.jsdelivr.net/npm/phoria2@VERSION/dist/charts.js"
} }
</script>
```

The other sub-paths follow the same pattern: `dist/gltf.js`, `dist/motion.js`, `dist/particles.js`,
`dist/edit.js`. TypeScript types ship with the package.

When this page doesn't settle something, read the source with its comments in
`node_modules/phoria2/src` (`src/View.js`, `src/scene/`, `src/geometry/`, `src/charts/`...), not the
minified `dist/` files - but import from the entry points, not from `src/`.

**Versions** follow semver from 1.0: everything on this page and in the types keeps working through
1.x, defaults included. Exact pixels and error wording can change; nothing is removed without a
release that warns first, naming the replacement. A warning that something is deprecated says what
to write instead - do that.

## Conventions

- **Coordinates**: right-handed, **+Y up**, +Z towards the viewer, units are metres.
- **Angles** are radians, except a perspective camera's `fov`, which is degrees.
- **Vectors in**: `[x, y, z]` arrays (objects `{ x, y, z }` also work). On objects, `position`,
  `rotation`, `scale` are small vector classes: `node.position.set(1, 2, 3)`, `node.rotation.y += 0.1`,
  `node.scale.x = 2` and `node.position = [1, 2, 3]` (copied in) all work.
- **Colours**: `'#ff8800'`, `'#f80'`, `0xff8800`, CSS names (`'orange'`), `'rgb(255 136 0)'`, or
  `[r, g, b]` 0-1. Inputs are sRGB.
- **Time** is seconds. Handlers get what they act on as an argument (arrow functions are fine).
- **The orbit**: `view.controls.spherical` is `{ yaw, pitch, distance }` about `camera.target` - yaw 0
  looks from +Z (the front), `Math.PI / 2` from +X (the right); pitch is above the horizon. Setting it
  moves the camera, within the limits. Move the camera or its target yourself at any time - the orbit
  turns about wherever they are; `camera.target = [x, y, z]` copies the point in.
- **One options object per constructor.** Unknown option names throw an error that says what to use
  instead - read it, it usually names the fix.

## The minimal app

```html
<canvas id="c" style="width: 100%; height: 100vh; display: block"></canvas>
<script type="module" src="./main.js"></script>
```

```js
import { View, Mesh, box, DirectionalLight } from 'phoria2'

const view = new View({ canvas: '#c', orbit: true, background: '#1c1c20' })
const cube = view.scene.add(new Mesh({ geometry: box(2), material: { color: 'orange' } }))
view.scene.add(new DirectionalLight({ direction: [-1, -2, -1] }))
view.start((dt) => cube.rotateY(0.6 * dt))
```

The canvas needs a size from CSS; the View matches its drawing buffer to it and follows resizes
itself. A scene with no lights is lit automatically (with a console note).

## View

```js
const view = new View({ canvas: '#c', orbit: true })
```

| Option | Default | |
|---|---|---|
| `canvas` | a new full-window canvas | element or CSS selector |
| `camera` | `'perspective'`: a three-quarter view from the front right and above, fitted to the scene on the first frame | a preset - `'perspective'`, `'isometric'`, `'top'`, `'front'`, `'side'` (fitted to the scene on the first frame, unless you place or frame the camera first) - camera options (`{ position, target, fov }`), or a camera |
| `orbit` | `false` | `true`, or options: `{ autoRotate, inertia, minDistance, maxDistance, minPitch, maxPitch, pan, zoom, mode }`. `autoRotate`: `true` (a slow turn) or radians per second; it pauses while the user drags. `mode`: `'orbit'` (the default) or `'map'` - drags pan and the view never turns, for plans. `minDistance`/`maxDistance` limit zooming: the distance to the target, or for an orthographic camera the height of the view. Left-drag orbits, right-drag pans, wheel zooms |
| `background` | transparent | a colour |
| `highlight` | none | a colour mixed into whatever is under the pointer |
| `tooltip` | none | `(hit) => content` - see Interaction |
| `framing` | `'height'` | what stays in view as the canvas changes shape: `'height'`, `'width'`, or `'both'` (nothing framed is ever cut off - good for tiles). Also `{ keep, aspect }` |
| `renderMode` | `'auto'` | `'auto'` draws only when something changed (idle views cost nothing); `'always'`; `'manual'` |
| `toneMapping`, `exposure` | `'neutral'`, `1` | `'neutral'` \| `'aces'` \| `'none'` |
| `bloom` | off | glow round bright parts (emissive, additive points and lines): `true` or `{ strength, radius, threshold }`; also `view.bloom` |
| `autoLight` | `true` | light a scene that has no lights (a chart needs none of its own); `false` to leave it dark |
| `pixelRatio` | `min(devicePixelRatio, 2)` | |
| `context` | `'auto'` | WebGL context: own for the first four views on a page, then one shared context - so a page can hold any number of views |
| `keyboard` | `false` | `true` or `{ label: (hit) => text }`: use without a pointer, with a screen reader - see Interaction |
| `description` | none | what the view shows, for screen readers (the canvas's label); made from the scene when `keyboard` is on |
| `reducedMotion` | `'auto'` | as the system's reduced-motion setting: `frame()` jumps rather than glides, auto-rotation holds, charts change at once. `true` or `false` to choose |

Members: `view.scene`, `view.camera` (assign a camera or a preset name to switch), `view.controls`
(the orbit control), `view.renderer`, `view.width`, `view.height`, `view.description`, `view.reducedMotion`
(true or false as it stands - check it for motion of your own, such as a timeline; set `'auto'`, true or false).

Methods:

- `start(fn?)` - `fn(dt, t)` every frame. Time and node update handlers run anyway; you only need
  `start` for your own per-frame code.
- `frame(node?, { padding, direction, duration })` - move the camera so a node (default: the whole
  scene) fills the view, keeping the viewing direction - centred across, and a little below the
  middle so it stands rather than hangs. It fits what the camera draws - not hidden nodes, nor a
  chart's axis labels for the edges it isn't showing - so a chart fills the view. `padding` is the
  margin around it as a fraction of its size: `0` is a tight fit, `0.2` (the default) leaves a
  fifth, `0.5` half. `direction` looks from a preset's direction (`'perspective'`, `'top'`,
  `'front'`, `'side'`, `'isometric'` - the camera stays the kind it is) or a vector from the
  target towards the camera; `duration` (seconds) glides there - a press or the wheel stops it.
  A Reset button is `view.frame(undefined, { direction: 'perspective', duration: 0.6 })`; a guided
  tour flies from one node to the next with `view.frame(node, { duration: 1 })`.
- `on('click' | 'hover', (hit, event) => ...)` - see Interaction. Returns an unsubscribe function.
- `tooltip(fn)` - set the tooltip function later.
- `pick(x, y)` / `pick(event)` - the hit under a canvas position; `pickAll` for every hit.
- `rayAt(x, y)` / `rayAt(event)` - the world `Ray` through a canvas position, for placing things:
  `ray.at(ray.intersectPlane([0, 1, 0], [0, 0, 0]))` is the point on the floor under the pointer
  (`intersectPlane` returns null when the ray runs along the plane or away from it).
- `await view.toImage()` - a PNG `Blob` of the picture, labels included.
- `await view.explain()` - a plain-text report of what is drawn, with warnings ("nothing in view",
  "no lights", labels hidden...). Use it to debug a blank or wrong picture.
- `render()`, `invalidate()` (redraw after changing data the view can't see), `dispose()`.

If a page shows nothing or the wrong thing, `console.log(await view.explain())` before anything else.
Errors thrown for bad options name the option and usually the fix.

## Changing things later

Everything can be changed after it is made, and the next frame shows it (the View redraws when
something changes):

- Nodes: `position`, `rotation`, `scale`, `visible`, `pickable`, `add`/`remove` children. `node.bounds`
  is always current - read it straight after adding or moving things.
- Materials: every property - `color.set(...)`, `opacity` (going below 1 makes it transparent;
  back to 1, opaque again), `emissive`, `roughness`, `width` on Lines, `size` on Points, maps.
- Instances: `setInstance`, `setColor`. Labels: `text`, `className`, `visible`.
- Lights: `intensity`, `color`, `direction`, `castShadow`. Scene: `background`, `environment`.
- View: `view.camera = 'top'` switches camera (a preset is fitted to the scene); `view.controls.mode`,
  `view.controls.autoRotate`, `view.controls.enabled`; `view.highlight`; `view.tooltip(fn)`.
- Charts: `chart.update(newRows)` or `chart.update({ color: 'other' })` - animated.

## Scene graph

Everything in a scene is a node. Node options (all optional): `name`, `position`, `rotation`
(Euler XYZ radians, `[x, y, z]`), `quaternion` (`[x, y, z, w]` or `{ x, y, z, w }`), `scale` (number or `[x, y, z]`), `visible`,
`pickable` (default true), `userData`, `children`, `onUpdate`, `clip` (a section plane - see
Cutaways), plus the interaction options below.

```js
const group = view.scene.add(new Group({ position: [0, 1, 0] }))   // add() returns what it added
group.add(new Mesh({ geometry: sphere(), material: { color: 'teal' } }))
node.onUpdate((node, dt, t) => { node.rotation.y += dt })
scene.find('lamp'); scene.findAll((n) => n.name.startsWith('rack')); scene.traverse((n) => {})
node.translate(x, y, z); node.rotateY(rad); node.lookAt([0, 0, 0])  // a camera with a target moves its target; a light shines there
node.remove(child); node.removeFromParent(); node.dispose()
node.bounds              // world-space Box3: .min, .max, .getCenter(), .getSize()
node.boundsFrom(camera)  // the same, for only what that camera draws (hidden and showFrom-off parts left out)
node.worldPosition       // read only
node.updateWorld()       // world matrices up to date now - ancestors, the node, everything under it -
                         // to read worldPosition or bounds after moving things, before the next frame
node.updateWorldTree()   // the same for the node and everything under it, when its parent is already current
```

**Cutaways**: `clip: { normal, offset, cap }` on any node cuts away everything in its subtree on the
`normal` side of a plane, `offset` along the normal from the node's origin, in the node's own space
(so it moves with the node). `cap` fills the cut faces of closed shapes with a colour, as a surface
lying on the plane - parts that touch join cleanly, and what is inside them stays hidden; without it
they show their hollow insides. Caps need closed solids: keep open surfaces (planes, open tubes) out
of a capped clip. The nearest clip above a mesh is the one that cuts it. Move the cut
by changing it in place: `engine.clip.offset = 0.5`. Cut-away parts cast no shadow and can't be
picked; points and lines aren't cut. A clip is one plane: there is no cutting out an octant or a
wedge - build the cut-open shape itself for that.

```js
const block = view.scene.add(new Group({ clip: { normal: [0, 0, 1], offset: 0, cap: '#c0392b' } }))
```

`Scene` (also `view.scene`) adds: `background` (colour, or a panorama texture), `environment`
(`'studio'` - built in, no download - `'none'`, or an `.hdr` url: image-based light for every lit
material), `environmentIntensity`, `backgroundBlur` (0-1, for a panorama background), `fog`.

**Fog**: `scene.fog = { color, density }` - exponential, thickening with distance like mist (try 0.02 -
0.1) - or `{ color, near, far }` for linear. Give `background` the same colour, so distant things melt
into it. Change it in place (`scene.fog.density = 0.08`); `null` turns it off. Additive glows fade
out with distance rather than turning fog-coloured; a material with `fog: false` (a sky dome, a far
backdrop) ignores it.

## Drawables

All drawables take `geometry`, `material`, `castShadow`, `receiveShadow`, `renderOrder` and `data`.

```js
new Mesh({ geometry: box(1), material: { color: '#c33', roughness: 0.3 } })
new Points({ geometry, material: { color: 'white', size: 4, sizeAttenuation: false } })  // size in pixels when not attenuated
new Lines({ geometry: edges(box(2)), material: { color: '#333', width: 2 } })            // segments: pairs of vertices; width in pixels
new Label({ text: 'Rack A1', position: [0, 2, 0], className: 'my-label', place: 'above' })
```

**InstancedMesh** - many copies of one geometry in one draw call, for bars, racks, nodes:

```js
const bars = view.scene.add(new InstancedMesh({ geometry: box(1), material: { roughness: 0.5 }, data: rows }))  // count = rows.length
rows.forEach((r, i) => bars.setInstance(i, { position: [r.x, r.h / 2, r.z], scale: [0.8, r.h, 0.8], color: r.color }))
bars.setColor(3, 'red')
```

`setInstance(i, { position, rotation, quaternion, scale, color })`. An instance's `color` multiplies the
material's colour, which is white unless you set one - so the instance colour shows as given. `count` defaults to the number
of rows in `data`. For very large data, write `bars.instanceMatrices` (16 numbers per instance,
column-major) directly and call `bars.needsUpdate()`. An instance scaled to 0 is hidden: it draws
nothing, and bounds, framing, shadows and labels leave it out - so a pool can keep spare instances.
Positions and quaternions also take `{ x, y, z }` and `{ x, y, z, w }`, as physics engines return
them, so a physics bridge is one line a body:
`bricks.setInstance(i, { position: body.translation(), quaternion: body.rotation() })`.

**Labels** are HTML elements pinned to 3D points (style them with CSS). Options: `text`, `position`,
`className`, `place` (`'center'` | `'above'` | `'below'` | `'left'` | `'right'`), `offset` ([x, y]
pixels), `priority` (higher wins when labels overlap), `overlap` (`'hide'` | `'dim'` | `'show'` - what
a label does when covered), `occlude` (true: counts as covered when geometry is in front), `leader`
(true: a line from the point to the label, with a dot on the point - for callouts), `edge` (`'left'` |
`'right'`: set the label at that edge of the view, level with its point - callouts in a column, with
`leader: true`; `offset` then moves it in and up or down), `minScale` (show it only when zoomed in this
far - below).

A label answers the pointer when it has handlers: a Label with its own `onClick` or `onHover` is
clicked and hovered like a mesh (`new Label({ text: 'Mantle', onClick: () => show('mantle') })` - a
callout that opens its layer), and a label of an instance or point is part of it - clicking it is
clicking that bar, with the same hit. Other labels let the pointer through to the scene.

**Labels per instance or point**, without a Label node each:

```js
new InstancedMesh({ geometry: box(1), data: rows, labels: { text: (row) => row.name, place: 'above', priority: (row) => row.alert ? 2 : 0 } })
```

**Labels by zoom level**: `minScale` on any label shows it only when the view is zoomed in at least that
far - that many CSS pixels to one world unit, at the label's point (perspective or orthographic alike).
Until then it takes no part in the layout, so it can't push other labels out. `labels` can also be a
list, several labels per instance - the short one always, the details as you come closer:

```js
new InstancedMesh({ geometry: box(1), data: elements, labels: [
  { text: (e) => e.symbol, place: 'center', className: 'symbol' },
  { text: (e) => e.name, place: 'below', className: 'name', minScale: 45 },
] })
```

Pick `minScale` by looking: at the zoom where the details should appear, a world unit spans that many
pixels (a 1-unit tile drawn 60 px wide is 60). `view.explain()` counts the labels still waiting.

## Geometry

Generators return a `Geometry`; each takes one options object (a number is the main size):

| | Options |
|---|---|
| `box(size \| { width, height, depth })` | centred on the origin |
| `sphere({ radius, segments, rings })` | |
| `plane(size \| { width, depth })` | in the x-z plane, facing up (+Y) |
| `cylinder({ radius, radiusTop, height, segments })` | along Y, centred; `radiusTop: 0` is a cone, its tip at the + end of the axis (up) |
| `torus({ radius, tube })`, `icosphere({ radius, detail })` | |
| `lathe({ points, segments, axis })` | a profile of `[radius, y]` pairs, bottom up, turned about Y - pistons, bottles, bolts (listed top down, it faces inward) |
| `extrude({ shape, holes, depth, axis })` | an outline of `[x, y]` pairs (and hole outlines) pushed along Z, centred - plates, brackets, logos |
| `grid({ size, divisions })` | floor grid, for `Lines` |
| `edges(geometry, { angle })` | the edges of any geometry, for `Lines`: where faces turn more than `angle` degrees (default 1) - 30 keeps round surfaces clean, outlining a part as a drawing does |

`axis: 'x' | 'y' | 'z'` lays `cylinder`, `lathe` and `extrude` along another axis - no rotating the mesh
to suit. An extruded outline is drawn as seen from the axis's + end, centred along the axis: with
`'y'`, from above - the outline's x is the world's x and its y runs towards -z, away from the front.

**Outlines** for `extrude` and `lathe` - lists of `[x, y]` points, anticlockwise, to spread together or
cut as holes: `outline.circle(radius | { radius, segments, center })`, `outline.rect({ width, height,
radius, center })` (`radius` rounds the corners), `outline.polygon({ radius, sides, angle })`,
`outline.arc({ radius, from, to, center })` (angles in radians from +x; both ends included, for joining
into a shape), `outline.gear({ radius, teeth, depth })`.

```js
// a connecting rod: two eyes joined by their sides, each bored through, lying across x
extrude({
  shape: [...outline.arc({ radius: 0.15, from: -0.4, to: Math.PI + 0.4, center: [0, 1.4] }), ...outline.arc({ radius: 0.3, from: Math.PI - 0.4, to: 2 * Math.PI + 0.4 })],
  holes: [outline.circle(0.2), outline.circle({ radius: 0.09, center: [0, 1.4] })],
  depth: 0.16, axis: 'x',
})
```

Your own: `new Geometry({ positions, normals?, uvs?, uvs2?, colors?, indices? })` - flat arrays, xyz per
vertex; `colors` are rgb 0-1 per vertex (use `material: { vertexColors: true }`); `uvs2` is a second UV
set, for baked occlusion and light maps (below). To animate one - cloth, a wave, a morph - write
`geometry.positions` in place and call `geometry.needsUpdate()` each frame; normals you didn't give are
worked out again to follow the shape.

## Materials

One material type, given as a plain object:

```js
{ color: 'white' }                                   // lit, physically based
{ color: '#c33', roughness: 0.2, metalness: 1 }      // metal
{ color: 'orange', unlit: true }                     // flat colour, ignores lights
{ color: '#8cf', opacity: 0.4 }                      // transparent: fades the whole surface
{ transmission: 1, roughness: 0.05 }                 // clear glass
{ color: '#a3121f', metalness: 0.6, clearcoat: 1 }   // car paint: a glossy coat over it
{ color: '#1f2d6e', roughness: 0.9, sheen: 1 }       // velvet: cloth's bright rim
{ color: '#ccc', metalness: 1, anisotropy: 0.8 }     // brushed metal
{ color: '#f2e4c4', translucency: 0.8 }              // paper: lit from behind too
{ matcap: 'clay.png' }                               // the look from a picture of a lit sphere
{ color: '#e4572e', toon: 3 }                        // cartoon: three flat tones
{ emissive: '#ff0', emissiveIntensity: 3 }           // glows
{ map: 'wood.jpg', normalMap: 'wood_n.png' }         // textures from urls
```

**Exact colour**: an `unlit` material draws exactly the colour it is given - `'#e15759'` is
`#e15759` on screen and in `toImage()`, whatever the tone mapping - and so do instance colours,
vertex colours, colour maps, lines and points. Use it for swatches, legends, status colours and
brand colours. A lit surface doesn't keep its colour: light and tone mapping are meant to change
it. Vertex colours blend across each face in linear light, so a ramp between two vertices differs
slightly from a 2D tool's; subdivide for a closer match.

Properties: `color`, `opacity`, `roughness` (0.5), `metalness` (0), `emissive`,
`emissiveIntensity`, `unlit`, `flatShading`, `doubleSided`, `vertexColors`, `fog` (true), `blending`
(`'normal'`, `'additive'` - adds light, for glows and sparks - or `'multiply'` - darkens what is behind, as a colour
filter does: cyan over magenta is blue), `alphaTest` (cut-outs: drop pixels with less alpha - leaves, fences),
`map`, `normalMap`/`normalScale`, `bumpMap`/`bumpScale`, `roughnessMap`, `metalnessMap`, `aoMap`,
`emissiveMap`, `lightMap`/`lightMapIntensity`, `environmentIntensity` (1), `transmission`, `clearcoat`/`clearcoatRoughness`, `sheen`/`sheenColor`/`sheenRoughness`, `ior`/
`specularIntensity`/`specularColor`, `anisotropy`/`anisotropyRotation`, `translucency`/`translucencyColor`, `matcap`, `toon` (below); `size`/`sizeAttenuation` for Points, `width` for Lines. Change later through
`mesh.material.color.set('#0f0')`, `mesh.material.opacity = 0.5`, or a whole new one: `mesh.material = { color: 'red' }`
(options become a Material, as in the constructor; `mesh.geometry = box(2)` likewise).

A **bump map** is a height texture (red channel) shown as bumps - no normal map to make, so it suits
heights drawn in code. `bumpScale` is how high a height of 1 stands, in the mesh's units. Textures
take `anisotropy` (default 8, up to the GPU's limit, 1 for off), which keeps floors and roads sharp
into the distance. A cut-out (`alphaTest`) casts the shadow of what is left of it. A Texture given to a
data map (`normalMap`, `bumpMap`, `roughnessMap`, `metalnessMap`, `aoMap`) is read as data, not colour,
unless its `colorSpace` was set on purpose - `normalMap: await loadTexture('n.png')` just works.

**Canvas and video textures**: a texture's `image` can be a canvas - draw on it, then call
`texture.needsUpdate()` - or a `<video>`, whose frames upload by themselves while it plays, with
nothing to call. For a big canvas drawn on a little at a time (paint, a map being revealed), say what
changed - `texture.needsUpdate({ x, y, width, height })`, in the canvas's pixels from its top left -
and only that rectangle is sent, rather than the whole canvas every frame (several calls before a
frame add up). `new Texture({ url: 'promo.mp4' })` (or .webm, .ogv, .mov, .m4v) makes the video
for you, muted and looping so browsers let it start by itself; `texture.image` is that `<video>` -
pause, seek or unmute it as any other. A browser that blocks autoplay leaves it on its first frame
until `texture.image.play()` from a click. Video textures make no mipmaps (they would be remade
every frame) unless `mipmaps: true`. Put one on an unlit plane for a screen:
`{ map: new Texture({ url: 'promo.mp4', wrap: 'clamp' }), unlit: true }`.

**Placing a texture**: `repeat` ([u, v] times across), `offset`, and `rotation` (radians, about
`center`: [0, 0], the corner, by default - [0.5, 0.5] for the middle) - applied in that order, as glTF's
`KHR_texture_transform` does, and each map keeps its own: a fabric's colour can repeat 7 times while
its normal map repeats twice. Animate them to scroll or spin a pattern.

**Baked occlusion and light maps**: occlusion and lighting baked in Blender, Unreal or Unity need
every surface on its own patch of texture, so they come on a second UV set while the first tiles
colour and detail. Give the geometry `uvs2` and the texture `uvSet: 1` - glTF models do both
for you (`TEXCOORD_1`, `texCoord: 1`). Read through the first set, baked occlusion lands in the
wrong places as dark smudges. `lightMap` is light baked into a texture, added as light from all
round (`lightMapIntensity`, 1) - the soft, cheap lighting of architectural scenes.

**Environment strength per material**: `environmentIntensity` (1) scales how much of the
scene's environment - its light and its reflections - one material takes: lower for a matte floor in
a shiny showroom, higher to make one product catch the light, without changing the scene's.

**Glass**: `transmission` (0-1) lets light through as glass does. Unlike `opacity`, which fades
everything - reflections too, so faded things look washed out, as dimmed chart bars should - glass
keeps its reflections whole, and shows less of what is behind it towards its edges, where it
reflects nearly everything. Its colour shows in proportion to `1 - transmission`: `transmission: 0.6`
with a colour is tinted glass. Keep `roughness` low for clear glass, higher for frosted. There is
no refraction - what is behind isn't bent. It shines with an `environment` to reflect
(`'studio'`, or better an `.hdr`).

**Clearcoat**: `clearcoat` (0-1) puts a clear glossy layer over the surface - car paint, lacquered
wood, varnish - with its own sharp reflection over the base's softer one; `clearcoatRoughness` (0,
a mirror) makes it satin. Normal and bump maps show under a smooth coat.

**Sheen**: `sheen` (0-1) is the soft bright rim of cloth at grazing angles - velvet, felt,
upholstery - which plain roughness can't give: without it fabric looks like matte plastic.
`sheenColor` (white) tints it, often lighter than the cloth or another colour entirely;
`sheenRoughness` (0.5) runs from a thin bright rim (0) to a broad soft glow (1).

**Reflectance**: `ior` (1.5) sets how strongly a non-metal reflects - water 1.33, glass and plastic
1.5, diamond 2.4 - and glass with `transmission` reflects more the higher it is.
`specularIntensity` (1) scales a non-metal's reflections, 0 for none (chalk, clay, unglazed
pottery); `specularColor` tints them face on. Metals take their reflections from `color`, so
these leave them alone.

**Brushed metal**: `anisotropy` (0-1) - the material's, not a texture's filtering - draws highlights and reflections out along the brushing -
brushed aluminium, steel appliances, the bottom of a pan. The brushing runs along the UVs' u (round
a sphere or cylinder, say; round the up axis on a mesh with no UVs); `anisotropyRotation`
(radians) turns it - `Math.PI / 2` runs it along v. Use it with `metalness: 1` and a middling
`roughness` (0.2-0.4).

**Translucency**: `translucency` (0-1) lets light through thin surfaces, so they are lit from
behind as well as in front - leaves against the sun, paper lanterns and lampshades with a light
inside, curtains. What passes through is taken from what is scattered back, so at 1 a surface is lit
only through it. `translucencyColor` (white) tints the light that comes through. It is light
through a thin sheet, not light scattering inside a solid: a lantern glows, marble stays marble.

**Matcap**: `matcap` is a picture of a lit sphere - clay, wax, chrome, a painted ball - that gives the
whole look: each point takes the colour from where a sphere facing the same way would show it. It is
the clay look of sculpting tools and CAD viewers, good for reading a model's shape, and costs one
texture lookup - no lights, shadows or environment, which it ignores. Its shine stays put as the camera
turns, since the light is in the picture, so it looks out of place beside lit things. `color` and
`map` multiply it, so one grey matcap serves any colour; normal and bump maps and `flatShading`
still shape it. Any matcap image works, or draw one on a canvas (`new Texture({ image: canvas })`).

**Toon**: `toon: 3` shades in that many flat tones (2 or more; 0, the default, is smooth), with one
hard-edged highlight - a cartoon. Lights and shadows work as usual; the shaded tone is the scene's
ambient and hemisphere light, so add some for a lighter shade. Metals keep their colour, with a
highlight of it. Pair it with `outline` on the nodes for inked edges.

glTF models bring glass, clearcoat, sheen, reflectance, brushed metal and translucency from `KHR_materials_transmission`, `KHR_materials_clearcoat`,
`KHR_materials_sheen`, `KHR_materials_ior`, `KHR_materials_specular`, `KHR_materials_anisotropy`
and `KHR_materials_diffuse_transmission` (by their factors; their textures aren't read).

**Models without UVs** (scans, CAD exports) can still take maps: `triplanar: 40` projects them
from the mesh's three axes instead of using UVs, repeating 40 times per unit of the mesh's own space.
The maps stay on the mesh as it moves; normal maps follow the surface; a map's `repeat` and `offset` apply
on top, as with UVs (animate `offset` to scroll a pattern). 0 (the default) uses the UVs.

```js
{ bumpMap: pores, bumpScale: 0.0005, roughnessMap: sheen, triplanar: 45 }   // bone texture on a scanned skull
```

## Lights and cameras

| | Options |
|---|---|
| `AmbientLight` | `color`, `intensity` |
| `HemisphereLight` | `sky`, `ground`, `intensity` |
| `DirectionalLight` | `color`, `intensity`, `direction` (the way it travels, e.g. `[-1, -2, -1]`), `castShadow`, `shadowBounds` |
| `PointLight` | `color`, `intensity`, `position`, `range` - inverse-square falloff, so intensity ~ distance squared (30 lights things ~5 m away); `castShadow` |
| `SpotLight` | point light options plus `direction`, `angle`, `penumbra`, `castShadow` |

Intensity 1 on a directional light lights a white surface facing it to white.

**Light limits**: a scene draws at most 2 directional lights and 4 point and spot lights together -
the first found in scene order; hidden ones don't count. Any more are ignored, with a console warning,
so a fifth lamp simply doesn't light anything. For a room of lamps, light it broadly with
`scene.environment` or a `HemisphereLight` (no limit), use real lights for the few that matter most -
near the camera, or casting shadows - and give the rest emissive materials so they still glow.
Toggle `visible` to move the real lights to where the action is.

**Shadows**: one directional light, up to four spot lights and one point light with `castShadow: true`;
meshes opt in with `castShadow` and `receiveShadow`. No shadow camera to set up. A spot light's own
lamp - anything whose bounds hold the light - doesn't block it, so a lamp's shade can cast shadows of
its own. A point light casts all round, and everything that casts blocks it, around it too: a candle in
a lantern or a carved pumpkin lights the room only through the openings. Give a bulb or flame mesh
drawn at the light `castShadow: false`. The directional shadow is fitted to whatever casts, every
frame; when things fly far off, give the light `shadowBounds: { min: [x, y, z], max: [x, y, z] }` -
the world area that gets shadows - so the map stays sharp there.

```js
scene.add(new PointLight({ position: [0, 0.1, 0], intensity: 0.5, range: 4, castShadow: true }))  // a candle in a jack-o'-lantern
```

Cameras: `new PerspectiveCamera({ fov, near, far, position, target })`,
`new OrthographicCamera({ height, near, far, position, target })` (width follows the aspect). Or
use a View camera preset: `'isometric'` and `'top'` are orthographic.

A plan view and back, for editors and floor plans:

```js
planButton.onclick = () => { view.camera = 'top'; view.controls.mode = 'map' }      // fitted, drags pan
threeDButton.onclick = () => { view.camera = 'perspective'; view.controls.mode = 'orbit' }
```

**Camera recipes** - the camera is moved by `frame()`, by its control, or by setting its `position`
and `target` yourself; the orbit always turns about wherever the target is.

- **Which way is up on screen**: from `'top'`, screen right is +x and screen up is -z (north on a
  map is -z). From `'front'`, right is +x and up is +y.
- **Fly to something**: `view.frame(node, { duration: 1 })` - the glide eases in and out, and a
  press or the wheel takes over.
- **Back to the start**: `view.frame(undefined, { direction: 'perspective', duration: 0.6 })`
  (or the preset the view started with).
- **Where framing would go**: `view.framing(target, { padding, direction })` returns
  `{ position, target, height? }` without moving the camera - for a camera that eases after
  something that keeps changing size (`camera.position.lerp(aim.position, 0.1)`, the same for target).
- **Follow something that moves** - move the camera and its target by as much as it moved, so the
  view keeps its angle and the user can still orbit round it:

  ```js
  let last = null
  view.start(() => {
    if (!followed) return
    const now = followed.updateWorld().worldPosition
    if (last) {
      const moved = now.clone().sub(last)
      view.camera.position.add(moved)
      view.camera.target.add(moved)
    }
    last = now
  })
  // to start: last = null; followed = planet; view.frame(planet) - and to stop, followed = null
  ```
- **Turn to an angle**: `view.controls.spherical = { yaw, pitch, distance }` (see Conventions).
- **Light far from a point light**: point and spot light falls off with the square of distance, so
  intensity scales with distance squared - a sun lighting planets 20 units away wants an intensity
  of about 400 and a `HemisphereLight` fill for their dark sides; things meant to glow regardless
  can be `unlit` or `emissive`.

## Interaction

```js
const view = new View({ canvas: '#c', orbit: true, highlight: '#ffffff',
  tooltip: (hit) => ({ title: hit.datum.name, rows: { Sales: hit.datum.sales } }) })
view.on('click', (hit) => { if (hit) select(hit.datum) })   // hit is null for empty space
view.on('hover', (hit) => show(hit?.datum))                 // fires when the thing under the pointer changes
```

- A **hit** is `{ node, instance, datum, point, distance, normal, face, uv }`. `datum` is the
  `data` row for the instance or point hit, or the node's own `data`.
- The **nearest surface** under the pointer is the hit - a link drawn over a site's top wins the
  hover there. To let one kind of thing through, give it `pickable: false`; to choose among
  everything under the pointer, `view.pickAll(event)` lists every hit, nearest first.
- **Rays of your own** - line of sight, what's below a dropped object, picking in tests: a
  `Raycaster` finds what any ray hits, on the CPU. Set `raycaster.ray.origin` and `.direction`, or aim
  it with `setFromCamera([x, y], camera)` (-1 to 1, y up); `intersect(nodeOrNodes)` returns hits,
  nearest first, as `pickAll` does. `threshold` (default 0.1, world units) is how near a ray must pass
  a point or line to hit it; `near` and `far` limit the distance.

  ```js
  const ray = new Raycaster()
  ray.ray.origin.set(0, 10, 0); ray.ray.direction.set(0, -1, 0)
  const ground = ray.intersect(view.scene)[0]   // what's straight below, or undefined
  ```
- **Tooltip** content: a string (new lines kept), an HTML element, or `{ title, rows }` with rows as
  an object `{ name: value }`. Return null for none. Styled by the `.phoria-tooltip` class.
- **highlight** tints the hovered node, instance or point. A drag never counts as a click.
- Per node: `tooltip`, `highlight`, `onHover`, `onClick` options on any node apply to it and its
  children. A node's `highlight` is the colour for its subtree; it tints the mesh, instance or point
  under the pointer. Add `highlightWhole: true` to tint the whole subtree as one thing (a piece of
  furniture, a machine) whichever part is hovered. Without the View's `highlight`, only nodes with
  their own highlight light up - leave it off to keep floors and walls plain, or keep it and give
  those `highlight: false` (`null` means "the View's").
- `onHover` and `onClick` are the app's own handler for a node; to add more without replacing it
  (an add-on, a second concern), `node.on('hover' | 'click', fn)` - it returns a function that stops
  listening. Both run. A drag has one handler, `onDrag`: one thing moves a node at a time.
- **Dragging**: `onDrag: (drag) => ...` on a node makes its subtree draggable. A press on it starts a
  drag (not an orbit) once the pointer has moved 4 px - until then it can still click - and the click
  after a drag is dropped. `drag` is `{ phase, hit, node, ray, plane, start, point, delta, event }`:
  `phase` is `'start'`, `'move'` or `'end'`; `point` is where the pointer's ray meets `plane`
  (null when it misses), and `delta` is `point - start`. `plane` (`{ normal, point }`) is
  horizontal through the hit unless the handler sets another at `'start'`. The cursor shows grab and
  grabbing.

```js
chair.onDrag = (drag) => {
  if (drag.phase === 'start') from = chair.position.clone()
  else if (drag.point) chair.position.copy(from).add(drag.delta)
}
```

- **Outline**: `outline: '#ffcc00'` or `{ color, width }` (pixels, up to 8; default 2) on a node draws
  a line round its silhouette, over everything - for what is selected, or as an inked edge for a
  drawn look. Set it any time; `null` removes it. Outlines are antialiased - soft edges and round
  corners - as the canvas is; `outlineAntialias: false` on the View (or `view.renderer.outlineAntialias =
  false`, any time) draws them in hard pixel steps instead.
- `view.controls.cancel()` lets go of the orbit gesture in progress, for apps that take over a press.
- **Keyboard and screen readers**: `keyboard: true` on the View makes the canvas a stop in the page's
  tab order. The arrow keys (and Home, End, PageUp, PageDown) step through what can be hovered or
  clicked, in scene order and each mesh's instances in order: each instance, point, surface grid
  point (a mesh with a row per vertex) or row of data under a node with its own `tooltip`, `onClick`,
  `onHover`, `onDrag` or `highlight` - and, when the View has a tooltip or handlers itself, each one
  with data. A mesh with no rows is a stop when it has a name or a handler of its own. A
  `highlightWhole` subtree is one stop. Lines with a row per segment (a network's links) are a stop
  per segment, after everything else. The one stepped to is shown as hovering would show it - tint (`#ffcc00` when no highlight
  is set), tooltip, hover handlers - and Enter or Space clicks it (the handler's event is null);
  Escape leaves it, and moving the pointer takes over. A screen reader hears each one: the tooltip's
  text, else its data, else its name, with "3 of 12" - or `keyboard: { label: (hit) => text }`. The
  canvas is labelled with `description`, or from the scene: each chart's `summary()` ("Sales: bar
  chart of 12 rows by month, sales"), else "3D view of 12 items".
- **Reduced motion**: `reducedMotion` follows the system's setting by default. When on, `frame()`
  with a `duration` jumps, `autoRotate` holds, and chart transitions and flowing links settle at
  once. Motion of your own (a `Timeline`, `onUpdate` spin) can check `view.reducedMotion`.

## Charts: `phoria2/charts`

```js
import { chart } from 'phoria2/charts'

const sales = view.scene.add(chart({
  mark: 'bar',
  data: rows,                         // [{ month: 'Jan', region: 'North', sales: 41 }, ...]
  x: 'month', z: 'region', y: 'sales',
  color: 'region',
  tooltip: ['region', 'month', { field: 'sales', format: { style: 'currency', currency: 'GBP' } }],
}))
view.frame(sales)
sales.update(newRows)                 // animates to the new data
```

A chart is a node with axes, ticks, grid walls, a legend and tooltips built in. Vega-Lite's shape
(`encoding: { x: { field, type } }`, `data: { values }`) is accepted as-is.

- **Marks**: `'bar'` (x and optional z bands, y value), `'point'` (scatter; x, y, z numbers or
  categories), `'line'`, `'area'` (a filled line; `stack: true` stacks series), `'surface'` (x, z grid
  with y heights), `'network'`. There are no pie, donut or gauge marks - build those from
  `extrude` and `outline.arc`.
- **Channels**: `x`, `y`, `z`, `color`, `size`, `opacity`, `label` (text on each mark), `key` (row
  identity for animated updates; default `id`), `detail`. Each is a field name or
  `{ field, type, title, format, scale, axis, priority, legend }`, or a constant: `color: '#4e79a7'`
  (or `{ value: '#4e79a7' }`), `size: 0.2`.
  `scale`: `{ domain, range, scheme, zero, nice, type: 'linear' | 'log' }`; a colour field's `type` picks a ramp
  (quantitative) or a colour per value (anything else), and a ramp's domain can have more than two stops
  (`[0, 50, 100]` for a diverging scheme); schemes: `'category'`,
  `'viridis'`, `'blues'`, `'heat'`, `'cool'`, `'redblue'`. `axis: false` or `{ title, format, ticks }`:
  `ticks` lists the values to mark (`[0, 25, 50, 75, 100]` - the axis reaches them) or says about how
  many (default 5).
- **Formats** (`format` on a channel, an axis or a tooltip field) are `Intl.NumberFormat` /
  `DateTimeFormat` options, or a function `(value) => string`:
  ``y: { field: 'sales', format: (v) => `£${v}k` }`` for values in thousands;
  `{ style: 'currency', currency: 'GBP', notation: 'compact' }` turns 42000 into £42K.
- **tooltip**: `true` (every encoded field), a field name, or a list of fields / `{ field, title, format }`.
  A field named on its own reads as the channel that encodes it - its `title` and `format` - so set
  those once, on the channel. The legend's title is the `color` channel's `title`.
- **Order**: bands follow the data's order, or `scale.domain` when given - `x` left to right, `z`
  front to back (the first `z` category is nearest the viewer). Put the tallest series at the back so
  it doesn't hide the rest: `z: { field: 'region', scale: { domain: ['West', 'South', 'North'] } }`.
- **Options**: `box: [x, y, z]` (the chart's size in world units, default about [10, 6, 6]),
  `stack: true` (bars with no `z` stack by `color`; areas stack), `width` (bar width share, 0-1),
  `legend: false | { position, container, ticks }` (`position`: `'top-right'`, `'top-left'`, `'bottom-right'`,
  `'bottom-left'` inside the canvas; `container`: an element or selector - the legend's HTML goes
  in it as a wrapping row, so give it no fixed height). Categories get swatches that click to hide
  and show; a number colour gets a key - a ramp, highest at the top, with values marked up its side,
  `ticks` as on an axis),
  `theme: 'dark' | 'light'`, `title`, `description` (what a screen reader hears for it; else `chart.summary()`
  makes one from the title and channels), `transition: false | { duration, ease }`,
  `overlap: 'dim' | 'hide' | 'show'` (labels), `highlight` (a colour, false, or for networks
  `'neighbours'` - the default, lighting the node's links and linked nodes - or `'node'`, the node alone), and node options (`position`, ...).
- **Surfaces**: one row per grid point - `x` and `z` are the grid (numbers or categories), `y` the
  height; colour follows `y` unless `color` says otherwise:
  `chart({ mark: 'surface', data: rows, x: 'hour', z: 'day', y: 'load', color: { field: 'load', scale: { scheme: 'heat' } } })`.
- **Networks** - nodes as spheres and links as lines, laid out, labelled and interactive:

  ```js
  const services = [{ id: 'gateway', status: 'ok' }, { id: 'payments', status: 'down' }, ...]
  const calls = [{ source: 'gateway', target: 'payments' }, ...]   // link ends name node ids
  view.scene.add(chart({
    mark: 'network',
    data: { nodes: services, links: calls },
    color: { field: 'status', scale: { domain: ['ok', 'warning', 'down'], range: ['#2ecc71', '#f5a623', '#e74c3c'] } },
    label: 'id',                        // a name label on each node
    size: 'load',                       // optional: node size from a field
    link: { width: 2, color: '#8899aa' },   // or fields: width, color, opacity, flow (moving packets)
    layout: { tiers: 'tier', order: ['edge', 'service', 'data'] },   // or 'force' (default), or 'given' (x, y, z fields)
    highlight: 'neighbours',            // hover lights the node, its links and linked nodes; dims the rest
    tooltip: ['id', 'status'],
  }))
  view.on('click', (hit) => hit && show(hit.datum))   // the node's (or link's) row
  ```

  `source`/`target` name the link fields if they aren't called that; nodes are matched by `id`
  (or the `key` channel). Tiers run top to bottom, each tier a ring that widens further down - from
  the side (`camera: 'front'`, or a low view) they read as levels; `'force'` spreads nodes evenly
  instead. A hit on a node gives the node's row as `hit.datum`, on a link the link's row (it has
  `source` and `target`).
- **Chart object**: `update(rowsOrSpec)`, `filter(fn | null)`, `scales` (e.g. `chart.scales.y(50)`),
  `marks` (the nodes drawing it). Picking a mark gives the original row as `hit.datum`.
- **JSON Schema** for the spec ships with the package: `phoria2/charts/schema.json` - validate a
  spec before rendering it, or hand it to a model generating specs. It covers what JSON can hold: in
  code, `format` can also be a function and `legend.container` an element.

## Editing: `phoria2/edit`

For editors - planners, layout tools, scene builders: a handle to move and turn what is selected, and
undo. Built on `onDrag`, `outline` and `rayAt` above.

```js
import { TransformHandle, History } from 'phoria2/edit'

const history = new History({ onChange: (h) => { undoButton.disabled = !h.canUndo } })
const handle = new TransformHandle({
  view, history,
  snap: { move: 0.5, turn: Math.PI / 12 },               // a half-metre grid, 15 degree turns
  constrain: (placement, target) => fits(target, placement) ? placement : null,
  onChange: (target, phase) => showDistances(target, phase),
})
handle.target = chair                                    // null hides it
chair.outline = '#ffb000'
window.addEventListener('keydown', (e) => { if (e.ctrlKey && e.key === 'z') history.undo() })
```

- **TransformHandle** options: `view` (required), `target`, `move` (`'xz'` across the floor - the
  default - `'xyz'` with an up arrow too, or `false`), `turn` (a ring for turning about the
  vertical; default true), `snap: { move, turn }`, `size` (pixels across the ring; default 120 - it
  grows to go round a big target), `dragTarget` (drag the target itself too; default true),
  `history`, `constrain(placement, target)` and `onChange(target, phase)`. It is drawn over
  everything, the same size on screen at any distance. `constrain` gets `{ position, rotation }`
  (rotation is the turn about y) and returns it changed, `null` to refuse the move, or nothing to
  allow it. `handle.dispose()` removes it.
- **History**: `push({ label, undo, redo })` records something already done; `undo()`, `redo()`
  (each returns false when there is nothing to do), `canUndo`, `canRedo`, `undoCount`, `redoCount`,
  `undoLabel`, `redoLabel`, `clear()`. Options `limit` (default 100) and `onChange(history)`.
  `history.transform(nodes, label?)` notes where nodes are and returns `done(label?)`: call it after
  moving them, and it records the move if there was one.

```js
const done = history.transform(selected)
selected.rotation.y += Math.PI / 2
done('Turn')
history.push({ label: 'Delete desk', undo: () => room.add(desk), redo: () => desk.removeFromParent() })
```

## Models: `phoria2/gltf`

```js
import { loadGLTF } from 'phoria2/gltf'

const model = await loadGLTF('models/chair.glb')     // .glb or .gltf
view.scene.add(model)
view.frame(model)
model.find('Cushion').material.color.set('#2a6')
for (const m of model.meshes) m.castShadow = true
model.play()                                          // its first animation; or model.play('Open')
```

A model has `animations` (each with `play()`, `pause()`, `stop()`, `loop`, `speed`), `cameras` and
`meshes`. Its `toJSON()` is a plain group of its parts, with their vertex data - `create()` builds it
back without `phoria2/gltf`, but the animations, and textures embedded in a `.glb`, aren't kept.
Product-viewer lighting:

```js
view.scene.environment = 'studio.hdr'                // or 'studio' (built in)
view.scene.background = view.scene.environment       // the HDR as a backdrop
view.scene.backgroundBlur = 0.5
```

## Curves and motion: `phoria2/motion`

Curves are in the core: `curve(points, { closed, tension })` is a smooth path through points
(`tension` 0 round to 1 straight), `ellipse({ plane, radius, radiusX, radiusY, radiusZ, center, tilt })`
an orbit (flat in x-z unless `plane` is `'xy'` or `'yz'`). Positions go by distance, so `t = 0.5`
is half way along. A curve has `length`, `at(t)`, `tangentAt(t)`, `points(count)`,
`line({ segments, dash: [on, off] })` (geometry for `Lines`) and `tube({ radius, segments, sides })`
(geometry for a `Mesh`).

`phoria2/motion` plays named steps in order - for stories, explainers and guided tours. Each step is
a function of its own progress (0 before it starts, 0-1 while it plays, 1 once done) and sets the
scene from it, so seeking, stepping back and looping always leave the scene right.

```js
import { curve, Lines } from 'phoria2'
import { Timeline, follow, reveal } from 'phoria2/motion'

const route = curve([[0, 0, 0], [2, 3, 0], [6, 2, 1]])
const trail = view.scene.add(new Lines({ geometry: route.line({ dash: [0.3, 0.15] }), material: { color: 'orange', width: 2 } }))
const story = new Timeline({ loop: true })
story.add(4, (t) => { follow(probe, route, t); reveal(trail, t) }, { label: 'Transfer', ease: 'inOut' })
story.add(2, (t) => { flag.visible = t > 0 }, { label: 'Arrival' })
story.onStep((index, label) => { caption.textContent = label })
view.start((dt) => story.update(dt))
```

- `new Timeline({ loop, speed })`; `add(seconds, run, { label, ease })` with `ease` `'linear'`
  (default), `'in'`, `'out'`, `'inOut'` or a function. `play()`, `pause()`, `seek(seconds)`,
  `seekStep(index | label)`, `onStep(fn)`, and `update(dt)` every frame. Read `duration`, `time`,
  `step`, `label`, `steps`, `playing`.
- `follow(node, curve, t, { orient, forward, up })` puts a node `t` along a curve, facing along it.
  `forward` names the model's nose axis (`'-z'` default; `'+y'` for a rocket modelled upright).
- `face(node, direction, { forward, up })` turns a node to point along a direction.
- `reveal(lines, t)` draws only the first `t` of a `curve.line()`, so a path draws in as it is
  travelled.

## Particles: `phoria2/particles`

```js
import { Emitter, Body } from 'phoria2/particles'

const sparks = view.scene.add(new Emitter({
  rate: 200, velocity: [0, 3, 0], velocitySpread: 1, gravity: [0, -9.8, 0],
  lifetime: [0.8, 1.4], color: ['#ffd27f', '#ff5a1f', '#000'],   // fades through these; end on black
}))
sparks.burst(500, { velocitySpread: 8 })
```

An `Emitter` is a `Points` node that runs itself. Options: `max` (most alive at once, 1000), `rate`
(born per second, 100), `origin`, `originSpread` (a radius), `velocity`, `velocitySpread` (a number
spreads in every direction - explosions; `[x, y, z]` per axis), `lifetime` (seconds or `[min, max]`),
`color` (one, or a list each particle fades through), `gravity`, `drag` (share of velocity lost per
second), `follow` (a node whose position is the origin each frame - a trail), `onParticle(p)`
(every live particle each frame; return false to remove it), plus node and material options; the
default material is small additive points. `burst(count, spawnOptions)`, `clear()`, `set(options)`,
`count`.

`Body` moves any node: `node.onUpdate(new Body({ velocity, gravity, drag }).update)`;
`body.impulse([x, y, z])` kicks it.

## Testing without a GPU

Scene logic, bounds, picking with a `Raycaster` and descriptions all run in Node, with no canvas. A
`NullRenderer` stands in for the WebGL one: `render(scene, camera)` brings world matrices up to date
and counts the frame without drawing. `scene.update(dt, t)` runs the update handlers, as the View's
loop would.

```js
import { NullRenderer, PerspectiveCamera, Scene } from 'phoria2'

const renderer = new NullRenderer()
scene.update(0.016, 0.016)                         // one frame of onUpdate handlers
renderer.render(scene, new PerspectiveCamera({ position: [0, 2, 8] }))
renderer.frameCount                                // 1
```

`renderer.lastFrame` describes what would have been drawn - handy to look at in a debugger, but its
shape isn't part of the API and may change.

## Scenes as plain data

`node.toJSON()` describes a node and its children as plain data, and `create(description)` builds it
back - to save, load, send or generate scenes. A description is a node's constructor options plus a
`type`: `'group'`, `'mesh'`, `'instanced-mesh'`, `'points'`, `'lines'`, `'label'`, the lights
(`'directional-light'`, `'point-light'`, ...), the cameras, `'scene'`, and `'chart'` once
`phoria2/charts` is imported. Geometry is described the same way: a generator and its options, or
vertex arrays. Handlers are behaviour, not data, and are left out - as are `labels` on instanced meshes
and points, whose `text` is a function. Particle emitters can't be described yet.

**JSON Schema** for descriptions ships with the package: `phoria2/schema.json` - validate one before
`create()`, or hand it to a model generating scenes. A chart's own options are in
`phoria2/charts/schema.json`.

**Node types of your own**: give the class a static `type` and register it, and `create()` builds its
descriptions. Options of its own add to its parent's; to write them in descriptions too, add them in
`toJSON()`.

```js
import { Group, registerType } from 'phoria2'

class Beacon extends Group {
  static type = 'beacon'
  static get OPTIONS() { return [...super.OPTIONS, 'blink'] }
  constructor({ blink = 1, ...options } = {}) { super(options); this.blink = blink }
  toJSON() { return { ...super.toJSON(), blink: this.blink } }
}
registerType(Beacon)
create({ type: 'beacon', blink: 2, position: [0, 3, 0] })
```

```js
import { create } from 'phoria2'

view.scene.add(create({
  type: 'group', children: [
    { type: 'mesh', geometry: { type: 'box', size: 2 }, material: { color: 'orange' }, position: [0, 1, 0] },
    { type: 'label', text: 'Crate', position: [0, 2.4, 0] },
  ],
}))
await view.scene.ready   // textures named by url have loaded
```