@solidrt/3d 0.0.60 → 0.0.61

package/AGENTS.md

@@ -167,6 +167,13 @@ pick()/raycast()/overlap()/sweep() skip scene-masked-out meshes like
 invisible ones - unless the query passes its own `{ layers }`, which is
 how a low-poly collision mesh lives undrawn in the scene yet answers
 ground and collision queries (the physics-collider pattern).
+SEALED INTERIORS are the other manual use: from outside, a closed shell
+hides its whole interior, but frustum culling cannot know that and
+there is no occlusion or portal culling. Put the interior, the shell
+and an opening "plug" on their own layers and switch the scene mask by
+the camera's zone (inside, outside, in the doorway) - the reactive
+`<Scene layers>` makes it one signal, and a light's reach is masked
+the same way once lights carry layers.
 Per-view fog: `fog: FogOptions | null` on createView overrides the
 scene's fog for that view (null = unfogged - the clear minimap over a
 fogged scene); absent follows the scene. `overrideMaterial` (Three's
@@ -225,12 +232,13 @@ a zoomed camera or a scaled-up tree). `createLod([{ node, size }, ...],
 levels nearest first, `size` the projected size BELOW which a level
 hands over to the next, the last one's the cull threshold (0 = never
 culled); a level is a direct child (a parentless node is adopted by
-`setLod`, one parented elsewhere is refused, never moved). Every camera write also sets its target's LOD view (eye,
-focal, ortho flag, `lodBias`): the scene and each view pick by their
-own camera (a minimap sees the far level of the same tree), shadow
-tiles by the SCENE camera (a caster draws the level the camera sees, so
-its shadow matches - Unity's and Godot's rule), probe faces pick
-nothing. The gate composes with the frustum and `visible` into the same
+`setLod`, one parented elsewhere is refused, never moved). Every camera
+write is also its target's view for the core, which derives the eye,
+focal and ortho flag it measures with (under `lodBias`): the scene and
+each view pick by their own camera (a minimap sees the far level of the
+same tree), shadow tiles by the SCENE camera (a caster draws the level
+the camera sees, so its shadow matches - Unity's and Godot's rule),
+probe faces by each face's camera. The gate composes with the frustum and `visible` into the same
 instance-count switch, so a still camera re-tests nothing and a thousand
 groups cost no JS per frame; a child of the group that carries no
 `lodSize` is drawn always. Without a `fade` the switch is hard with a
@@ -264,8 +272,14 @@ device. Picking and collision see the level the queried target draws
 (`scene.pick`/overlap/sweep/moveAndSlide the scene's, `view.pick` the
 view's); a collider that must not follow the camera is its own undrawn
 mesh on a collision layer. Nested groups chain. Mesh simplification is
-a bake job, not a runtime one. `examples/lod.tsx` is the shape;
-`probes/3d-lod-bench.tsx` the cost.
+a bake job, not a runtime one, and a far level for EMISSIVE DETAIL is a
+design job: geometry simplifies, point lights do not. Fine lights
+aggregated into bigger dots read as a uniform point cloud from afar;
+what works is folding them into a dim emissive floor under the coarse
+blocks, brightness proportional to the local light density squared,
+visible only through the gaps - and tiny lights kept in the MIDDLE
+level bring the speckle back one level closer. `examples/lod.tsx` is
+the shape; `probes/3d-lod-bench.tsx` the cost.
 
 ### Shadows
 
@@ -317,7 +331,9 @@ PCF taps clamp at face-tile edges, so a face seam hardens slightly
 instead of bleeding into the neighbour.
 `shadow: { cascades: N }` (1..MAX_CASCADES = 4) replaces the box with
 N maps fitted to slices of the SCENE camera's frustum (near ..
-`shadow.distance`, default the camera far; the practical split; each
+`shadow.distance`, default the camera far; the practical split, or
+`shadow.splits` - `N - 1` ascending fractions of that range, Godot's
+shadow_split_1..3 - to push resolution outward or pull it in; each
 slice's bounding sphere as an ortho box along the light, its centre
 snapped to the map's texel grid so edges do not swim; re-fitted
 whenever the scene camera or the light moves) - a receiver samples the
@@ -521,13 +537,16 @@ faces); an instance is just per-entry uniforms (`uColor`) and bindings
 
 ### Pure pieces and checks
 
-The pure pieces (`math.ts`, `order.ts`, `geometry.ts`,
+The pure pieces (`math.ts`, `color.ts`, `geometry.ts`,
 `profile.ts`, `sweep.ts`, `gltf.ts`, `model-file.ts`) are Solid-free and
-GPU-free BY DESIGN so they can be checked headless (and, for the two
-model modules, run under bun in `tools/model.ts`); keep them that way.
+GPU-free BY DESIGN so they can be checked headless and run under bun:
+`src/model-data.ts` re-exports exactly this set as the published
+`@solidrt/3d/model` entry (the bake tool and app bake scripts), and
+`tests/model-data.test.ts` imports it under `bun test`, so a runtime
+import creeping into any of them fails there; keep them that way.
 The rigs under `checks/`
 (`geometry-check`, `sweep-check`, `pick-check`, `dispatch-check`,
-`order-check`, `gltf-check`) run on
+`gltf-check`) run on
 flux from the repo root: `bunx srt bundle -f --stdout
 packages/3d/checks/<name>.ts | target/release/flux -`. Run the ones
 touching what you changed. `raycast-check.tsx` and
@@ -547,15 +566,15 @@ collision claims - two copies of this contract have drifted before.
 
 | Component | Props |
 | --- | --- |
-| `Scene` | `width?`, `height?` (target pixels - both, or neither = FILL, below), `clearColor?`, `camera?` (partial CameraUpdate, `ortho` included - the declarative scene.setCamera; same state as `PerspectiveCamera`, use one form; the camera CONTROLS are not a third form - `OrbitCamera`/`FirstPersonCamera` drive position and target only, so `fov`/`near`/`far` come from here even while a control moves the camera, and the default `far` of 100 is what clips a scene in metres), `background?` (fragment GLSL, or a skybox `{ cube, intensity?, rotation? }`), `environment?` (`{ cube, intensity?, rotation? }`, the cube reflective materials mirror), `fog?` (`{ color, near, far }`, linear by camera distance), `toneMapping?` (`"none"` default, `"aces"`, `"agx"` or `"neutral"`), `exposure?` (default 1), `bloom?` (`{ threshold?, intensity?, radius? }`, the stock bloom on the resolve, reactive), `layers?` (target mask, default 1), `depth?` (`"texture"` exposes scene.depthTexture; not with samples), `samples?` (1/2/4/8 MSAA), `label?`, `ref?(scene)`, `output?(texture)`, `resolve?` (the source, `{ source, textures }`, or a function of the buffer id returning either; fixed at creation - see Color), `events?` (pointer events, default on), `pointer?` (the leaf's pointer feed, fed from the scene's root), `onPointerDown/Move/Up?`, `onWheel?`, `onTap?` (the scene's own handlers, the last stop of the walk - `event.mesh` null over empty space) |
+| `Scene` | `width?`, `height?` (target pixels - both, or neither = FILL, below), `clearColor?`, `camera?` (partial CameraUpdate, `ortho` included - the declarative scene.setCamera; same state as `PerspectiveCamera`, use one form; the camera CONTROLS are not a third form - `OrbitCamera`/`FirstPersonCamera` drive position and target only, so `fov`/`near`/`far` come from here even while a control moves the camera, and the default `far` of 100 is what clips a scene in metres), `background?` (fragment GLSL, or a skybox `{ cube, intensity?, rotation? }`), `environment?` (`{ cube, intensity?, rotation? }`, the cube reflective materials mirror), `fog?` (FogOptions: linear `{ color, near, far }` or exp2 `{ color, density }`, either plus `height`/`heightFalloff` - see Fog), `toneMapping?` (`"none"` default, `"aces"`, `"agx"` or `"neutral"`), `exposure?` (default 1), `bloom?` (`{ threshold?, intensity?, radius? }`, the stock bloom on the resolve, reactive), `layers?` (target mask, default 1), `depth?` (`"texture"` exposes scene.depthTexture; not with samples), `samples?` (1/2/4/8 MSAA), `label?`, `ref?(scene)`, `output?(texture)`, `resolve?` (the source, `{ source, textures }`, or a function of the buffer id returning either; fixed at creation - see Color), `events?` (pointer events, default on), `pointer?` (the leaf's pointer feed, fed from the scene's root), `onPointerDown/Move/Up?`, `onWheel?`, `onTap?` (the scene's own handlers, the last stop of the walk - `event.mesh` null over empty space) |
 | `View3d` | a Scene child rendering the scene again from a camera of its own (scene.createView as a component): `width`, `height` (target pixels, live; fixed-size only for now), `x?`, `y?` (the tile's top-left in `into`, live), `into?` (tile an app-owned draw target - one pass for every view into it; fixed at creation), `camera?` (partial CameraUpdate on the view's camera, live; same state as a `PerspectiveCamera` child), `layers?` (the view's mask, live), `clearColor?`, `label?`, `overrideMaterial?`, `fog?` (FogOptions, or null for none), `depth?`, `samples?`, `filter?`, `wrap?` (createView's, fixed), `ref?(view)`, `output?(texture)` (else a built-in `<texture>` leaf at the target size, a tile shown through srcX/srcY), `resolve?` (as Scene's; not with `into`), `bloom?` (BloomOptions overrides the scene's, null turns it off in this view, absent follows the scene; not with `into`), `events?`, `pointer?` (the view leaf's feed, fed from the view's root), `onPointerDown/Move/Up?`, `onWheel?`, `onTap?` (the view's own handlers); camera-control children drive the VIEW (inside, `useScene()` reports the view as `viewport` and the view's feed as `pointer`); node children mount to the scene as outside, and under the view's leaf get their ordinary pointer handlers, picked through the view's camera (`view.pick`), the view as the root of that walk |
 | `Group` | `position?`, `rotation?` (Euler radians, XYZ order), `quaternion?` (either, not both), `scale?` (number = uniform), `visible?`, the bubbling pointer events (below: down/move/up/wheel/tap from a hit descendant; a group is never the struck node, so it takes no `onPointerEnter`/`onPointerLeave` - `Lod` likewise), `ref?(node)` |
 | `Lod` | a Group whose direct children carrying `lodSize` (a prop every node component takes: the projected size below which that child hands over, see Level of detail) are its levels, sorted by size, never by JSX position; plus `fade?` (the cross-fade band fraction, default 0); a child without `lodSize` is drawn always |
 | `InstancedLod` | as InstancedMesh minus `material`, plus `levels` (`[{ geometry, material, size }]` nearest first, fixed at creation; instanced materials as InstancedMesh's), `castShadow?` (every level); `<Instance>` children populate it as under `InstancedMesh`, each drawing the level its own projected size picks |
-| `Mesh` | `geometry`, `material`, transforms as Group, `params?` (per-mesh uniforms, merge semantics - no unset), `renderOrder?`, `castShadow?`, `layers?` (membership bitmask, default 1), pointer events (below), `ref?(mesh)` |
+| `Mesh` | `geometry`, `material`, transforms as Group, `params?` (per-mesh uniforms, merge semantics - no unset), `renderOrder?`, `castShadow?`, `layers?` (membership bitmask, default 1), `frustumCulled?` (default true; false for geometry a vertex stage moves beyond the node's box - a billboard, a fullscreen quad; see Culling), `cullMargin?` (world units of slack around the box for bounded displacement), pointer events (below), `ref?(mesh)` |
 | `Sprite` | as Mesh minus `geometry`: a camera-facing unit quad, `scale` is its world size, rotation is ignored; pair with a `sprite()` material |
-| `InstancedMesh` | as Mesh (an instanced `material`: a stock one with `instanced`/`instanceColors`, or a class declaring INSTANCE_MATRIX_ATTRIBUTES), plus `capacity?` (instance slots, default 64; the buffers double past it), `bounds?` (optional: instances pick by themselves and the mesh culls by their union), `label?`; a PARENT: `<Instance>` children populate it, `<Group>` children are squads; the record buffers are component-owned and freed on unmount |
-| `Instance` | one instance of the enclosing `InstancedMesh`: transforms, `transition`, pointer events as Group, plus `style?` (the material's style record, one value per component - `[r, g, b, a]` under `instanceColors`), `ref?(instance)`; a parent too (a `<Mesh>` under an instance rides with it) |
+| `InstancedMesh` | as Mesh (an instanced `material`: a stock one with `instanced`/`instanceColors`, or a class declaring INSTANCE_MATRIX_ATTRIBUTES), plus `capacity?` (instance slots, default 64; the buffers double past it), `bounds?` (an optional cull box, never a hit: instances pick by themselves, and without it the mesh culls by their union), `label?`; a PARENT: `<Instance>` children populate it, `<Group>` children are squads; the record buffers are component-owned and freed on unmount, and `anchor?` (a SceneNode, fixed at creation: the ancestor the records are relative to, so `<Instance mesh>` children may sit anywhere under it - see createInstancedMesh) |
+| `Instance` | one instance of the enclosing `InstancedMesh`: transforms, `transition`, pointer events as Group, plus `style?` (the material's style record, one value per component - `[r, g, b, a]` under `instanceColors`), `ref?(instance)`; a parent too (a `<Mesh>` under an instance rides with it), and `mesh?` (the population, fixed at creation, when the instance is placed outside its `<InstancedMesh>` - inside that mesh's `anchor` subtree) |
 | `RecordMesh` | as Mesh, plus `records` (the per-instance records in the material's first instance layout, an ArrayBufferView; buffer capacity starts at the first value and grows on larger rewrites), `count?` (records drawn, default all), `bounds?` (local [minX..maxZ] over the population - without it the mesh never picks); the record buffers are component-owned and freed on unmount |
 | `PerspectiveCamera` | `fov?` (vertical DEGREES, default 60), `near?`, `far?`, `position?`, `lookAt?`, `up?` - or the Scene `camera` prop, the same state (last write wins) |
 | `SpotLight` | transforms as Group, `direction?` (local aim, default [0, -1, 0]), `color?`, `intensity?`, `distance?` (falloff cutoff, 0 = none), `angle?` (cone half-angle DEGREES, default 60), `penumbra?` (0..1 rim fade, default 0), `decay?` (falloff exponent, default 2), `castShadow?`, `shadow?` (mapSize, bias, normalBias, near), `ref?(light)` |
@@ -637,17 +656,27 @@ input.bind(orbitBindings({ pointer, gamepad: gamepad() }))
 
 The vocabulary is shared with @solidrt/2d, one kind and unit per word:
 `rotate` vec2 (orbit turns), `zoom` axis (octaves, positive in), `pan`
-vec2 (element heights), `look` vec2 (turns), `move` vec2 ([right,
-forward], forward = -y in the screen convention), `rise` axis. Keys and
+vec2 (element heights), `focus` axis (a nudge with a focal: a double
+tap's point), `look` vec2 (turns), `move` vec2 ([right, forward],
+forward = -y in the screen convention), `rise` axis. Keys and
 sticks move the CAMERA where a drag moves the content, so the presets
 bind them to `rotate`/`pan` through `invert()`; `look` is the exception,
 a drag and a stick both turn the eye.
 
 ### Orbit camera
 
+The camera controls run one pipeline (okf/design/camera-controls.md):
+a SOURCE (an input nudge, a verb, the follow) writes the pose, the
+FRAMING eases a followed point into its zones, the LANES (a screen
+offset, shakes) are summed on top of the pose, the CONSTRAINTS (the
+clamps, `clampPose`, occlusion) apply, and the PUSH writes the final
+camera. `pose()` is the pose alone; `camera()` the final camera as
+pushed.
+
 Camera control: `createOrbitCamera(scene, { target?, azimuth?, elevation?,
 distance?, min/maxDistance?, min/maxElevation?, orbitSpeed?, rotateSpeed?,
-zoomSpeed?, panSpeed?, damping?, clampPose?, zoomAnchor?, rotateAnchor? })`
+zoomSpeed?, panSpeed?, damping?, push?, panPlane?, follow?, offset?,
+clampPose?, zoomAnchor?, rotateAnchor?, occluder? })`
 - azimuth/elevation/distance around a target with optional auto-orbit. The
 first argument is anything with the scene's `setCamera`, `camera()` (the
 fov maps pan travel to world) and `size()` (the aspect `fit` frames
@@ -656,78 +685,186 @@ Its `axes` are `rotate` (a delta of one element height sweeps one full
 turn, Three's OrbitControls convention, so a drag feels the same on a
 phone and a 4k window; a rate turns at 0.5 turn/s at full deflection),
 `zoom` (octaves: a delta of 1 halves the distance, a rate of 1 halves it
-per second) and `pan` (the target slides so the scene tracks the fingers
-1:1 at the target's depth, three.js DOLLY_PAN, weighted by `panSpeed`). A
-delta bracketed by a gesture (a drag, a pinch, two fingers) applies at
-once, the content staying under the fingers; an unbracketed one (a wheel
-notch, a key step) is an impulse and glides in - `damping` scales that
-settle time, 0 applies it at once - notches compounding on the pending
-value so a fast scroll is one push, the 2d camera's rule and the same
-knob there. The verbs: `rotateBy(azimuth, elevation)` radians,
-`zoomBy(factor, anchor?)` (factor > 1 in, as the 2d camera's zoomAt),
-`panBy(right, up)` world units, `setPivot(point)`, `set(pose)`; every one
+per second - a DOLLY, bounded by the target), `pan` (the target slides so
+the scene tracks the fingers 1:1 at the target's depth, three.js
+DOLLY_PAN, weighted by `panSpeed`; `panPlane: "ground"` slides in the
+plane orthogonal to world up instead, Three's screenSpacePanning off,
+the map's choice) and `focus` (an axis: a nudge with a focal - a double
+tap - glides the target to the point under it through `zoomAnchor`;
+without a focal, to the point under the view centre). A delta bracketed
+by a gesture (a drag, a pinch, two fingers) applies at once, the content
+staying under the fingers; an unbracketed one (a wheel notch, a key
+step) is an impulse and glides in - `damping` scales that settle time, 0
+applies it at once - notches compounding on the pending value so a fast
+scroll is one push, the 2d camera's rule and the same knob there. The
+verbs: `rotateBy(azimuth, elevation)` radians, `zoomBy(factor, anchor?)`
+(factor > 1 in, as the 2d camera's zoomAt), `panBy(right, up)` world
+units, `setPivot(point)`, `setOrbitPoint(point)`, `set(pose)`,
+`shake(strength, duration, { frequency?, direction? })`; every one
 pushes the pose at once. Two commanded moves ease instead, inside
 update(dt): `glideTo({ azimuth?, elevation?, distance?, target? })`, and
-`fit(bounds, { glide? })`, which frames a `[minX, minY, minZ, maxX, maxY,
-maxZ]` box (geometryBounds, a model's `bounds`) - target to its centre,
-distance to where the bounding sphere fills the tighter of the vertical
-and horizontal fov at the target's size, azimuth and elevation kept,
-clamps applied; a snap unless `glide`, so a park-then-snapshot repeats
-(under ortho only the target moves). Any input drops a glide (a finger
-landing holds the view), and a `set()` that writes a pose field snaps
-and drops any motion; `set({})` and `set({ orbiting })` leave it running.
-Every write - input, verb, glide frame, set() - goes through the range
-clamps and then `clampPose(pose)`, which sees the whole pose and returns
-the fields to change: bound where a pan may put the target, or hold the
-eye above a floor (an elevation floor that depends on the distance, which
-a fixed `minElevation` cannot say); a glide's goal is clamped when set
-and its frames as they land, so it never shows an illegal pose.
-Zoom aims at the target unless `zoomAnchor(focal, {eye, target})`
-maps the gesture's focal point - a FRACTION of the element, [0..1, 0..1] -
-to a world point (ground hit, target-depth plane, ...): then that point
-stays pinned under the pointer and the target slides toward it; only the
-app can build that mapping, since it needs the projection
-(scene.unproject over the scene's size). A pinch holds one anchor for its
-whole gesture (the fingers' interleaved events make the span oscillate,
-and re-anchoring per delta turns that into a crawl); the wheel, arriving
-unbracketed, anchors per notch. Pair it with `rotateAnchor({eye, target})`:
-called when a rotate gesture begins, its point is projected onto the
-view axis and re-seats the pivot without moving the picture, so a drag
-after an anchored zoom orbits what the camera looks at, not wherever the
-zoom left the target. Call `orbit.update(dt)` from your onFrame to
-integrate the rates, the auto-orbit and any glide (no frame loop of its
-own), and use its return - true when the pose changed since the previous
-update, nudges included - to gate per-frame dependents like reprojecting
-HUD overlays. `orbiting()` (the auto-orbit switch) and `active()` (the
-frame-loop gate: orbiting with a non-zero rate, a glide or damped notch
-in flight, or any rate driving - the predicate every camera control
-shares) are reactive (HUD-safe); the pose is plain state via
-`pose()`/`set()` (also the debug-command shape). It
-drives position and target only; fov/near/far stay on scene.setCamera
-(or the Scene `camera` prop). The auto-orbit pauses while a gesture is
-open.
+`fit(bounds, { glide? })`, which frames a `[minX, minY, minZ, maxX,
+maxY, maxZ]` box (geometryBounds, a model's `bounds`) - target to its
+centre, distance to where the bounding sphere fills the tighter of the
+vertical and horizontal fov at the target's size, azimuth and elevation
+kept, clamps applied; a snap unless `glide`, so a park-then-snapshot
+repeats (under ortho only the target moves). Any input drops a glide (a
+finger landing holds the view), and a `set()` that writes a pose field
+snaps and drops any motion; `set({})` and `set({ orbiting })` leave it
+running. Every write - input, verb, glide frame, set() - goes through
+the range clamps and then `clampPose(pose)`, which sees the whole pose
+and returns the fields to change: bound where a pan may put the target,
+or hold the eye above a floor (an elevation floor that depends on the
+distance, which a fixed `minElevation` cannot say); a glide's goal is
+clamped when set and its frames as they land, so it never shows an
+illegal pose.
+
+**Push.** `push: true` lets a zoom step past `minDistance` (or
+`maxDistance`) move eye and target together by the overflow - along the
+view axis, or the anchor's ray when the step is anchored, so the point
+under the fingers keeps its pixel - instead of stopping at the floor
+(camera-controls' infinityDolly): the eye's speed is continuous across
+the floor, so a pinch moves THROUGH a model at a speed that scales with
+the distance. Off by default: a dolly that ends at the subject is the
+viewer's default.
+
+**Anchors.** Zoom aims at the target unless `zoomAnchor(focal, {eye,
+target})` maps the gesture's focal point - a FRACTION of the element,
+[0..1, 0..1] - to a world point: then that point stays pinned under the
+pointer and the target slides toward it. A pinch holds one anchor for
+its whole gesture (the fingers' interleaved events make the span
+oscillate, and re-anchoring per delta turns that into a crawl); the
+wheel, arriving unbracketed, anchors per notch. `rotateAnchor({eye,
+target})`, called when a rotate gesture begins, names the point its
+drag should pivot about: projected onto the view axis, it re-seats the
+pivot without moving the picture (`setPivot`), so a drag after an
+anchored zoom orbits what the camera looks at, not wherever the zoom
+left the target. `<OrbitCamera>` builds both from its scene (`anchor`
+below); a function-face caller supplies them (`scene.pick` at the
+focal, `scene.unproject` at the target's depth as the fallback).
+
+**Orbit point and the lanes.** `setOrbitPoint(point)` re-seats the
+pivot EXACTLY: the target becomes the point, the distance its depth, and
+the offset lane takes up the point's sideways offset, so the camera's
+position and orientation do not change and the next drag orbits that
+point (camera-controls' setOrbitPoint with a focal offset) - a viewer
+pushed through a model keeps turning about the model's centre. The
+`offset` option is the lane's persistent half, in view HEIGHTS from the
+centre (x right, y down: `[0.25, 0]` shows the target a quarter of the
+height right of centre - Babylon's targetScreenOffset); `shake` adds
+decaying oscillations to it. Lanes are added on top of the pose at push
+and never enter `pose()`; a verb that writes the target (`set`,
+`glideTo`, `fit`, `focus`) clears setOrbitPoint's share.
+
+**Follow.** `follow(point)` makes the target chase a world point
+through the framing in `follow: { damping?, deadZone?, hardLimits?,
+lookahead?, heading? }` (core's camera-control, shared with the 2d
+camera): damping per view axis (`{ x, y, z }`: right, up, forward - a
+lazy vertical, a tight horizontal), the dead zone and hard limits as
+fractions of the view centred on the target (inside the dead zone the
+point roams free; in the band up to the hard limits it is eased back;
+beyond them it is clamped inside at once, whatever the damping - a fast
+point never leaves the view), lookahead by `time` seconds of the
+point's velocity smoothed over `smoothing` seconds. Cinemachine's
+Orbital Follow: the orbit's own input keeps working around the followed
+point - a rotate orbits it, a zoom dollies toward it, a pan moves the
+target and the follow eases it back. `follow(point, heading)` also
+recentres the azimuth on `heading`, the followed thing's yaw in the
+first-person convention (0 faces -z, positive turns left: a walker's
+`pose().yaw` feeds a chase camera directly), by the shortest turn,
+after `follow.heading.wait` seconds (default 1) without rotate input at
+`follow.heading.damping` - Cinemachine's recentering: a drag looks
+around, the camera settles back behind the walker. Call `follow` every
+frame for a moving point; the control settles once the point rests
+inside the zones and the heading is reached. `unfollow()`, or a verb
+that writes the target, ends it.
+
+**Occlusion.** `occluder(target, eye)` reports the free distance from
+the target toward the eye when something stands between them (null
+otherwise); a free distance under the pose's pulls the FINAL eye in to
+it at once, and the return eases as the obstacle clears (Cinemachine's
+deoccluder damping; Godot's SpringArm3D snaps both ways). The pose's
+distance is untouched: a zoom out from behind a wall still goes where
+the pose says once the wall is gone. `<OrbitCamera occlusion>` builds
+the hook from a scene raycast.
+
+Call `orbit.update(dt)` from your onFrame to integrate the rates, the
+auto-orbit, any glide, the follow, the lanes and the occlusion return
+(no frame loop of its own), and use its return - true when the camera
+changed since the previous update, nudges included - to gate per-frame
+dependents like reprojecting HUD overlays. `orbiting()` (the auto-orbit
+switch) and `active()` (the frame-loop gate: orbiting with a non-zero
+rate, a glide, follow, shake or occlusion return in flight, or any rate
+driving - the predicate every camera control shares) are reactive
+(HUD-safe); the pose is plain state via `pose()`/`set()` (also the
+debug-command shape). It drives position and target only; fov/near/far
+stay on scene.setCamera (or the Scene `camera` prop). The auto-orbit
+pauses while a gesture is open. checks/orbit-check.ts pins every stage
+headless.
 
 In a component tree, skip the wiring: `<OrbitCamera input={input}
 azimuth={1.2} distance={7} />` as a Scene child reaches the scene through
 context (as a `<View3d>` child, that view: the context's `viewport` is
 the nearest owner's), drives from the map in `input` (its `rotate`,
-`zoom`, `pan` actions, or the names in `actions`; live - a new map
-reconnects) and nothing else, and runs a frame loop only while
+`zoom`, `pan`, `focus` actions, or the names in `actions`; live - a new
+map reconnects) and nothing else, and runs a frame loop only while
 `active()`, so a camera moved by drags alone keeps the app demand-driven
-idle. The pose props are initial values: runtime pose changes (and the
-debug-command hookup) go through `ref`'s handle, whose set() and verbs
-push the pose and whose glideTo/fit ease it. Every other prop is live -
-forwarded to the control as a getter and read where it applies, never
-snapshotted - so clamps, rates, `damping` and anchors follow their props
-without a remount, and a clamp change (`clampPose` included) re-clamps
-the pose at once. A `fit` from `ref` at mount reads the scene's size of
-that moment: a fill-mode `<Scene>` has its creation size until its first
-layout, so fit after the first frame (or hand a fixed-size scene).
+idle. The projection-dependent hooks are built here, since the
+component sits where the projection is: `anchor` ("pick", the default:
+the scene under the focal, else the plane at the target's depth;
+"plane": that plane only; false: zoom toward the target, no pivot
+re-seat) fills `zoomAnchor` and `rotateAnchor`, `occlusion={{ radius?,
+layers?, meshes? }}` fills `occluder` from a raycast between target and
+eye (mask the followed character out with `layers`, or name the level's
+meshes); a hook prop overrides its half. The pose props are initial
+values: runtime pose changes (and the debug-command hookup) go through
+`ref`'s handle, whose set() and verbs push the pose and whose
+glideTo/fit ease it. Every other prop is live - forwarded to the
+control as a getter and read where it applies, never snapshotted - so
+clamps, rates, `damping`, the follow's zones, `offset` and anchors
+follow their props without a remount, and a clamp or offset change
+re-clamps the pose at once. A `fit` from `ref` at mount reads the
+scene's size of that moment: a fill-mode `<Scene>` has its creation
+size until its first layout, so fit after the first frame (or hand a
+fixed-size scene). `orbitBindings` is the viewer's wiring (a drag
+rotates, Ctrl-drag, right-drag and two fingers pan, pinch and wheel
+zoom, a double tap focuses); `mapBindings` the map's (a drag pans,
+Ctrl-drag, right-drag and two fingers rotate), paired with `panPlane:
+"ground"`.
+
+### Shots and blends
+
+`createShots(scene | view, { blend? })` (core's blender over the
+scene's CameraState, Cinemachine's virtual cameras): `shot(name, {
+priority? })` returns a target an orbit or first-person control drives
+instead of the scene (its `camera()` is the shot's own, its `size()` the
+owner's) - a chase camera and a cinematic one, each with its own
+control - and `activate(name, { blend? })` makes the highest-priority
+enabled shot live, blending the scene from the current output over
+`blend` seconds (default 0.5; 0 cuts; position, target, up, fov, near
+and far linear, two ortho extents linear, a perspective-to-ortho switch
+cuts at the midpoint; `mixCamera`); `deactivate` falls back by
+priority. A live shot's pushes reach the scene at once; a blend needs
+`update(dt)` while `active()`, the controls' rule. `live()` and
+`camera()` read the state. A switch mid-blend starts from the output of
+that moment, so a quick back-and-forth never jumps. Every shot starts
+from the owner's camera at creation. The component form: `<Shots
+blend? ref?>` as a Scene (or View3d) child with `<Shot name priority?
+active? blend?>` children, each providing a context whose `viewport` is
+the shot's recording target, so an `<OrbitCamera>` or
+`<FirstPersonCamera>` inside a `<Shot>` drives that shot; `active`
+(default true, live) withdraws and restores a shot, an unmount removes
+it, the container runs the blend on frames while one is in flight. A
+shot's picks and raycasts (`anchor`, `occlusion`) go through the
+owner's actual camera, which is the shot's own only while it is live
+and at rest. Pinned in checks/orbit-check.ts; probes/shots-3d-probe.tsx
+is the live guard.
 
 ### First-person camera
 
 First-person control: `createFirstPersonCamera(scene, { position?, yaw?,
-pitch?, min/maxPitch?, moveSpeed?, lookSpeed?, fly?, clampPosition? })` -
+pitch?, min/maxPitch?, moveSpeed?, boostSpeed?, lookSpeed?, fly?,
+clampPosition? })` -
 a position plus yaw/pitch (yaw 0 faces -z, positive turns left; pitch
 positive looks up), Unity's FirstPersonController shape (look AND move in
 one control) where Three splits PointerLockControls from a hand-written
@@ -737,15 +874,24 @@ pointer feed's `mouseDelta` delivers mouse motion under pointer lock in
 the same unit; a rate turns at 0.4 turn/s), `move` ([right, forward],
 forward = -y: a stick pushed up or W reads [0, -1]; a rate walks at
 `moveSpeed`, a delta is a step in world units, diagonals clamped to unit
-length so they walk no faster) and `rise` (world up at `moveSpeed`, fly
-mode only). Walking (the default) flattens the heading onto the ground
+length so they walk no faster), `rise` (world up at `moveSpeed`, fly
+mode only) and `boost` (an axis, since the control has no button kind:
+a bound button reads 1 while held, and any non-zero read multiplies the
+move and rise RATES by `boostSpeed`, default 2 - the sprint; a delta
+stays a one-unit step; `firstPersonBindings` puts it on Shift and the
+left stick's press). Walking (the default) flattens the heading onto the ground
 plane at fixed height; `fly` moves along the view. The verbs:
 `lookBy(yaw, pitch)` radians, `moveBy(right, forward, up?)` in the
 walker's frame, `set(pose)`, and `glideTo({ position?, yaw?, pitch? })`,
 which eases there inside update(dt) (yaw to the number given, not the
 shortest turn), dropped by any input and by a set() of a pose field -
 the orbit camera's glide, without its damping: this control's unbracketed
-delta is mouse motion under pointer lock, and that is never eased. Every
+delta is mouse motion under pointer lock, and that is never eased.
+`shake(strength, duration, { frequency?, direction? })` is the lane
+every control has (okf/design/camera-controls.md), here a view KICK in
+TURNS of yaw and pitch (the look axis's unit; 0.01 is 3.6 degrees), the
+first-person convention: a hit, a recoil, a footstep; the pose and the
+eye are untouched. Every
 option but the initial pose is read
 where it applies (`fly` per step, `clampPosition` per move, the rates and
 pitch clamps per input), so a field changed on the options object takes
@@ -820,7 +966,9 @@ so hits carry `face`, `uv` and a world-space `normal` facing the ray, and
 a ray through a knot's hole misses. A large geometry's triangles are
 BVH-indexed too - built by the first ray that reaches the shape, log-cost
 after - so raycasting a merged static scene stays cheap (see the batching
-advice). An instanced mesh is box-only (its
+advice). An instanced mesh picks per instance (each a leaf with the
+geometry's shape; its own node is never a hit, its `bounds` cull
+only). A record mesh is box-only (its
 explicit population bounds; records are opaque), and so is a mesh whose
 geometry is not a triangle list (lines, points, strips have no triangle
 narrowphase): it is tested by the
@@ -1150,7 +1298,8 @@ opts out of the scene's fog (all four library materials take it).
 
 #### sprite
 
-`sprite({ color?, map?, transparent?, blend?, billboard? })` - unlit on a quad
+`sprite({ color?, map?, transparent?, blend?, billboard?, shape?,
+falloff? })` - unlit on a quad
 that turns to face the camera IN THE VERTEX STAGE (off the shared
 uCamRight/uCamUp, or uCamPos for `billboard: "fixed-y"`, which yaws
 only and stays upright on world y - Godot's BILLBOARD_FIXED_Y, the
@@ -1160,7 +1309,11 @@ defaults to TRUE here (cutouts; Three's SpriteMaterial default), cull is
 off. Draw with `createSprite(material)` / `<Sprite>`: a Mesh over a
 shared unit plane, no geometry argument, `scale` = world size, rotation
 ignored. Picks by a unit box around its center (its reach at any
-facing), so hits carry no normal/face/uv. `examples/sprites.tsx`.
+facing), so hits carry no normal/face/uv. `shape: "radial"` is a
+procedural falloff over the quad's inscribed disc, `(1 - 2|uv -
+0.5|)^falloff` (default 1; 2 a soft puff) multiplying color and alpha,
+so a glow, flare or puff needs no texture; it composes with a `map`
+and with `blend: "add"`. `examples/sprites.tsx`.
 
 #### shaderMaterial
 
@@ -1205,6 +1358,12 @@ Scene-wide values (a clock, a sun direction, fog) go through
 class/instance split for your own GLSL: compiles once, and
 `cls.instance({ params?, textures? })` returns a Material sharing that
 pipeline with its own values. `dispose()` lives on the class alone.
+Seed only the names the material owns: a per-entry param is applied
+AFTER the target's shared params, so a scene-wide name seeded in
+`instance({ params })` (uTime, a sun direction) pins that mesh to the
+seeded value and `scene.setParams` never reaches it again. Declare the
+uniform in the source, leave it out of the instance, and the scene's
+write lands.
 `shaderMaterial(opts)` is exactly a class with one instance (its
 `dispose` forwards to the class).
 
@@ -1259,7 +1418,7 @@ tree, a crowd member), not to submit a lot of vertices. The tell in
 
 #### createInstancedMesh
 
-`createInstancedMesh(geometry, material, { capacity?, bounds?, label? })`
+`createInstancedMesh(geometry, material, { capacity?, bounds?, anchor?, label? })`
 draws the geometry once per instance NODE: `addInstance(mesh,
 transform?, parent?)` returns a scene node (kind "instance") placed
 inside the mesh - setTransform/setTransition/setVisible, lookAt,
@@ -1268,6 +1427,15 @@ matrix RELATIVE to the mesh the spatial core writes into the record
 buffer (`bindMatrixRecord` anchored on the mesh node: one coalesced
 buffer write per flush however many instances moved, so native
 transitions and clip players move instances with zero per-frame JS).
+`anchor` moves that frame to an ANCESTOR the mesh sits under at
+identity: the records are then relative to the anchor and instances may
+be placed under any node of the anchor's subtree, not only under the
+mesh - a population whose copies ride a hierarchy the mesh is not the
+root of (createModel's shared parts: the mesh at identity under the
+model root, an instance under every placement node). The anchor must be
+an ancestor when the mesh is added (it throws otherwise); keeping the
+chain between them identity is the caller's contract, the same one an
+instanced LOD's levels live under.
 The material declares `INSTANCE_MATRIX_ATTRIBUTES` as its first instance
 buffer (four vec4 columns, 16 floats; anything else throws at creation)
 and its vertex
@@ -1378,7 +1546,12 @@ no separate resize plumbing. Two forms:
   later, so a procedural sky written here lights the scene then. A sky
   writes LINEAR light to fragColor (the skybox form does) and the
   scene's resolve exposes, tone maps and encodes it with everything
-  else.
+  else. Derivatives in uniform control flow only: `fwidth()`/`dFdx()`
+  after an early `return` or inside a data-dependent branch are
+  undefined in the 2x2 quads that straddle it, and on Mesa Intel a
+  hash-grid sky with an "empty cell" early out drew stray 1-px lines
+  and L-shapes along every cell edge. Take the derivatives at the top
+  of main, before any branch.
 - A skybox `{ cube, intensity?, rotation? }` (SkyboxOptions): a cube
   map from createCubeTexture sampled along the same ray - Three's
   `scene.background = cubeTexture` with `backgroundIntensity` and
@@ -1703,25 +1876,32 @@ resolve - at one of three tiers, top first:
    params: { uColor: [1, 1, 1, 1], uSpecular: 0.12, uShininess: 24 } })`
    is the white starting point (the stock materials seed exactly this
    from their `color` option).
-2. A SURFACE FUNCTION inside the stock fragment. `phongFragment({ surface,
-   prelude })`: `prelude` is file scope (uniforms and helpers; a uniform
-   it declares is an ordinary `instance()` param), `surface` declares
-   `void surface(inout Surface s)`, called once the program has filled
-   the Surface struct from its options (base from uColor, the map and
-   the vertex color; the normal, bent by the normal map; emissive,
-   ambient, the light model's fields) and before it shades. Rewrite any
-   field or `discard`; it reads the varyings, the declared uniforms and
-   prelude's names, and runs in the shadow twin too, so what it discards
-   casts no shadow. The struct is the contract, no local of the
-   generated program is; colors are linear light, premultiplied
-   throughout, `Surface.base` included. The material describes the
-   surface, the package shades it (Godot's fragment(), Filament's
-   material()). This is the tier for anything whose geometry is not a
-   surface: a point splat discarding outside `gl_PointCoord`'s inscribed
-   circle and flipping a fitted normal towards the viewer keeps the
-   scene's whole light model in about fifteen lines, where hand-rolling
-   the light loop (tier 3) would have to match every light's falloff,
-   cone and shadow by hand.
+2. A SURFACE FUNCTION inside the stock material. `phong({ ..., prelude,
+   surface })` / `standard({ ..., prelude, surface })`: every other
+   option seeds as usual (`color`, the maps, metalness and roughness),
+   `prelude` is file scope (uniforms and helpers; a uniform it declares
+   is an ordinary per-entry param, `params` on the mesh or
+   `setMeshParams`), `surface` declares `void surface(inout Surface s)`,
+   called once the program has filled the Surface struct from the
+   options (base from the color, the map and the vertex color; the
+   normal, bent by the normal map; emissive, ambient, the light model's
+   fields) and before it shades. Rewrite any field or `discard`; it
+   reads the varyings, the declared uniforms and prelude's names, and
+   runs in the shadow twin too (attached whenever a surface is given),
+   so what it discards casts no shadow - with the twin seeing a prelude
+   uniform at its zero value, since mesh params reach the main entry
+   only. One program per distinct source, keyed like every option. The
+   struct is the contract, no local of the generated program is; colors
+   are linear light, premultiplied throughout, `Surface.base` included.
+   The material describes the surface, the package shades it (Godot's
+   fragment(), Filament's material()). This is the tier for anything
+   whose geometry is not a surface: a point splat discarding outside
+   `gl_PointCoord`'s inscribed circle and flipping a fitted normal
+   towards the viewer keeps the scene's whole light model in about
+   fifteen lines, where hand-rolling the light loop (tier 3) would have
+   to match every light's falloff, cone and shadow by hand. The same
+   two slots on `phongFragment` / `standardFragment` are the class form
+   for a custom vertex stage (tier 1 and 2 together).
 3. A FRAGMENT OF YOUR OWN over the scene set. Compose `SCENE` (or
    `sceneSource({ lights, receiveShadow, env, fog })`, each flag leaving a
    declaration out): it declares uCamPos, uHemiSky/uHemiGround, the
@@ -1820,7 +2000,9 @@ is discarded; Three's alphaTest, glTF MASK): opaque, depth-written, no
 sorting, usually with `cull: "none"` for cards, and `instanced: true` /
 `instanceColors: true` for an instanced mesh's population (see
 Instancing: the placement, the depth pass and a per-instance tint with
-no GLSL; the material then draws populated meshes only). Triplanar
+no GLSL; the material then draws populated meshes only), and `prelude`
+/ `surface` for one procedural term inside the stock shading (tier 2
+of Custom looks below; also on `standard`). Triplanar
 is an OPTION, not the default: generators emit 0..1 UVs per face, so a
 map on a plane is a decal (UV) while a map on generated scenery wants one
 density across parts of any size (triplanar); the map must be created
@@ -1892,7 +2074,11 @@ lights at all lights a scene (`examples/environment.tsx`). Light intensities rea
 (1 lights a white matte surface to 1; Godot's and Unity's convention -
 a Three scene's intensities divide by pi). Without an environment a
 metal shows only its highlights: no diffuse, nothing to reflect (Three
-and Godot do the same), so give the scene one. `examples/standard.tsx`
+and Godot do the same), so give the scene one. The same inside a closed
+volume: a dark, mostly-metal surface there gets little diffuse light
+and has little to reflect, so a hemisphere fill barely registers on it
+(a 5x fill and an interior reflection probe both did nothing visible);
+keep directional key and fill lights on inside. `examples/standard.tsx`
 is the sphere grid. Internally one
 `shaderMaterialClass` per option combination (map x vertexColors x
 triplanar x transparent x cull x alphaTest x fog x the surface maps),
@@ -1949,6 +2135,33 @@ naming it, and Draco or meshopt compression throws "re-export without
 mesh compression" - Blender exports Draco by DEFAULT, so that is the
 first error a real file hits.
 
+Reuse is kept, not unrolled. A mesh several nodes reference (Blender's
+linked duplicates export that way) becomes ONE part per primitive with
+`node` = the first node and `placements` = the further ones, and
+`EXT_mesh_gpu_instancing` lands the same way: its per-instance TRS
+become synthesized child nodes of the referencing node, named
+`<node>[i]`, so the hierarchy stays one table and an instance moves
+like any node (Three builds an InstancedMesh, Godot a MultiMesh;
+Unity's importer shares the mesh and lets its batcher instance).
+What cannot share one geometry stays a part per node: a skinned use
+(bind-pose model space, placed by its skin), a morphed one (its
+weights are the node's), and a placement whose rest-pose world
+MIRRORS the first's (opposite determinant sign - the winding flip is
+baked into the indices, so one index order cannot serve both). The
+file's `extras` ride through where glTF puts them, the way Three fills
+`userData` and Godot node metadata: `data.extras` (root), `node.extras`,
+`part.extras` (the glTF MESH's) and `material.extras`, each present
+only when non-empty - so a collider box authored as a Blender custom
+property arrives with the model. Parts come out in WALK order (each
+where its first placing node was visited, a node's primitives in
+order), and the parts a primitive cannot fold still share its built
+geometry: two skinned placements are two parts over ONE `Geometry`
+object, a mirrored copy shares the vertex buffer with its own index
+order - and the container writes each object and each buffer once
+(`decodeModel` restores the identities, so the runtime uploads them
+once too). A document with no `scene`/`scenes` draws everything from
+its true roots; a hierarchy reaching a node twice (a cycle) throws.
+
 #### createModel
 
 `createModel(data, { material?, label?, autoFree? })` - uploads the images (repeat
@@ -1962,14 +2175,32 @@ Blinn-Phong look, or any other material; it is called once per material and shar
 Groups with the file's local TRS, and one mesh per part under its node,
 all inside the returned `Model` (a Group): `add(scene.root, model)`,
 place it with `setTransform`, find parts by name in `model.parts`
-(`{ name, mesh }`), spin a wheel relative to its axle through
-`model.nodes` (`{ name, node }` in table order, parents first; names
+(`{ name, mesh, extras? }`), spin a wheel relative to its axle through
+`model.nodes` (`{ name, node, extras? }` in table order, parents first; names
 repeat when the file's do - `.find()` yours), `model.bounds` for
-framing a camera. Skinned parts get the `skinned: true` material
+framing a camera, `model.extras` and `model.blobs` for the app data a
+file or a bake carried. Skinned parts get the `skinned: true` material
 variant and hang off the model ROOT (the spec ignores their node's
-transform; the palette places them - see the mixer below). `dispose()`
-detaches it and frees the geometry buffers and textures - the model owns
-them, nothing else frees them.
+transform; the palette places them - see the mixer below). A part with
+`placements` is a POPULATION: one InstancedMesh at identity under the
+model root (its `anchor`, see Instancing), `instanced: true` material
+variant, with an instance node at identity under every placement node
+- `part.instances`, in placement order, the part's own node first - so
+the copies are one draw entry (`/gpu` shows one entry labelled with the
+part's name, `instanceCount` = placements + 1; every mesh's entry
+carries its geometry's label there) and still ride the hierarchy: move,
+hide or animate the placement node in `model.nodes` and its copy
+follows; a pick lands on the copy (`hit.mesh` the part's mesh,
+`hit.instance` the instance, whose `parent` is the placement node);
+culling is per copy through the mesh's instance union. The one thing a
+population cannot do per copy is a material swap - `setMaterial` on the
+part's mesh restyles every copy; per-copy tint is `setInstanceStyle`
+under a material with `instanceColors`. The `material` callback's
+last flag is `instanced` (after `skinned`, `vertexColors`, `morphed`):
+pass it through, or the instanced draw has no matrix to read.
+`dispose()` detaches it and frees the geometry buffers, a population's
+record buffers and the textures - the model owns them, nothing else
+frees them.
 
 #### loadGltf and loadModel
 
@@ -1990,6 +2221,32 @@ models and a binary import (`import bytes from "./x.glb" with { type:
 "binary" }` then `createModel(parseGltf(bytes))`, see
 `examples/model.tsx`); bake anything big.
 
+#### Baking your own geometry
+
+Geometry an app GENERATES (a terrain, a city block, a hundred thousand
+vertices of anything) pays the same interpreter cost every start; when
+it does not depend on runtime input, bake it once too. The whole data
+side of the package - the parser, the container and the pure geometry
+kit (generators, `withAttribute`, `mergeGeometries`, `transformGeometry`,
+the sweeps and profiles, the math) - is published without the runtime
+as `@solidrt/3d/model`, so a bake script runs under `bun` with no
+`flux:*` shim:
+
+```ts
+import { box, encodeModel, transformGeometry } from "@solidrt/3d/model"
+import type { ModelData } from "@solidrt/3d/model"
+// nodes in pre-order, one part per drawable (a part several nodes place
+// takes `placements`), materials as glTF-shaped records, app data in
+// `extras` (JSON) and `blobs` (named bytes, each an aligned block).
+let data: ModelData = { nodes, parts, skins: [], clips: [], materials, images: [], bounds, extras: { spawn }, blobs: { grid } }
+await Bun.write("assets/level.srtm", encodeModel(data))
+```
+
+`loadModel("assets/level.srtm")` then builds it like any authored model;
+`model.extras` and `model.blobs` hand the app data back (blobs are views
+onto the loaded bytes). `srt tool 3d/model` is the same entry applied
+to a glTF, so the two bakes share one code path.
+
 ### Async loading
 
 Loading is async everywhere but the binary import: loadGltf/loadModel
@@ -2036,7 +2293,10 @@ WITH a skin over the body's joints and WITHOUT clips, so beside an
 animated body they hold their bind pose. `bindSkeleton(body, piece)`
 drives them from the body's skeleton - Three's SkinnedMesh.bind, Unity's
 `bones =`, Godot's shared Skeleton3D. The piece's palette rows re-bind
-onto the body's joint nodes (matched by name, case-insensitive) with
+onto the body's joint nodes (matched by name, case-insensitive; a
+pipeline whose names differ by a prefix or suffix - Mixamo's
+`mixamorig:`, a one-sided `_JNT` - passes `{ match: pieceName =>
+bodyName }`, Unity's leave-it-to-the-app in one option) with
 the piece's own inverse binds, so the flush writes the body's pose into
 the piece's skin and no per-frame code exists; joints with no body
 counterpart (a hat's internal bones) and rigid parts hanging off a
@@ -2106,11 +2366,9 @@ write) - read poses with `getTransform(node)`, which reads the core;
 writes to such a node always go through (setTransform skips its
 usual equal-value short-circuit there, so a teleport back to the last
 JS-written spot is not lost); (3) a channel nothing plays leaves the node's pose
-alone; (4) known gap: native pose writes bypass the scene's moved list,
-so a TRANSPARENT mesh parented under a player-animated joint does not
-re-trigger the back-to-front re-sort while it animates (opaque meshes,
-palettes and picking are unaffected) - nudge the scene with any
-setTransform if it shows, until the core-side transparent sort lands.
+alone; the draw sort follows native pose writes like any move (the core
+re-keys what it recomputed), so an animated transparent sorts as it
+animates.
 
 ### Root motion
 
@@ -2256,6 +2514,21 @@ with `srt tool 3d/model`.
   half-blend of EXTREME targets can show a ragged self-shadow
   terminator where the lit and shadowed halves disagree; a modeller's
   blend shapes are far too small for it to show.
+- A shared part (`part.instances` set) has ONE mesh for every copy, at
+  identity under the model root: hiding it hides all copies, swapping its
+  material restyles all, moving it is wrong (its records are anchored on
+  the root - see the instancing traps). Per-copy identity lives on the
+  placement nodes in `model.nodes` and on `part.instances` - hide, move,
+  animate and pick those. A file that references one mesh from nodes on
+  both sides of a mirror yields two parts (one per winding sign), so
+  `model.parts.find` by name may find the unmirrored one only; the
+  mirrored copy carries the mirroring node's name.
+- `createModel` refuses a skinned or morphed part with `placements`
+  (thrown, not drawn wrong): parseGltf never folds those, so this only
+  comes from a hand-built ModelData - give each copy its own part.
+- `extras` fields exist only where the file HAD data (an empty object
+  is dropped), so read them with `?.` - `model.extras?.spawn`, not
+  `model.extras.spawn`.
 
 ### Materials and color
 
@@ -2282,15 +2555,32 @@ with `srt tool 3d/model`.
   behind opaques without occluding other translucents). The one inference:
   a stock material or `shaderMaterial` with any `blend` but "none" is transparent
   unless told `transparent: false` - every blended draw belongs after the opaques, and
-  back-to-front is harmless for add/multiply. The scene owns the
-  order: background, opaque meshes by `renderOrder` then add order,
-  transparent meshes by `renderOrder` then back-to-front by the CENTER of
-  the mesh's world bounds in view space (not the origin: off-origin geometry
-  sorts by where it is; not the nearest bounds point: a big translucent
-  ground plane would cover the small translucents on it) - one `setDrawOrder` from sync() whenever the list changed, a
-  renderOrder changed, or (with two or more transparent meshes) the camera
-  or a transparent mesh moved, and skipped when the resort lands on the
-  permutation already issued. Per-mesh sort only: one non-convex translucent
+  back-to-front is harmless for add/multiply. The spatial core owns the
+  order of every scene and view target (`setDrawSort`; each mesh's bind
+  carries its queue and renderOrder): four queues - the background,
+  bound to the scene root and pinned first whatever the camera does,
+  opaque meshes front-to-back by their distance to the camera, cutout
+  meshes (any `alphaTest`, a `shaderMaterialClass({ cutout: true })`)
+  after them the same way because their discard defeats early-z, and
+  transparent meshes back-to-front by their view-space depth -
+  `renderOrder` above depth inside each queue, never across queues,
+  all measured at the CENTER of the mesh's world bounds (not the origin:
+  off-origin geometry sorts by where it is; not the nearest bounds point:
+  a big translucent ground plane would cover the small translucents on
+  it), add order breaking ties. The opaque and cutout key is coarse on
+  purpose - a logarithmic distance bucket, four per doubling - because
+  early-z only needs near layers before far ones, and a coarse key keeps
+  the order (and the meshes' add-order material grouping within a bucket)
+  stable while the camera moves: a look-around changes no distance, and a
+  step shorter than 16% of the nearest bucketed center's distance can
+  cross no bucket edge, so neither re-sorts. Dense geometry added
+  base-first therefore no longer needs the app to sort it (Godot and
+  Unity sort opaques the same way, Three exactly). The core issues one
+  `setDrawOrder` per target from the flush whenever a mesh was added,
+  removed or re-keyed, a node moved, or the camera moved (with a
+  transparent bound, or past that bucketed step), and skips it when the
+  resort lands on the permutation already issued. Per-mesh sort only:
+  one non-convex translucent
   mesh still overlaps itself in vertex order, and two large interpenetrating
   translucents can sort wrong (center distance, not per-pixel) - that is the
   engine contract, no OIT. A `shaderMaterial({ transparent: true })`
@@ -2493,6 +2783,13 @@ with `srt tool 3d/model`.
   core before freeing the buffer, so the destroyed instances' hiding
   writes land in a live buffer; keep that order if you ever free a
   record buffer by hand.
+- An anchored population (`createInstancedMesh` with `anchor`) draws
+  `uModel * record`, and the record is relative to the ANCHOR: the
+  copies land right only while the mesh's world equals the anchor's.
+  Moving the mesh itself (or any group between it and the anchor) shifts
+  every copy twice; move the anchor, the instances or their parents
+  instead. A model's shared parts are anchored this way - `setTransform`
+  on `model.parts[i].mesh` of a part with `instances` is the mistake.
 
 ### Shadows
 
@@ -2602,11 +2899,13 @@ with `srt tool 3d/model`.
 
 ### Picking, pointer and collision
 
-- Picking is triangle-accurate for ordinary meshes (`point` is a surface
-  point, hits carry `face`/`uv`/`normal`) but box-only for instanced
-  meshes and for lines/points geometry: there `point` is where the ray
-  meets the population `bounds` box (the geometry's box for lines),
-  `normal` that face's, and `face`/`uv` are absent. Never present an
+- Picking is triangle-accurate for ordinary meshes and for instances
+  (`point` is a surface point, hits carry `face`/`uv`/`normal`; an
+  instanced mesh's own node is never struck, its `bounds` only cull)
+  but box-only for record meshes and for lines/points geometry: there
+  `point` is where the ray meets the population `bounds` box (the
+  geometry's box for lines), `normal` that face's, and `face`/`uv` are
+  absent. Never present an
   instanced hit as a surface hit. Both tiers run in the spatial core (Rust); never
   add a per-triangle path in JS - rays at mesh scale are
   interpreter-hostile, and the core already does it.
@@ -2642,10 +2941,8 @@ with `srt tool 3d/model`.
   lies flat with the hole on y, discs and cylinder caps get a PLANAR disc
   map inscribed in the unit square) but the doc comment is the source.
 - Entry rebuild order: `setGeometry`/`setMaterial` re-add the entry at the
-  list END and dirty the order, so the next sync() re-sorts and the mesh
-  keeps its place. `_transparent` on the mesh is the flag AS ATTACHED
-  (setMaterial swaps `mesh.material` before the rebuild, so _detach must
-  not read the new material's flag).
+  list END and rebind it with the new material's key, so the core's next
+  flush re-sorts and the mesh keeps its place.
 - `lathe` takes a CLOSED profile (a cross-section with thickness, or run
   to the axis at x = 0) - it is a solid of revolution, NOT Three's open
   polyline shell. An "open" outline must be closed by the author;