phoria2 1.0.0 → 1.2.0

package/llms-full.txt

@@ -15,8 +15,8 @@ editors that drag, snap and undo. Picking, tooltips, hover highlights, HTML labe
 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 fresnel or
-custom effects), no clearcoat, and no shadow-softness setting.
+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
 
@@ -114,9 +114,13 @@ const view = new View({ canvas: '#c', orbit: true })
 | `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`.
+(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:
 
@@ -164,7 +168,7 @@ something changes):
 ## Scene graph
 
 Everything in a scene is a node. Node options (all optional): `name`, `position`, `rotation`
-(Euler XYZ radians, `[x, y, z]`), `quaternion`, `scale` (number or `[x, y, z]`), `visible`,
+(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.
 
@@ -229,7 +233,11 @@ 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()`.
+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]
@@ -237,7 +245,8 @@ pixels), `priority` (higher wins when labels overlap), `overlap` (`'hide'` | `'d
 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).
+`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
@@ -250,6 +259,21 @@ clicking that bar, with the same hit. Other labels let the pointer through to th
 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):
@@ -285,8 +309,11 @@ extrude({
 })
 ```
 
-Your own: `new Geometry({ positions, normals?, uvs?, colors?, indices? })` - flat arrays, xyz per
-vertex; `colors` are rgb 0-1 per vertex (use `material: { vertexColors: true }`).
+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
 
@@ -296,7 +323,14 @@ One material type, given as a plain object:
 { 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
+{ 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
 ```
@@ -313,7 +347,8 @@ Properties: `color`, `opacity`, `roughness` (0.5), `metalness` (0), `emissive`,
 (`'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`; `size`/`sizeAttenuation` for Points, `width` for Lines. Change later through
+`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).
 
@@ -324,6 +359,83 @@ into the distance. A cut-out (`alphaTest`) casts the shadow of what is left of i
 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. `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
@@ -339,7 +451,7 @@ on top, as with UVs (animate `offset` to scroll a pattern). 0 (the default) uses
 |---|---|
 | `AmbientLight` | `color`, `intensity` |
 | `HemisphereLight` | `sky`, `ground`, `intensity` |
-| `DirectionalLight` | `color`, `intensity`, `direction` (the way it travels, e.g. `[-1, -2, -1]`), `castShadow` |
+| `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` |
 
@@ -357,7 +469,9 @@ meshes opt in with `castShadow` and `receiveShadow`. No shadow camera to set up.
 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`.
+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
@@ -383,6 +497,9 @@ and `target` yourself; the orbit always turns about wherever the target is.
   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:
 
@@ -438,7 +555,8 @@ view.on('hover', (hit) => show(hit?.datum))                 // fires when the th
   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.
+  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.
@@ -458,8 +576,27 @@ chair.onDrag = (drag) => {
 ```
 
 - **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. Set it any time; `null` removes it.
+  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`
 
@@ -511,7 +648,8 @@ A chart is a node with axes, ticks, grid walls, a legend and tooltips built in.
   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`, `transition: false | { duration, ease }`,
+  `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phoria2",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Small, friendly 3D for the web - a WebGL 2 renderer with charts, labels, picking, particles and glTF",
   "keywords": [
     "3d",
@@ -85,10 +85,13 @@
     "plugin": "node scripts/plugin.mjs"
   },
   "devDependencies": {
+    "@dimforge/rapier3d-compat": "^0.21.0",
     "@eslint/js": "^10.0.1",
     "eslint": "^10.3.0",
     "gl-matrix": "^3.4.4",
     "globals": "^17.6.0",
+    "manifold-3d": "^3.5.4",
+    "recast-navigation": "^0.44.0",
     "three": "0.186.1",
     "typescript": "^7.0.2",
     "vite": "^8.0.12",

package/schema/scene.schema.json

@@ -202,6 +202,11 @@
                   "type": "null"
                 }
               ]
+            },
+            "minScale": {
+              "type": "number",
+              "description": "Show the label only when zoomed in this far: CSS pixels to one world unit at its point (0, always).",
+              "minimum": 0
             }
           },
           "unevaluatedProperties": false
@@ -327,6 +332,16 @@
             },
             "castShadow": {
               "type": "boolean"
+            },
+            "shadowBounds": {
+              "type": ["object", "null"],
+              "description": "The part of the world, in world units, that has shadows; null (the default) follows what casts.",
+              "required": ["min", "max"],
+              "properties": {
+                "min": { "$ref": "#/$defs/vec3" },
+                "max": { "$ref": "#/$defs/vec3" }
+              },
+              "additionalProperties": false
             }
           },
           "unevaluatedProperties": false
@@ -462,13 +477,16 @@
           "description": "Anything of your own."
         },
         "highlight": {
-          "description": "Hover tint for this subtree, or null for none.",
+          "description": "Hover tint for this subtree; false for none, null to use the View's.",
           "anyOf": [
             {
               "$ref": "#/$defs/color"
             },
             {
               "type": "null"
+            },
+            {
+              "const": false
             }
           ]
         },
@@ -703,6 +721,23 @@
           "minItems": 2,
           "maxItems": 2
         },
+        "rotation": {
+          "type": "number",
+          "description": "Turns the image on the surface, in radians, about center."
+        },
+        "center": {
+          "type": "array",
+          "description": "The point rotation turns about, in repeated UVs ([0, 0], the corner, by default).",
+          "items": {
+            "type": "number"
+          },
+          "minItems": 2,
+          "maxItems": 2
+        },
+        "uvSet": {
+          "enum": [0, 1],
+          "description": "Which UV set to read: 0 the first, 1 the second (uvs2) - baked occlusion and light maps usually come on the second."
+        },
         "filter": {
           "enum": ["linear", "nearest"]
         },
@@ -801,6 +836,28 @@
             }
           ]
         },
+        "lightMap": {
+          "description": "Light baked into a texture, added as light from all round - usually on the second UV set.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/texture"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "matcap": {
+          "description": "A picture of a lit sphere that gives the whole look - clay, wax, chrome - picked by which way the surface faces the camera; lights are ignored.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/texture"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "unlit": {
           "type": "boolean",
           "description": "Ignore lights: draws exactly its colour."
@@ -873,6 +930,15 @@
           "minimum": 0,
           "maximum": 1
         },
+        "lightMapIntensity": {
+          "type": "number",
+          "minimum": 0
+        },
+        "environmentIntensity": {
+          "type": "number",
+          "description": "This material's share of the environment's light and reflections (1).",
+          "minimum": 0
+        },
         "triplanar": {
           "type": "number",
           "description": "Repeats per unit, projecting maps from three axes instead of using UVs; 0 uses the UVs.",
@@ -881,6 +947,78 @@
         "bumpScale": {
           "type": "number"
         },
+        "transmission": {
+          "type": "number",
+          "description": "How much light passes through, as through glass: reflections stay whole, and less of what is behind shows towards the edges. Unlike opacity, which fades the whole surface.",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "clearcoat": {
+          "type": "number",
+          "description": "A clear glossy layer over the surface - car paint, lacquer, varnish.",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "clearcoatRoughness": {
+          "type": "number",
+          "description": "How glossy the coat is, 0 a mirror.",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "sheen": {
+          "type": "number",
+          "description": "The soft bright rim of cloth at grazing angles - velvet, felt, upholstery.",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "sheenColor": {
+          "$ref": "#/$defs/color"
+        },
+        "sheenRoughness": {
+          "type": "number",
+          "description": "A thin bright rim at 0, a broad soft glow at 1.",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "ior": {
+          "type": "number",
+          "description": "Index of refraction: how strongly a non-metal reflects - water 1.33, glass and plastic 1.5 (the default), diamond 2.4.",
+          "minimum": 1
+        },
+        "specularIntensity": {
+          "type": "number",
+          "description": "Scales a non-metal's reflections, 0 for none.",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "specularColor": {
+          "$ref": "#/$defs/color"
+        },
+        "anisotropy": {
+          "type": "number",
+          "description": "Brushed metal: highlights drawn out along the brushing, which runs along the UVs' u.",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "anisotropyRotation": {
+          "type": "number",
+          "description": "Turns the brushing from the UVs' u, in radians."
+        },
+        "translucency": {
+          "type": "number",
+          "description": "Light through thin surfaces, lighting them from behind - leaves, paper, lampshades.",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "translucencyColor": {
+          "$ref": "#/$defs/color"
+        },
+        "toon": {
+          "type": "number",
+          "description": "Cartoon shading in this many flat tones (2 or more), with a hard-edged highlight; 0 is smooth.",
+          "minimum": 0,
+          "maximum": 16
+        },
         "blending": {
           "enum": ["normal", "additive", "multiply"]
         }
@@ -1129,6 +1267,13 @@
                 "type": "number"
               }
             },
+            "uvs2": {
+              "type": "array",
+              "description": "A second UV set, for baked occlusion and light maps.",
+              "items": {
+                "type": "number"
+              }
+            },
             "colors": {
               "type": "array",
               "items": {

package/src/OrbitControl.js

@@ -255,8 +255,12 @@ export class OrbitControl {
     this.target.add(move)
   }
 
-  /** Apply inertia and auto-rotate; the View calls this each frame. @param {number} dt seconds */
-  update(dt) {
+  /**
+   * Apply inertia and auto-rotate; the View calls this each frame.
+   * @param {number} dt seconds
+   * @param {boolean} [still] hold auto-rotation - the View passes its reducedMotion
+   */
+  update(dt, still = false) {
     if (!this.enabled) return
     if (this.#pointers.size === 0) {
       const v = this.#velocity
@@ -267,7 +271,7 @@ export class OrbitControl {
         v.yaw *= keep
         v.pitch *= keep
       }
-      if (this.autoRotate) this.rotate(-(this.autoRotate === true ? 0.5 : this.autoRotate) * dt, 0)
+      if (this.autoRotate && !still) this.rotate(-(this.autoRotate === true ? 0.5 : this.autoRotate) * dt, 0)
     }
   }
 

package/src/Raycaster.js

@@ -10,6 +10,7 @@ import { BVH_MIN_TRIANGLES, bvhOf, walk } from './geometry/bvh.js'
 /** @import { InstancedMesh, Lines, Mesh, Points } from './scene/drawables.js' */
 
 /** The section plane cutting what is being tested: world plane, and whether its cut faces are filled. @typedef {{ plane: Float32Array, cap: boolean }} Cut */
+/** @internal A surface ready for many rays: a mesh or one instance, with its world matrix and bounding sphere. @typedef {{ node: any, world: Float32Array, instance: number | null, cut: Cut | null, x: number, y: number, z: number, radius: number }} Solid */
 
 // Nodes are told apart by markers (drawMode, instanceMatrices) rather than instanceof, so picking
 // doesn't pull every node class into an app's bundle.
@@ -119,6 +120,63 @@ export class Raycaster {
     return hits.filter((h) => h.distance >= this.near && h.distance <= this.far).sort((x, y) => x.distance - y.distance)
   }
 
+  /** @internal
+   * The solid surfaces of a frame's draw list, ready for many rays: each mesh and each instance with its
+   * world matrix and bounding sphere worked out once, rather than once per ray - for label occlusion,
+   * which casts a ray per label.
+   * @param {{ node: Node, worldMatrix: Float32Array, instances: { count: number, instanceMatrices: Float32Array } | null, clip: { plane: Float32Array, cap: unknown } | null }[]} items
+   * @returns {Solid[]}
+   */
+  static solids(items) {
+    /** @type {Solid[]} */
+    const out = []
+    for (const item of items) {
+      const n = /** @type {any} */ (item.node)
+      if (n.drawMode !== 'triangles' || !n.geometry.vertexCount) continue
+      const box = n.geometry.bounds, center = box.getCenter(), radius = box.getRadius()
+      const cut = item.clip ? { plane: item.clip.plane, cap: !!item.clip.cap } : null
+      /** @param {Float32Array} world @param {number | null} instance */
+      const add = (world, instance) => {
+        const c = center.clone().applyMatrix4(world)
+        const scale = Math.max(Math.hypot(world[0], world[1], world[2]), Math.hypot(world[4], world[5], world[6]), Math.hypot(world[8], world[9], world[10]))
+        out.push({ node: n, world, instance, cut, x: c[0], y: c[1], z: c[2], radius: radius * scale })
+      }
+      if (item.instances) {
+        for (let i = 0; i < item.instances.count; i++) {
+          add(mat4.multiply(new Float32Array(16), item.worldMatrix, item.instances.instanceMatrices.subarray(i * 16, i * 16 + 16)), i)
+        }
+      } else add(Float32Array.from(item.worldMatrix), null)
+    }
+    return out
+  }
+
+  /** @internal
+   * Whether the ray meets any of these solids nearer than `distance` - the first one found settles it,
+   * so nothing is sorted. One node, or one instance of it, can be left out: what a label is on.
+   * @param {Solid[]} solids from Raycaster.solids() @param {number} distance
+   * @param {Node | null} [skip] @param {number | null} [skipInstance] null for the whole node
+   * @returns {boolean}
+   */
+  blocked(solids, distance, skip = null, skipInstance = null) {
+    const o = this.ray.origin, d = this.ray.direction
+    /** @type {Hit[]} */
+    const hits = []
+    for (const s of solids) {
+      if (s.node === skip && (skipInstance === null || s.instance === skipInstance)) continue
+      // its bounding sphere first: missed, or wholly beyond the distance or behind the ray, it can't block
+      const ox = s.x - o[0], oy = s.y - o[1], oz = s.z - o[2]
+      const along = ox * d[0] + oy * d[1] + oz * d[2]
+      const off = ox * ox + oy * oy + oz * oz - along * along, r2 = s.radius * s.radius
+      if (off > r2) continue
+      const half = Math.sqrt(r2 - off)
+      if (along - half > distance || along + half < 0) continue
+      hits.length = 0
+      this.#mesh(s.node, s.world, s.instance, hits, s.cut)
+      if (hits.length && hits[0].distance < distance) return true
+    }
+    return false
+  }
+
   /** @internal
    * Where the ray meets one instance, point or segment of a drawable - the CPU half of GPU picking,
    * which finds what is under the pointer and leaves the exact point, face and uv to this.