@solidrt/3d 0.0.58 → 0.0.60

package/AGENTS.md

@@ -24,6 +24,7 @@ Contents:
   - [Rendering is the runtime's](#rendering-is-the-runtimes)
   - [Views and layers](#views-and-layers)
   - [Culling](#culling)
+  - [Level of detail](#level-of-detail)
   - [Shadows](#shadows)
   - [Retargeted motion](#retargeted-motion)
   - [Geometry layout, indices and topology](#geometry-layout-indices-and-topology)
@@ -56,7 +57,7 @@ Contents:
   - [Lighting GLSL](#lighting-glsl)
   - [Custom looks: three tiers](#custom-looks-three-tiers)
   - [Lights](#lights)
-  - [lit](#lit)
+  - [phong](#phong)
   - [standard](#standard)
 - [Models](#models)
   - [Three layers](#three-layers)
@@ -103,16 +104,24 @@ nothing itself.
 
 ### Node lifecycle
 
-Node lifecycle: `add(parent, child)` attaches (re-parenting detaches
-first), `remove(child)` DETACHES an intact subtree - children stay
-under the removed node, core nodes free on leave and recreate on
-re-enter, so a removed subtree re-adds cleanly. Nothing is destroyed
-except instance record buffers (`disposeInstances`) and the scene
-itself. (@solidrt/2d's `removeGroup` DESTROYS its subtree instead - a
-sprite cannot exist outside its layer, so there remove means destroy.)
-An instance node (addInstance on an instanced mesh) follows the 2d
-rule: slot-bound to its mesh, `removeInstance` destroys it, and the
-generic add/remove throw on it.
+Two removal verbs, one meaning each, the same words with the same
+meanings in @solidrt/2d. `remove(child)` DETACHES an intact subtree -
+Three's `parent.remove`, Godot's remove_child: children stay under the
+removed node, core nodes free on leave and recreate on re-enter, so a
+removed subtree re-adds cleanly (`add(parent, child)` re-parents through
+it); it SNAPS, since a detached node is coming back. `destroy(node)` is
+Unity's Destroy, Godot's queue_free: the subtree is gone for good, every
+handle in it inert (writes are no-ops, add throws, remove skips), and it
+is the removal an `exit` rides on (see Retargeted motion). The components
+destroy on unmount. Nothing else is destroyed: GPU resources stay on
+their own disposers (`disposeGeometry`, `disposeInstances`,
+`model.dispose`, the scene's `dispose`), each of which frees a node still
+animating out on the spot. An instance node (addInstance on an instanced
+mesh) is slot-bound to its mesh: `destroy` frees it (the slot recycles at
+the free) and the generic add/remove throw on it. (@solidrt/2d has no
+detach - a sprite cannot exist outside its layer - so `destroySprite` /
+`destroyGroup` are its only removal, and a sprite that should come back
+is hidden.)
 
 ### Rendering is the runtime's
 
@@ -138,7 +147,14 @@ sets itself (or its `fog` option, below) become VIEW-OWNED: the
 scene's setParams/setFog fan-out skips them from then on, so a view
 override survives scene-wide writes. A view's backdrop is its
 clearColor (the scene background draws on PROBES, not views); a view
-has no picking. LAYERS select what a target
+has no picking. A view is a buffer plus a resolve like the scene
+(`view.hdrTexture`, `view.texture`, the `resolve` option and
+`view.setResolve` - see Color); a tiled view (`into`) renders LINEAR
+light into the atlas and the app resolves the atlas once: a
+`createShaderTexture` over `resolveFragment()` from `/glsl` (the stock
+source with `uScene` and the RESOLVE set declared) with the atlas bound
+as `uScene` and `resolveParams({ toneMapping, exposure })` as its params
+- `examples/scene-atlas.tsx`. LAYERS select what a target
 draws, Three's model exactly: `layers` on a mesh is its membership
 bitmask (default 1, `setLayers`/the `layers` prop, NOT inherited from
 Groups), and each target carries a mask (default 1) - `layers` on
@@ -157,7 +173,7 @@ fogged scene); absent follows the scene. `overrideMaterial` (Three's
 `scene.overrideMaterial`, scoped to the view) draws every mesh with one
 material - a depth pass, a normal/id visualizer - skips instanced
 meshes (unless the override itself declares their exact
-`instanceAttributes` record layout) and draws in add order. `depth: "texture"` exposes `view.depthTexture`, the shadow-map
+`instanceBuffers` record layouts) and draws in add order. `depth: "texture"` exposes `view.depthTexture`, the shadow-map
 input; the same option on createScene exposes `scene.depthTexture`,
 the input for a depth-reading post effect in `output` (not combinable
 with `samples` - no multisampled sampleable depth). `ortho: { left, right, top, bottom }` on any camera swaps
@@ -195,6 +211,62 @@ knob is needed. Probe faces set no frustum (six cameras, one target).
 Shadow tiles cull casters against their light frustum, which is what
 makes `shadow.distance` and cascades cheaper.
 
+### Level of detail
+
+LOD is the core's too, beside culling: a group's level is picked per
+target after each flush by PROJECTED SIZE - the sphere around the
+group's boxes (radius = half the box diagonal, conservative like the
+frustum box), its diameter as a fraction of the viewport height,
+`radius / (distance * tan(fov / 2))` under a perspective camera and
+`radius * 2 / (top - bottom)` under an orthographic one (Unity's
+screen-relative model; Three's distance is wrong for an ortho minimap,
+a zoomed camera or a scaled-up tree). `createLod([{ node, size }, ...],
+{ fade? })` / `<Lod fade?>` with `lodSize` on its direct children: the
+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
+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
+one-sided hysteresis band (a level is left at its threshold and
+re-entered only once the size climbs a tenth above it), so a boundary
+never flickers; with one, each threshold `s` widens into `[s, s * (1 +
+fade))` where both levels draw with COMPLEMENTARY screen-hash dithers
+(the near one keeps the pixels below the band position, the far one
+the rest - a partition, never a double draw) through the `uLodFade`
+vec2 every stock fragment composes, its band position in 64 steps so an
+entry is rewritten when its step changes, not every frame, and written
+solid again when the entry switches off; a custom class opts in by composing
+`LOD_FADE` from `@solidrt/3d/glsl` and calling `lodFade()` first in
+main. Shadow tiles never fade: their depth pass switches hard at the
+band's midpoint, invisible for two variants of one shape.
+`createInstancedLod([{ geometry, material, size }, ...], opts)` /
+`<InstancedLod levels capacity?>` is the population form: one instance
+set, one matrix buffer PER LEVEL, and the core stages each instance's
+record into the level ITS OWN size picks - a spread forest as three
+entries, near trees full and far ones cards. Returned as the first
+level's mesh (the other levels are its children at identity, sharing
+its instance slots; `setLayers`/`setCastShadow` on it reach them,
+`setInstanceStyle` writes every level's style stream; a pick or pointer
+event on an instance names that first mesh whatever level the instance
+is drawn at). Records are
+target-agnostic, so instances pick by the SCENE camera and every view
+draws that choice; instanced levels switch hard (`fade` is refused).
+`scene.setLodBias` (Unity's lodBias) multiplies every measured size:
+below 1 hands over sooner, the one-line quality knob for a low-end
+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.
+
 ### Shadows
 
 SHADOWS are a view: `<DirectionalLight castShadow shadow={{ mapSize?,
@@ -205,9 +277,20 @@ the `castShadow` meshes (`<Mesh castShadow>`, `setCastShadow`) from an
 orthographic camera at the light's WORLD position along its world
 direction, `shadow.camera` (+-5, 0.5..500 by default) as the frustum.
 Any light may cast, bounded by the shadow-slot budget
-(MAX_SHADOW_MAPS = 8, its own constant: a directional light claims
-`shadow.cascades` consecutive slots, a point light six, a spot one,
-and a caster past the budget throws at attach). `<SpotLight castShadow
+(`MAX_SHADOW_MAPS` = 8, its own constant, exported from the root and
+`/glsl` with `MAX_LIGHTS` and `MAX_CASCADES`: a directional light claims
+`shadow.cascades` consecutive slots, a point light six, a spot one).
+The budget is checked when the set settles (the scene's sync), never
+at attach, so a `<Show>`/`<Switch>` swap whose branches each fit is
+fine even though both are attached for an instant. A set over budget
+once settled is reported once per change of the set: `<Scene>`
+rethrows it inside the tree, so the app's error boundary (or an
+`<Errored>` closer in) shows it, and Reset returns to the scene, which
+kept rendering - the casters that fit in attach order keep their maps,
+the rest light the scene unshadowed. A bare `createScene` throws it
+from its sync unless given `onError`. A deliberate overlap must fit
+alongside its successor: a casting light with its own exit transition
+keeps casting until it frees. `<SpotLight castShadow
 shadow={{ mapSize?, bias?, normalBias?, near? }}>` is the same
 machinery with a PERSPECTIVE camera: at the light's world position
 along its world direction, fov = its cone (2 * angle), near from
@@ -255,8 +338,8 @@ its view's own view-projection (the whole array is one write per
 shadow-camera move) - and per light i `uShadowFirst[i]`/`uShadowCount[i]`
 name its slots (count 0 = it does not cast) with
 `uShadowBias[i]`/`uShadowNormalBias[i]` its knobs; `SHADOW_SLOTS` in
-glsl declares the set. Every `lit` material RECEIVES by default
-(Godot's and Three's default); `lit({ receiveShadow: false })` opts a
+glsl declares the set. Every `phong` material RECEIVES by default
+(Godot's and Three's default); `phong({ receiveShadow: false })` opts a
 material out and drops the map from its program - a material option,
 as with vertexColors/triplanar, because the material picks the program
 (Godot's `disable_receive_shadows`). The factor is `SHADOW`'s one
@@ -273,28 +356,88 @@ the quaternion geodesic - a spring keeps its velocity through
 retargets), so a mesh gliding to a slot or a camera rig easing costs
 one JS write per target change, zero per frame. The declaration lives
 on the SceneNode and re-applies on every scene enter; the pose a node
-enters with always snaps. Each natural settle calls the node's
-`onTransitionEnd` (plain field like the pointer handlers) with
-`{ component }`; the raw "spatialTransitionEnd" engine event
-(srt:events, carrying the CORE node id `_node`) stays for flux:spatial
-consumers.
+enters with snaps, unless a component's `from` (`position: { duration,
+from: [x, y, z] }`, a quaternion for `rotation`) animates it in from
+there - at every scene enter, since each enter creates the core node
+anew. A component's `exit` is where it animates to when `destroy` lets
+go of the node: it stays drawn while it leaves and is a GHOST meanwhile -
+no pick, raycast, overlap, sweep or pointer event sees it - then frees
+when the last exit settles; children go first and the parent stays their
+frame until the last of them has settled, so a dying character's parts
+leave in its frame (a mixer driving its joints keeps driving them). Either
+endpoint takes `{ value, duration?, curve?, bounce?, delay? }` to own its
+direction's motion (an ease-out enter, an ease-in exit), and `delay` on
+an entry holds its writes on the animation clock (a late frame catches
+up). `stagger` (ms) goes on an ANCESTOR's declaration (a `<Group
+transition={{ stagger: 40 }}>`), never on the animating nodes: it spaces
+the enters and exits of its descendants that begin in one frame by
+`index * stagger` (add order in, tree order out whatever order the
+unmount lets them go in; nearest declaring ancestor wins) and cascades
+nothing unless they declare `from`/`exit` -
+a squad of instances spawning in is one `stagger` on their group, and
+for the nodes straight under the scene root it is `<Scene stagger>` /
+`createScene({ stagger })` (a declaration on `scene.root`). A populated
+mesh unmounts as `destroy(mesh)` then `disposeInstances(mesh)`, and the
+dispose waits for a mesh still animating out, so an `<Instance>`'s exit
+plays through its `<InstancedMesh>`'s unmount (`model.dispose` waits the
+same way); the scene's and a layer's `dispose` cut a corpse short - the
+whole target is going. `examples/exits.tsx` is the live example: crates
+that pop in and shrink away on tap, the shelf cascading out and back
+through `<Show>`. Each natural settle calls the node's `onTransitionEnd`
+(plain field like the pointer handlers) with `{ component }` - never on
+a cancel, snap, leave or exit; the raw "spatialTransitionEnd" engine
+event (srt:events, carrying the CORE node id `_node`) stays for
+flux:spatial consumers.
 
 ### Geometry layout, indices and topology
 
 One interleaved vertex buffer per geometry, described by an open layout
-(`Geometry.layout`, absent = "standard"): an ordered attribute list that
-always starts with the standard prefix `aPos` vec3 + `aNormal` vec3 +
-`aUV` vec2 (what every generator emits) and may carry any named channels
-after it. `withAttribute(geometry, { name, format }, fill)` appends one
-(Three's `setAttribute` for an interleave); "colored" names the common
-case, the prefix plus `aColor` vec4 - the per-vertex data channel (a
-tint, baked AO, any four scalars; standard name, your contents) - and
-`withColors(geometry, fill)` is its spelling. Fill is a flat
-size-per-vertex array or a per-vertex callback receiving `(index, pos,
-normal, uv)`. Materials read attributes BY NAME: a material's vertex
-stage may declare any subset of its geometry's channels, and a channel
-the program reads that the geometry lacks (name + format) throws at
-add(). What a program reads is the ENGINE's word (`material.attributes()`
+(`Geometry.layout`, absent = "base"): an ordered attribute list that
+starts with `aPos` float32x3 and may carry any named channels after it,
+each in a vertex format. Formats are WebGPU's spelling of (component
+type, count, normalized): the float32 family (`float32` .. `float32x4`),
+`float16x2/x4`, the normalized integers `unorm8x4`, `snorm8x4`,
+`unorm16x2/x4`, `snorm16x2/x4`, the unsigned integers `uint8x4`,
+`uint16x2/x4`, `uint32` .. `uint32x4` and the signed integers `sint8x4`,
+`sint16x2/x4`, `sint32` .. `sint32x4`; `VERTEX_FORMATS` is the table.
+Every format is a multiple of 4 bytes, so offsets and strides are
+4-aligned by construction. A format feeds the shader `in` of its KIND
+and component count, WebGPU's rule: float and normalized formats feed
+`in vec4` (the fetch converts: `in vec4 aColor` reads a `unorm8x4` as
+0..1), `uint*` formats feed `in uvec4` and `sint*` formats `in ivec4`,
+exact at every width - so a per-vertex id or an index into a wide
+table rides as `uint32` into `in uint aId`, and the "skinned" layout's
+`aJoints` is `uint8x4` into `in uvec4 aJoints`. A layout that crosses
+kinds (`uint8x4` into `in vec4`) is the missing-attribute error at
+add() (`formatFeeds` is the rule). The base prefix `aPos` float32x3 + `aNormal`
+float32x3 + `aUV` float32x2 is what every generator emits and what the
+stock materials read, not a rule: a hand-built geometry declares what
+it has, so a point cloud may carry `[aPos float32x3, aData float32]` at
+16 bytes a point instead of 36, or a color as `unorm8x4` at 4 bytes
+instead of 16. Pair a prefixless layout with a material that reads only
+what it carries: `unlit` (aPos only) or a shaderMaterial; a stock lit
+material over it throws the ordinary missing-attribute error at add().
+A layout handed to a generator must start with the prefix and stay
+float32-family (the generator writes floats); packing is a pass over
+the result. `withAttribute(geometry, { name, format }, fill)` appends
+one channel in any format (Three's `setAttribute` for an interleave;
+the fill is given in float and encoded on write); "colored" names the
+common case, the prefix plus `aColor` float32x4 - the per-vertex data
+channel (a tint, baked AO, any four scalars; standard name, your
+contents) - and `withColors(geometry, fill)` is its spelling. Fill is a
+flat size-per-vertex array or a per-vertex callback receiving `(index,
+pos, normal, uv)` (zeros for a channel the layout lacks). The fill is
+raw floats: a tint the stock materials read under `vertexColors` is
+premultiplied linear like every shader color, so encode an sRGB pick
+with `premultipliedColor(color)`. `Geometry.vertices` is an
+`ArrayBufferView` (a Float32Array for an all-float layout, a Uint8Array
+when a channel is packed; never the contract): read and write a channel
+through `geometryAttribute(geometry, name)`, an accessor whose
+`get(i, k)`/`set(i, k, v)` speak floats whatever the format, and count
+vertices with `vertexCount`. Materials read attributes BY NAME: a
+material's vertex stage may declare any subset of its geometry's
+channels, and a channel the program reads that the geometry lacks (by
+name, or with a different component count) throws at add(). What a program reads is the ENGINE's word (`material.attributes()`
 = `programAttributes` reflection of the linked program, instance
 attributes excluded), not a parse of the GLSL: an `in` the compiler
 dropped does not count, and the engine also rejects a pipeline whose
@@ -302,15 +445,39 @@ attribute lists leave a read attribute uncovered. The material
 keeps one program and builds one pipeline per layout its meshes bring,
 so a geometry may carry more than a material reads. The whole layout
 ships whether a material reads every attribute or not (inactive
-attributes only keep the stride), so extra channels cost their floats on
+attributes only keep the stride), so extra channels cost their bytes on
 every draw of that geometry - keep data-light passes (a wireframe
-reading only aPos) on standard geometry. The prefix has no opt-out, so
-geometry that is not a surface pays for it anyway: a lidar point
-carrying a position and one packed channel still costs the 8-float
-prefix, doubling a large cloud's vertex buffer
-(okf/backlog/non-surface-vertex-layouts.md). `layoutStride`/`layoutSlot`/
-`layoutKey`/`layoutAttributes` are the layout arithmetic; two layouts
-with equal keys interleave identically (merge requires that).
+reading only aPos) on base-layout geometry. `layoutStride` (bytes)/
+`layoutSlot` (byte offset, format, components)/`layoutKey`/
+`layoutAttributes` are the layout arithmetic; two layouts with equal
+keys interleave identically (merge requires that).
+STREAMS: a geometry may carry more than one vertex buffer.
+`Geometry.vertices` under `layout` is stream 0 (where aPos lives) and
+`Geometry.streams` holds extra `{ layout, vertices }` buffers, each with
+its own attribute list and the same vertex count (Unity's vertex
+streams; Three's one buffer per channel when a stream carries one
+attribute). `withAttribute(geometry, attr, fill, { stream })` appends a
+channel to stream 1..n or opens stream n + 1; `geometryAttribute`,
+`geometrySlot`, `geometryKey`, `geometryLayouts`, `geometryStreams`
+and `geometryVertexCount` read across streams, and a material's
+pipeline is one per `geometryKey` (every stream's layout, `|` between
+them). Streams exist for data on its own schedule: `updateVertices(
+geometry, { stream?, first?, count? })` re-uploads that vertex range of
+that stream from the geometry's own array in place (write the array
+through the accessor first; Three's `needsUpdate` with an update
+range), reaching every mesh, view and wireframe over the geometry
+while the other streams never move; a stream-0 update drops the cached
+bounds and rewrites the same range of the core's copy of the positions,
+so the mesh picks and culls where it is now drawn (the box follows at
+the next flush, the triangle index is rebuilt by the next query - a
+deforming mesh needs no re-attach). transformGeometry and
+the edge builders share extra streams with their source; merge
+concatenates every stream; the `.srtm` container refuses streams (run
+time data). `setDrawRange(mesh, first, count?)` draws indices `[first,
+first + count)` of the mesh's geometry (Three's `setDrawRange`, on the
+mesh because the scene owns the entries), applied to every entry of the
+mesh and reset by setGeometry. The worked example is
+`examples/streams.tsx`.
 Indices are uint16 or uint32 - the `Geometry.indices` array type picks
 the draw's index format, so hand-built geometry past 64k vertices just
 uses a Uint32Array (generators emit uint16). What the indices LIST is
@@ -321,8 +488,9 @@ SetIndices topology), a material builds one pipeline per (layout,
 topology) pair its meshes bring, and validateGeometry enforces the
 count rule at add() (a whole number of triangles or lines, one
 primitive's worth for a strip). Materials have no topology of their
-own. Only a triangle list gets a picking shape; lines and points pick
-and collide by their bounds box, and cast no shadow. `geometryTopology`
+own. Only a triangle list gets a triangle narrowphase; lines and points
+pick and collide by their bounds box (which follows `updateVertices` all
+the same), and cast no shadow. `geometryTopology`
 reads the field with the default applied. POINTS: a point cloud is
 ordinary indexed geometry - one vertex per point, the index buffer
 listing them, `topology: "points"`, no constraint on the index count.
@@ -336,7 +504,7 @@ cost model). Geometry GPU buffers are lazy, shared, and
 reference-counted by draw entries: removing the last
 entry frees them at the end of the microtask (a same-tick rebuild keeps
 the upload), so swapping `<Mesh geometry>` reactively never accumulates
-old generations; the vertex upload is keyed on the `Float32Array`
+old generations; the vertex upload is keyed on the vertices view
 itself, so geometries sharing a vertex array (a wireframe over its
 source) share one buffer. `disposeGeometry` is the immediate explicit
 free.
@@ -345,9 +513,9 @@ free.
 
 Materials dedupe hard: one program + one pipeline per material CLASS
 (a `shaderMaterialClass` per option combination for unlit, lit and
-sprite alike: map x transparent x cull x alphaTest, lit's extras on
+sprite alike: map x transparent x cull x alphaTest, phong's extras on
 top), `depth: true` + `cull: "back"` unless the material says otherwise
-(`cull: "none"` for double-sided geometry; lit flips the normal on back
+(`cull: "none"` for double-sided geometry; phong flips the normal on back
 faces); an instance is just per-entry uniforms (`uColor`) and bindings
 (`uMap`).
 
@@ -379,14 +547,16 @@ 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 or `"aces"`), `exposure?` (default 1), `layers?` (target mask, default 1), `depth?` (`"texture"` exposes scene.depthTexture; not with samples), `samples?` (1/2/4/8 MSAA), `label?`, `ref?(scene)`, `output?(texture)`, `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), `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?`, pointer events (below), `ref?(node)` |
+| `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) |
+| `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)` |
 | `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 slot-1 floats - `[r, g, b, a]` under `instanceColors`), `ref?(instance)`; a parent too (a `<Mesh>` under an instance rides with it) |
-| `RecordMesh` | as Mesh, plus `records` (interleaved per-instance floats; 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 buffer is 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) |
+| `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)` |
 | `PointLight` | transforms as Group (position is what matters), `color?`, `intensity?`, `distance?`, `decay?`, `castShadow?` (six face maps, six shadow slots), `shadow?` (mapSize, bias, normalBias, near), `ref?(light)` |
@@ -400,7 +570,9 @@ a `<d-texture>`, a leaf with blendMode/fit/pointer/layout props, or a
 post-effect chain (`createShaderTarget` sampling the id with a
 covering-triangle pass; created in the callback it disposes with the
 Scene). Return null for no leaf at all and compose `scene.texture`
-elsewhere. Called once, untracked, inside the scene context. Scene
+elsewhere. Called once, untracked, inside the scene context. `output`
+composes the DISPLAYED texture, the resolve's output: an LDR effect
+lives here; one that needs the scene's radiance is a `resolve` (Color). Scene
 `width`/`height` are target pixels and the leaf's own width/height are
 layout, so render and display size separate - render at 2x and display
 smaller for supersampling.
@@ -475,21 +647,42 @@ a drag and a stick both turn the eye.
 
 Camera control: `createOrbitCamera(scene, { target?, azimuth?, elevation?,
 distance?, min/maxDistance?, min/maxElevation?, orbitSpeed?, rotateSpeed?,
-zoomSpeed?, panSpeed?, clampTarget?, zoomAnchor?, rotateAnchor? })` -
-azimuth/elevation/distance around a target with optional auto-orbit. The
-first argument is anything with the scene's `setCamera` and `camera()`
-(the fov maps pan travel to world): a Scene, or a View to drive one view's
-camera independently. 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`; `clampTarget(target)` bounds where a pan may put the
-pivot). 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 pushes the pose at
-once. Zoom aims at the target unless `zoomAnchor(focal, {eye, target})`
+zoomSpeed?, panSpeed?, damping?, clampPose?, zoomAnchor?, rotateAnchor? })`
+- 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
+against): a Scene, or a View to drive one view's camera independently.
+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
+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
@@ -502,13 +695,14 @@ 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 and the auto-orbit (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, 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
+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.
@@ -522,10 +716,13 @@ 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. Every other prop is live - forwarded to the control as a
-getter and read where it applies, never snapshotted - so clamps, rates
-and anchors follow their props without a remount, and a clamp change
-re-clamps the pose at once.
+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).
 
 ### First-person camera
 
@@ -544,7 +741,12 @@ length so they walk no faster) and `rise` (world up at `moveSpeed`, fly
 mode only). 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)`. Every option but the initial pose is read
+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
+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
 effect on the next move: walk and fly are one control. The control NEVER
@@ -554,8 +756,10 @@ collision of its own: `clampPosition(next, current)` is the whole hook -
 bounds, a floor height, or `moveAndSlide` over `next - current` against
 the collision layer (see `examples/collision.tsx`, whose `jump` is one
 more action on the same map: Space or the pad's south button, read by
-name). Call `update(dt)` from onFrame; `active()` is reactive - a rate
-driving (a held key, a deflected stick) - and gates the loop. The map
+name); a glide consults it every frame as a walk does every step. Call
+`update(dt)` from onFrame; `active()` is reactive - a rate driving (a
+held key, a deflected stick), or a glide in flight - and gates the loop.
+The map
 tracks held keys from the down/up pair through `input.handlers`; spread
 its `onBlur` too, since the up never arrives once focus has left.
 
@@ -609,7 +813,9 @@ The index and the narrowphase live in the spatial core: every attached
 mesh's local box is a leaf in a dynamic AABB tree the flush refits from
 the fresh world matrices (O(moved) per frame, a query O(log meshes)), and
 an ordinary mesh is then tested per triangle against its geometry's
-shape (one CPU copy per distinct geometry, created with its GPU buffers),
+shape (one CPU copy of the positions per distinct geometry, created with
+its GPU buffers and rewritten by `updateVertices`; the mesh's box comes
+from the same copy, so a deforming mesh is found where it is drawn),
 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
@@ -723,7 +929,9 @@ pointerType, button, modifiers) plus `x`/`y` in scene pixels
 (screenRay's input - a drag plane is one intersection away). Root
 listeners all run, in registration order (the root is the last stop,
 nothing is left to claim). Wiring: the built-in `<Scene>` leaf carries
-`scene.handlers` automatically (opt out: `events={false}`); an `output`
+`scene.handlers` automatically (opt out: `events={false}`, which throws
+at mount together with a `pointer` feed - the feed would listen at a root
+no event reaches; the same on `<View3d>`); an `output`
 leaf or imperative composition spreads `{...scene.handlers}` onto the
 element showing the texture. `scene.handlers` assumes that leaf is LAID
 OUT at the target size - true for the built-in leaf and a d-texture at
@@ -742,15 +950,36 @@ a default, named as Three names them: `box({ width, height, depth })`
 `ring({ innerRadius, outerRadius, segments })` (XY, facing +z - rotate
 `[-Math.PI/2, 0, 0]` for a floor); `sphere({ radius, widthSegments,
 heightSegments })`; `cylinder({ radiusTop, radiusBottom, height,
-radialSegments })` (y axis, capped; unequal radii taper it) and
-`cone({ radius, height, radialSegments })`; `torus({ radius, tube,
+radialSegments, heightSegments })` (y axis, capped; unequal radii taper
+it) and `cone({ radius, height, radialSegments, heightSegments })`;
+`capsule({ radius, height, capSegments, radialSegments, heightSegments
+})` (y axis, `height` the TOTAL extent like
+cylinder's and Godot's/Unity's where Three's is the middle section
+only, so `height: 2 * radius` is a sphere and less throws; its collision
+volume is `{ a: [0, -(height / 2 - radius), 0], b: [0, height / 2 -
+radius, 0], radius }`); `torus({ radius, tube,
 radialSegments, tubularSegments })` (lying flat, hole on the y axis) and
 `torusKnot({ radius, tube, tubularSegments, radialSegments, p, q })`
 (standing y-up) - both oriented for the y-up world, unlike Three's z-up.
 No positional form: `box()` is the default cube, `box({ label: "rock" })`
-names it. Every options object (the profile kit's `extrude`/`lathe`/
+names it. The polyhedra: `tetrahedron`, `octahedron`, `icosahedron` and
+`dodecahedron` (`{ radius, detail }`, radius 0.5 like sphere where
+Three's is 1) and the generic `polyhedron(vertices, indices, { radius,
+detail })` over Three's data form (flat xyz list, CCW triangle list, the
+data first like `box3Helper`), each solid projected onto its
+circumsphere. `detail` splits every edge `detail + 1` ways first, so
+`detail: 0` is the flat-shaded solid (face normals) and anything above a
+sphere of uniform triangles with radial normals: `icosahedron({ detail:
+3 })` is the icosphere, no pole pinch. Non-indexed like Three, every
+triangle owning its three vertices; `edgesGeometry` welds by position,
+so `edgesGeometry(dodecahedron())` is the twelve pentagons (the fan
+diagonals are coplanar and drop out) where `wireframeGeometry` shows the
+triangulation. UVs are the spherical map with Three's seam patch,
+stretched toward the poles: the textured sphere stays `sphere()`, the
+polyhedra are for flat-shaded, low-poly and procedurally shaded looks
+(examples/polyhedra.tsx). Every options object (the profile kit's `extrude`/`lathe`/
 `sweep`/`tube` too) also takes `label` and `layout` - `layout` makes the
-generator emit that layout in one pass (standard channels written, the
+generator emit that layout in one pass (base channels written, the
 extra slots zero), so `box({ layout: "colored" })` then
 `fillColors(g, fill)` builds colored geometry without the
 generate-then-repack copy; the result is byte-identical to
@@ -759,7 +988,8 @@ the tail every generator ends in, for your own generators.
 `withAttribute(geometry, attr, fill, label?)` derives a copy of any
 geometry (generator or hand-built) with one more channel after its
 current layout; the source is untouched. `withColors(geometry, fill,
-label?)` is the aColor vec4 case, keeping the "colored" preset name.
+label?)` is the aColor float32x4 case, keeping the "colored" preset
+name (`withAttribute` with `unorm8x4` is the 4-byte color).
 `fillAttribute(geometry, name, fill, first?, count?)` is the in-place
 primitive under both: overwrites one channel the geometry's layout
 already carries (withAttribute ADDS one), reading pos/normal/uv from the
@@ -796,13 +1026,86 @@ until the threshold passes 360 / radialSegments. The wireframe of a
 "skinned" part draws in its pose under `unlit({ skinned: true })` with
 the mesh's palette, and the swap onto a live mesh is
 `setGeometry` + `setMaterial` (`examples/wireframe.tsx`). Lines are one
-pixel wide on GL ES; thick lines are quad geometry. `geometryBounds(geometry)`
+pixel wide on GL ES; thick lines are quad geometry. The debug helpers are
+`"lines"` builders too, Three's helper classes camelCased:
+`gridHelper({ size?, divisions?, color?, centerColor? })` is the XZ grid
+at y 0 (defaults 10 by 10, Three's grays; the two lines through the
+origin take `centerColor` and exist only for an even `divisions`),
+`axesHelper({ size? })` the X red, Y green, Z blue triad from the origin,
+`box3Helper(bounds, options?)` the twelve edges of a
+`[minX, minY, minZ, maxX, maxY, maxZ]` box in local space, and
+`planeHelper({ size? })` a square outline with its diagonals and a unit
+normal tick in the XY plane facing +z, placed like `plane()`, and
+`arrowHelper({ length?, headLength?, headWidth? })` an arrow along +y
+with a pyramid-outline head, aimed by the node's rotation
+(`quatFromTo(out, [0, 1, 0], direction)`), and `capsuleHelper(volume,
+{ segments? })` the outline of a `{ a, b, radius }` collision capsule
+(rings at both ends, four lines, two half circles per cap; `a == b`
+draws a sphere's three great circles) in the volume's own space, the
+gizmo Unity and Godot draw for a capsule collider. Godot and
+Unity keep these in the editor and Three makes them scene objects; here
+they are plain geometry a node places and a material draws. The grid and
+the triad are "colored" layout (sRGB colors in, premultiplied linear
+aColor out, the material contract) drawn by `unlit({ vertexColors:
+true })`; a material that reads no aColor draws them in its own color.
+The box, the plane, the arrow and the capsule are base layout. For a bounds box that moves
+every frame, draw `edgesGeometry(box())` on a node whose position is the
+box center and whose scale is its size and update the transform (Three's
+Box3Helper does exactly that) instead of rebuilding.
+`examples/wireframe.tsx` draws a grid, the triad and the rover's bounds
+box. `geometryBounds(geometry)`
 returns the cached local AABB `[minX, minY, minZ, maxX, maxY, maxZ]`, and
 `rayBoxDistance(ox, oy, oz, dx, dy, dz, minX, .., maxZ)` is the picking
 slab test (entry t >= 0 in units of the direction's length, 0 from
 inside, -1 for a miss) - for ray-testing boxes you keep yourself
 (triggers, collision volumes) without meshes you do not want to draw.
 
+Normals as data: two ops, split by whether the vertex count survives.
+`computeVertexNormals(geometry)` recomputes a triangle geometry's
+normals IN PLACE from the faces that name each vertex by index (Three's
+`computeVertexNormals`, Unity's `RecalculateNormals`, Godot's
+`generate_normals`, all in place), each face weighted by its corner
+angle so the result does not depend on how a surface was triangulated.
+The math runs in the core in one call over the vertex floats (so aNormal
+must be float32x3; a packed normal is an authoring format, pack after
+withNormals), and it returns the stream carrying aNormal, which
+`updateVertices` re-uploads: the CPU deformation loop is
+`fillAttribute(g, "aPos", ...)`, `computeVertexNormals(g)`,
+`updateVertices(g)`. That loop is for data that genuinely changes on the
+CPU - a streamed cloud, a cloth solved in JS, an editor edit. A
+per-frame ripple, sway or wave belongs in a vertex shader: displace and
+derive the normal in the vertex stage (`shaderMaterial`), and no
+per-vertex work touches the CPU at all; the fillAttribute callback alone
+is an interpreter call per vertex per frame. A vertex shared across faces
+shades smooth and a split one per face, so a merged or deformed
+generator geometry comes out right; a uv seam's copies each see one side
+and the seam shows (Three's artifact too). `withNormals(
+geometry, creaseAngle = 60, label?)` is the authoring path and a COPY:
+faces are matched by position, so a triangle soup, a hand-written face
+list, a merged result or a geometry with no aNormal channel at all (one
+is added, float32x3) all work and a seam shades smooth across it; 0 is
+flat shading, 180 smooths everything, 60 (Three's `toCreasedNormals`
+and Unity's import smoothing angle) keeps hard edges hard. It is
+`toNonIndexed` + per-corner normals + `mergeVertices`, so the result is
+indexed and split only where a crease or a seam needs it (a box stays
+24 vertices under 90 degrees). Both pieces are exported:
+`toNonIndexed(geometry, label?)` gives every index its own vertex
+(identity indices; per-face colors via fillAttribute, flat shading via
+computeVertexNormals), `mergeVertices(geometry, tolerance = 1e-4,
+label?)` welds vertices equal in every channel back together, the exact
+inverse (a normal or uv that differs keeps them apart). Neither takes a
+morphed geometry: split or weld before `withMorphTargets`.
+`normalsHelper(geometry, { size?, color? })` draws one line per vertex
+along its normal (Three's VertexNormalsHelper as a static builder,
+"colored" layout, red by default, drawn by `unlit({ vertexColors: true
+})` under the mesh's node), the way to look at any of this;
+`examples/normals.tsx` shows the three crease angles on one soup, a
+rippling sphere on the per-frame loop, and the helper refreshed in place
+with the same loop. Three's `center()` is `transformGeometry(g, {
+position: [-(b[0] + b[3]) / 2, -(b[1] + b[4]) / 2, -(b[2] + b[5]) / 2]
+})` over `geometryBounds`; there is no bounding sphere op, the box is
+what every query and the LOD read.
+
 ### Profile kit
 
 Profile kit (2D outlines to solids, real texture UVs): a `Profile` is a
@@ -825,8 +1128,8 @@ Closed loops are NOT supported yet - overlap the ends by a segment to
 fake one. `tube(path, { radius, radialSegments })` is the round-profile
 shorthand (wire, rope, pipe), and `pathFrames(path)` exports the
 per-segment frames (tangents, cross-section axes, arc lengths) for
-custom work along a path. `shape(profile, options?)` fills one flat (facing +z,
-like circle); `triangulate(points)` is the ear-clipping core (fan
+custom work along a path. `polygon(profile, options?)` fills one flat (facing
++z, like circle); `triangulate(points)` is the ear-clipping core (fan
 fallback, never drops a cap), exported for custom flat work. These pick
 uint16/uint32 indices by vertex count automatically.
 
@@ -834,15 +1137,20 @@ uint16/uint32 indices by vertex count automatically.
 
 #### unlit
 
-`unlit({ color?, map?, transparent?, cull?, alphaTest?, fog? })` -
+`unlit({ color?, map?, vertexColors?, transparent?, blend?, cull?, alphaTest?, fog? })` -
 straight `[r, g, b, a?]` 0..1 sRGB (decoded to linear light, see Color
-below), premultiplied internally; `cull` and
-`alphaTest` as on lit (a mapped cutout casts its cutout); `fog: false`
+below), premultiplied internally; `vertexColors: true` multiplies by the
+"colored" layout's aColor (the geometry must carry it: withColors, a
+gridHelper or axesHelper); `blend` the factors of a transparent draw,
+"alpha" when absent, `"add"` for a glow (any mode but "none" implies
+`transparent` unless told `transparent: false`, the shaderMaterial
+rule); `cull` and
+`alphaTest` as on phong (a mapped cutout casts its cutout); `fog: false`
 opts out of the scene's fog (all four library materials take it).
 
 #### sprite
 
-`sprite({ color?, map?, transparent?, billboard? })` - unlit on a quad
+`sprite({ color?, map?, transparent?, blend?, billboard? })` - 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
@@ -872,12 +1180,7 @@ with uViewProj - the specular/fresnel view vector is
 uViewProj rows, that carries the clip flip), `uniform mat4
 uInvViewProj` (the camera's inverse view-projection, shared likewise -
 a clip position back to world, the world-space ray through a pixel
-without knowing the projection), the output stage's `uniform float
-uExposure` / `uToneMapping` (compose `OUTPUT` from `/glsl` and end with
-`fragColor = outputColor(rgb, alpha)` to take the scene's exposure and
-tone mapping and encode like the library materials do; a fragment
-writing fragColor directly writes final encoded pixels) and `uniform
-mat4 uNormal` (the world
+without knowing the projection) and `uniform mat4 uNormal` (the world
 inverse-transpose, written beside uModel for this material's meshes;
 take `mat3(uNormal)` - correct under non-uniform scale, where
 mat3(uModel) bends normals off the surface). Attributes come from the
@@ -907,21 +1210,33 @@ pipeline with its own values. `dispose()` lives on the class alone.
 
 #### Instanced materials
 
-`instanceAttributes: [{ name, format, slot? }]` (`format` is the vertex
-vocabulary, `"f32" | "vec2" | "vec3" | "vec4"`, NOT WebGPU's
-`float32x3` spelling) on either shader-material form makes an INSTANCED
-material: the vertex stage reads them as `in` variables beside the
-layout's own, and each drawn instance gets one
-record per slot from the mesh's instance buffers - slot 0 (default)
-is the record buffer, slot 1 an instanced mesh's STYLE buffer (below).
-Its meshes come from `createInstancedMesh` or `createRecordMesh`; a
-`createMesh` mesh is rejected at add(). `instanceStyle: [..]` is the
-slot-1 record a fresh instance starts with. The stock materials do
-the same with one flag: `lit/standard/unlit({ instanced: true })`
-places by the instance matrix (the shadow pass too, so the fleet
-casts), and `{ instanceColors: true }` adds a per-instance
-premultiplied `[r, g, b, a]` style record starting white - Unity's
-per-material instancing switch with Three's setColorAt.
+`instanceBuffers: [{ attributes: [{ name, format }] }]` (one layout per
+per-instance buffer, instance-step by definition and tightly packed in
+list order like a geometry layout; `format` is any of the vertex
+vocabulary, so a per-instance tint is a `unorm8x4` at four bytes and a
+frame index a `uint16x2`; explicit strides and offsets stay the
+engine's, through core's pipeline API) on either shader-material form
+makes an INSTANCED material: the vertex stage reads the attributes as
+`in` variables beside the layout's own, and each drawn instance gets one
+record from each of the mesh's instance buffers. An instance buffer IS a
+vertex stream stepped per instance: on the mesh it is an `InstanceStream`
+(the layout, a byte mirror, a mesh-owned GPU buffer), written through
+`instanceAttribute(mesh, name)` - the accessor `geometryAttribute`
+returns, record index in, values as the shader sees them, the codec
+packing the bytes - and published with `updateRecords(mesh, { stream?,
+first?, count? })`, which is `updateVertices` for records: one coalesced
+buffer write per dirty stream at the scene's sync, so ten moved records
+of ten thousand cost ten. Its meshes come from `createInstancedMesh`
+(the first buffer is the core-written matrix, the rest are streams; the
+second is the STYLE record, below) or `createRecordMesh` (every buffer a
+stream); a `createMesh` mesh is rejected at add(). `instanceStyle: [..]`
+is the style record a fresh instance starts with, one value per
+component. The stock materials do the same with one flag:
+`lit/standard/unlit({ instanced: true })` places by the instance matrix
+(the shadow pass too, so the fleet casts), and `{ instanceColors: true
+}` adds a per-instance premultiplied `[r, g, b, a]` style record
+starting white, stored as `float16x4` (eight bytes, no banding in the
+darks) - Unity's per-material instancing switch with Three's setColorAt.
 
 ### Instancing
 
@@ -953,32 +1268,36 @@ 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).
-The material declares `INSTANCE_MATRIX_ATTRIBUTES` in slot 0 (four vec4
-columns, 16 floats; anything else throws at creation) and its vertex
+The material declares `INSTANCE_MATRIX_ATTRIBUTES` as its first instance
+buffer (four vec4 columns, 16 floats; anything else throws at creation)
+and its vertex
 stage splices `INSTANCE_MATRIX` from `@solidrt/3d/glsl`: `uModel *
 instanceMatrix() * vec4(aPos, 1.0)`, normals through
 `instanceNormalMatrix()` (Three's derivation, exact for any rotation and
 scale at no per-instance data; a sheared hierarchy - a non-uniformly
 scaled group above a rotated instance - takes
 `transpose(inverse(mat3(instanceMatrix())))` instead) - or is a stock
-material with `instanced`. Slot-1 attributes, when the material declares
-any, give every instance a STYLE record beside its matrix
-(`MeshInstances.style`): app-owned floats in a second, mesh-owned
-buffer, written per instance with `setInstanceStyle(instance, floats)`
-into a JS mirror and published as ONE coalesced buffer write per mesh at
-the scene's sync (a frame-rate path, like setTransform); a fresh or
-recycled slot starts from the material's `instanceStyle` (white under
-`instanceColors`, zeros otherwise); under `alphaTest` the cutout shadow
+material with `instanced`. A second instance buffer, when the material
+declares one, gives every instance a STYLE record beside its matrix
+(`MeshInstances.streams[0]`): an app-owned stream in the material's
+layout, written per instance with `setInstanceStyle(instance, values)`
+(one value per attribute component, encoded by the codecs) or by name
+through `instanceAttribute` + `updateRecords`, into a JS mirror and
+published as ONE coalesced buffer write per stream at the scene's sync
+(a frame-rate path, like setTransform); a fresh or recycled slot starts
+from the material's `instanceStyle` (white under `instanceColors`, zeros
+otherwise); a third buffer is a further stream, reached by name only;
+under `alphaTest` the cutout shadow
 multiplies by the same color, so an instance faded below the cutoff
 casts nothing, like its pixels (Godot's alpha scissor holds in its
-shadow pass too). The core's pose slot and the app's style slot are
+shadow pass too). The core's pose buffer and the app's style buffer are
 @solidrt/2d's split one dimension up. Slots are fixed
-for an instance's life and recycle on `removeInstance` (remove means
-destroy: an instance cannot exist outside its mesh, and the generic
-add/remove throw on one), the drawn count is the slot high-water mark,
-and past `capacity` (default 64) both buffers double into replacements
-with the live records retargeted in one core call and the style mirror
-republished. `parent` may be a group inside the mesh's subtree (a squad
+for an instance's life and recycle on `destroy` (at the free: an
+instance cannot exist outside its mesh, so the generic add/remove throw
+on one), the drawn count is the slot high-water mark,
+and past `capacity` (default 64) every buffer doubles into a
+replacement, with the live matrix records retargeted in one core call
+and each stream's mirror republished. `parent` may be a group inside the mesh's subtree (a squad
 in a fleet): the record stays mesh-relative through it. Picking is per
 instance: every instance node carries the geometry's bounds and
 triangle shape, so `Hit`, `Overlap` and `Impact` name the `instance` and
@@ -1004,17 +1323,23 @@ or in five figures, belong to the function face.
 #### createRecordMesh
 
 `createRecordMesh(geometry, material, records, count?, { bounds?,
-label? })` is the raw form: `records` is the interleaved per-instance
-data (stride = the material's slot-0 instanceAttributes summed, a
-mismatch throws; slot 1 is an instanced mesh's and throws here),
-uploaded to a mesh-owned buffer whose capacity starts at the
-records given, and `count` picks how many draw (default all).
+label? })` is the raw form: `records` is the per-instance data laid out
+in the material's first instance layout - a Float32Array over an
+all-float layout, otherwise bytes built with `vertexView(layout, buffer)`
+and `attributeAccess` like a geometry stream (a length that is not whole
+records throws) - copied into the first stream's mirror, whose capacity
+starts at the records given; every further instance buffer the material
+declares is a zeroed stream of the same capacity, reached by name
+through `instanceAttribute`. `count` picks how many draw (default all).
 `setRecords(mesh, records, count?)` rewrites from the start (count
 defaults to the records written; more than capacity GROWS: capacity
-doubles into a replacement buffer, the entry is re-pointed via
-`setDrawBuffers`, the old buffer is freed) and `setRecordCount(mesh, n)`
-is the population dial (clamped to capacity; frame-rate-safe). Records
-are opaque data (position/yaw/tint/whatever your shader reads), so the
+doubles into replacement buffers, the entry is re-pointed via
+`setDrawBuffers`, the old ones are freed), `instanceAttribute` +
+`updateRecords(mesh, { first, count })` rewrites a few (the range is
+against capacity, so write ahead and dial after), and
+`setRecordCount(mesh, n)` is the population dial (clamped to capacity;
+frame-rate-safe). Records are opaque data (position/yaw/tint/whatever
+your shader reads), so the
 library cannot know where they place instances: a record mesh has NO
 picking leaf unless you pass `bounds` (local, covering the population) -
 then it picks and transparent-sorts conservatively as one box. The
@@ -1050,11 +1375,10 @@ no separate resize plumbing. Two forms:
   written through `scene.setParams` (an app clock for an animated sky).
   Godot's sky shader and Unity's skybox material are the same idea; the
   radiance bake for environment lighting will consume this same source
-  later, so a procedural sky written here lights the scene then. The
-  preamble declares the OUTPUT set: end with `fragColor =
-  outputColor(rgb, 1.0)` for a sky that takes the scene's exposure and
-  tone mapping (the skybox form does); a direct fragColor write is final
-  encoded pixels.
+  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.
 - A skybox `{ cube, intensity?, rotation? }` (SkyboxOptions): a cube
   map from createCubeTexture sampled along the same ray - Three's
   `scene.background = cubeTexture` with `backgroundIntensity` and
@@ -1091,7 +1415,7 @@ prop - the cube map every `standard` material is lit by (always: the
 split sum `envRadiance` at its roughness times PBR's `envBrdf` for the
 specular, `envIrradiance` - the fully rough sample along the normal, as
 Three's getIBLIrradiance and Godot read it - added to the hemisphere
-for the diffuse) and every `lit({ reflectivity })` material mirrors,
+for the diffuse) and every `phong({ reflectivity })` material mirrors,
 typically the skybox's own cube turned with it. The cube to use is a
 BAKED one: `bunx srt tool 3d/environment sky.hdr -o assets/sky.srte`
 turns an equirectangular Radiance .hdr (Poly Haven's are CC0) into the
@@ -1127,7 +1451,7 @@ tints instead; not offered). The reflection blurs with `shininess`:
 roughness `sqrt(2 / (shininess + 2))` picks a mip level of the cube
 (`textureLod`), so the environment cube wants `mipmap: true`; a cube
 without mipmaps stays sharp. `specularMap`'s red scales it like
-`specular`. For `lit` it is not an ambient light source: the hemisphere
+`specular`. For `phong` it is not an ambient light source: the hemisphere
 light stays its only ambient term (`standard` adds envIrradiance; SH9
 is a later, additive mode). A declared `reflectivity` with no
 environment set contributes nothing (uEnvOn 0), not a black reflection.
@@ -1141,7 +1465,11 @@ near?, far?, layers?, clearColor?, label? })` renders the scene into a
 cube map from a point - Three's CubeCamera, Unity's and Godot's
 realtime ReflectionProbe - and returns `{ cube, setPosition, update(),
 dispose() }`; `cube` is what `environment={{ cube }}` (a chrome ball
-mirroring its surroundings) or `background` takes. A view under the
+mirroring its surroundings) or `background` takes. `dispose()` destroys
+the cube, and a scene whose environment or background names it drops
+that first (setEnvironment(null) / setBackground(null)), so a subtree
+that owned the environment leaves the scene unlit by it rather than
+sampling a destroyed texture; set another when it goes. A view under the
 hood: one entry list mirrored from the scene, the light set and scene
 params fanned out, its own layer mask (keep the mirroring object out of
 its own probe with `layers`), the scene's background drawn first on
@@ -1168,13 +1496,12 @@ costs ~14 ms of GPU there against ~1 ms for the six face passes: fine at
 probes are the expensive option in every engine (Unity time-slices
 them): update a prefiltered probe when the surroundings changed, or
 every few frames, and keep `prefilter: false` for a probe that must
-refresh every frame on a tight budget. The faces hold LINEAR light (the probe owns
-`uOutputEncode` 0, `uToneMapping` 0 and `uExposure` 1 on its target,
-names the scene's fan-out then skips), HALF FLOAT where the device
+refresh every frame on a tight budget. The faces hold LINEAR light like every buffer (a
+probe is a buffer without a resolve), HALF FLOAT where the device
 renders it (`limits.halfFloatRenderable`, every GLES 3 device here: a
 sun's or an emissive's range survives into the reflection, as in every
 engine's HDR probe) and 8-bit clamped elsewhere - the renderer decides
-for all probes (Godot), not a per-probe knob (`probeFormat()` in
+for every target (Godot), not a per-probe knob (`bufferFormat()` in
 environment.ts) - and the probe never samples its own cube while
 rendering (a black environment stands in: one bounce). The face cameras are plain world-up cameras through an
 x-mirrored projection (`Camera.mirror`), because a GL cube face is seen
@@ -1185,9 +1512,8 @@ passes so cull modes keep their meaning. `examples/probe.tsx`.
 
 Baked sky: `scene.bakeBackground(size?)` is a reflection probe at the
 origin that sees no mesh (layer mask 0): the scene's background - the
-GLSL sky or the skybox - alone on its six faces, LINEAR (a sky ending in
-`outputColor` bakes its light; one writing fragColor raw bakes those
-bytes as light), prefilters it like a probe and returns the chain's
+GLSL sky or the skybox - alone on its six faces, LINEAR (a sky fragment writes light, so the bake stores exactly
+what the backdrop draws), prefilters it like a probe and returns the chain's
 TextureId for `environment={{ cube }}`: Godot's sky-to-radiance bake, so
 a procedural sky lights the scene with no light nodes, and the runtime
 way to turn a hi-res LDR skybox into a properly convolved environment
@@ -1195,8 +1521,8 @@ way to turn a hi-res LDR skybox into a properly convolved environment
 alternative). A snapshot at the probe format (half float where
 renderable; default size 128): bake again when the sky changes, and
 destroy the old cube - it is not auto-freed (an environment normally
-lives as long as the app). `outputColor` leaves linear output UNCLAMPED
-(the clamp sits in the display encode), so a sky's sun disc of 40.0
+lives as long as the app). A buffer is UNCLAMPED (the clamp sits in the
+resolve's encode), so a sky's sun disc of 40.0
 bakes as 40.0 and shows as the broad bright highlight on rough metal
 that HDR is for. A sky that reads
 `uCamPos` bakes from the origin; scene params (an app clock) are seen as
@@ -1245,7 +1571,8 @@ material drops the code from the program (Three's `material.fog`) - a
 sky sphere, a far backdrop. A shaderMaterial opts in by composing `FOG`
 from `/glsl` (declares the set; `fog(rgb, alpha, worldPos, camPos)`, or
 `fogAdditive(rgb, worldPos, camPos)` for a `blend: "add"` look, which
-fades toward black instead of the fog color).
+fades toward black instead of the fog color; a stock material with
+`blend: "add"` composes that form by itself).
 The BACKGROUND is not fogged: it is entry zero with no depth or
 distance, so match the fog color to `clearColor` or the background's
 horizon, and put `far` at or inside the camera's far plane to hide the
@@ -1258,26 +1585,65 @@ Color: the scene shades in LINEAR light and outputs sRGB, like Three
 (ColorManagement), Godot and Unity's linear space - no gamma mode. Every
 `[r, g, b]` color option is sRGB, what a color picker shows: material
 `color` and `emissive`, light `color`, the hemisphere's `sky`/`ground`,
-fog `color`; the library decodes it when it writes the uniform
-(`srgbToLinear`/`linearColor` are exported for values you write straight
-to a uniform yourself). Color MAPS decode through their format: create a
-base color, emissive or sky image with `format: "rgba8-srgb"`
-(createTexture, createCubeTexture; createModel does it for glTF's base
-color and emissive images) - a plain rgba8 map reads as linear data and
-renders washed out; data maps (normal, specular, roughness, light maps)
-stay rgba8, and an HDR image is "rgba16f". Vertex colors are linear, as
-glTF stores them. Every library fragment ends in the OUTPUT set's
-`outputColor(rgb, alpha)`: exposure (`scene.setExposure`, default 1),
-tone mapping (`scene.setToneMapping("none" | "aces")`, the reactive
-`toneMapping`/`exposure` props) and the sRGB encode, premultiplied. The
-scene target therefore holds encoded pixels like every texture the
-runtime displays; `clearColor` is written as given and is NOT tone
-mapped (with a curve on, draw the backdrop as a background), and a
-transparent mesh blends in encoded space (Three's compromise; the
-hardware-encode alternative would display wrong through the runtime's
-raw sampling). What changed for a scene tuned before this: terminators
-soften, mid-tones brighten, highlights widen - drop ambient rather than
-lights. `emissiveIntensity` scales the emissive in linear light.
+fog `color`, the scene's and a view's `clearColor`; the library decodes
+it when it writes the uniform or the clear (`srgbToLinear`/`linearColor`
+are exported for values you write straight to a uniform yourself). Color
+MAPS decode through their format: create a base color, emissive or sky
+image with `format: "rgba8-srgb"` (createTexture, createCubeTexture;
+createModel does it for glTF's base color and emissive images) - a plain
+rgba8 map reads as linear data and renders washed out; data maps
+(normal, specular, roughness, light maps) stay rgba8, and an HDR image
+is "rgba16f". Vertex colors are linear, as glTF stores them.
+
+Every target is a BUFFER plus a RESOLVE, Godot's and Unity's pipeline:
+the meshes draw into a linear buffer (`scene.hdrTexture` /
+`view.hdrTexture`: premultiplied linear light, half float where the
+device renders it - `limits.halfFloatRenderable`, every GLES 3 device
+here - else rgba8 linear and clamped; the renderer decides, no knob),
+and one full-screen pass, the resolve, writes the displayed rgba8
+`scene.texture`: exposure (`scene.setExposure`, default 1), tone mapping
+(`scene.setToneMapping("none" | "aces" | "agx" | "neutral")` - ACES the
+filmic curve every engine ships, AgX Blender's (Three, Godot 4.3+),
+Neutral the Khronos PBR curve (Three, Unity) that keeps product colors
+where a filmic curve shifts them; the reactive `toneMapping`/`exposure`
+props), then the sRGB encode with an ordered dither against banding,
+premultiplied. So a fragment - stock or custom -
+writes LINEAR light and never encodes (`sceneOutput` is fog only; a
+material has no output stage), a `transparent` mesh blends in linear
+space, the clearColor is tone mapped like a background is, and the
+resolve is an auto target, so a static scene still costs zero passes.
+The resolve is the post-effect slot: `resolve` on createScene/createView
+and the `<Scene>`/`<View3d>` prop - a source, `{ source, textures }`,
+or a function of the buffer id returning either, so a chain over
+`hdrTexture` is built before the resolve compiles - and
+`scene.setResolve` live with the same input. The
+source gets the shader-target contract (vUV, iResolution, fragColor),
+`uniform sampler2D uScene` (the buffer) and the RESOLVE set from `/glsl`
+declared: end with `fragColor = resolveColor(rgb, alpha)`; any
+`scene.setParams` name is readable; `DEFAULT_RESOLVE` is the stock one
+sample. BLOOM is stock: `bloom: { threshold?, intensity?, radius? }` on
+createScene, `scene.setBloom(opts | null)`, the reactive `bloom` prop -
+radiance above `threshold` (default 1, what a fully lit white surface
+reaches) blurred over `radius` rounds (default 2) of a separable blur
+at a quarter of the target's size and added back at `intensity`
+(default 0.5): Godot's glow, Unity's Bloom, Three's UnrealBloomPass. A
+chain of small auto passes per resolving target, re-rendered when the
+buffer is; views follow the scene's bloom unless they carry a `bloom`
+of their own (null = off, a clean minimap), the fog model. The glow is
+light: over a transparent backdrop (a view with no clearColor over UI)
+it still shows, its alpha its own brightness, and an opaque pixel is the
+plain sum. The default resolve composes it; a custom resolve does by declaring `uniform
+sampler2D uBloom; uniform float uBloomIntensity;` and adding the term
+(start from `BLOOM_RESOLVE` in `/glsl`; `examples/bloom.tsx` adds a
+vignette that way). `output` composes the DISPLAYED texture after the
+resolve, the place for an LDR effect (`examples/scene-post-effect.tsx`). Cost: one full-screen pass and
+double the color bandwidth per target, about 0.2 ms per 1080p target on
+an Intel iGPU (21 full-HD targets at once still ran at 36 fps); a
+device that cannot afford it renders a smaller buffer and the leaf
+scales it up. What changed for a scene tuned before linear light:
+terminators soften, mid-tones brighten, highlights widen - drop ambient
+rather than lights. `emissiveIntensity` scales the emissive in linear
+light.
 
 ### Lighting GLSL
 
@@ -1310,22 +1676,22 @@ three) and `SHADOW_LOOKUP`
 cast; it walks the light's slots and samples the first map that covers
 the point, which is the cascade select, blended into the next map over
 the outer `SHADOW_BLEND` of the map). A receiving fragment
-multiplies light i's term by `lightShadow(i, ...)`, exactly what `lit`
+multiplies light i's term by `lightShadow(i, ...)`, exactly what `phong`
 composes; a non-receiving one composes none of the three and declares no
 samplers. Lights, colors and exponents are arguments, so
-nothing is pinned but the function names; `lit` is composed from these
+nothing is pinned but the function names; `phong` is composed from these
 same constants - customizing never means leaving the system.
 
 ### Custom looks: three tiers
 
-A custom look is a citizen of the scene - lit by its lights, shadowed,
-fogged, exposed and tone mapped like the stock materials - at one of
-three tiers, top first:
+A custom look is a citizen of the scene - lit by its lights, shadowed
+and fogged like the stock materials, exposed and tone mapped by the same
+resolve - at one of three tiers, top first:
 
 1. STANDARD FRAGMENT, CUSTOM VERTEX. Any vertex stage that writes the lit
    varyings (vWorldPos, vNormal, vUv, plus vColor with `vertexColors`,
-   vUv2 with `lightMap`) pairs with `litFragment(options)` /
-   `standardFragment(options)` (`/glsl`): the exact fragment `lit` /
+   vUv2 with `lightMap`) pairs with `phongFragment(options)` /
+   `standardFragment(options)` (`/glsl`): the exact fragment `phong` /
    `standard` compile, the same option names and defaults as their
    options with the texture options boolean. An instanced or displaced
    mesh keeps the stock shading whole (`examples/instanced.tsx`: the
@@ -1337,7 +1703,7 @@ 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. `litFragment({ surface,
+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
@@ -1354,25 +1720,26 @@ three tiers, top first:
    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 the tone mapping and
-   output encoding by hand.
+   the light loop (tier 3) would have to match every light's falloff,
+   cone and shadow by hand.
 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
-   light list, the shadow set, the environment, fog and OUTPUT - declare
-   none of them yourself. Build a `Surface` with `surfaceOf(base,
+   light list, the shadow set, the environment and fog - declare none
+   of them yourself. Build a `Surface` with `surfaceOf(base,
    normal)`, set the fields you mean, call `shadeBlinn(s, position)` or
    `shadePbr(s, position)` (premultiplied rgb back: hemisphere, every
    light with its shadow, the environment term, the emissive), add your
    own terms times the alpha, and end with `sceneOutput(rgb, alpha,
-   position)` (fog, exposure, tone mapping, encode). A custom LIGHT MODEL
+   position)` (fog; the pixel is linear light, the resolve exposes, tone
+   maps and encodes it). A custom LIGHT MODEL
    loops `sceneLight(i, position, normal)` to `uLightCount` instead of a
    shade function: light i's direction and its color already attenuated,
    cone-faded and shadowed (zero when it cannot reach). The stock
    materials are built from this same set, so the tiers cannot drift.
    The demo `the-third-dimension.tsx` has tier 2 (the ground) and tier 3
    (the knot's rim term).
-`standardFragment(options)` is the same for `standard`: lit's options
+`standardFragment(options)` is the same for `standard`: phong's options
 minus `specularMap`/`env` (the environment is always composed) plus
 `metalnessMap`/`roughnessMap`, on the same `litVertex(options)`, with
 `uMetalness`/`uRoughness` in place of `uSpecular`/`uShininess`.
@@ -1391,7 +1758,7 @@ instance or every caster move warns about the skipped write.
 
 ### Lights
 
-Lights and `lit`: lights are graph NODES, like Three. `createDirectionalLight({
+Lights and `phong`: lights are graph NODES, like Three. `createDirectionalLight({
 direction?, color?, intensity? })` / `<DirectionalLight>` is parallel light
 travelling along `direction` in the node's LOCAL space (default `[0, -1,
 0]`, a sun overhead; length ignored), so a parent Group's rotation turns it
@@ -1413,10 +1780,12 @@ only, same falloff, no cone. `createHemisphereLight({ sky?, ground?, intensity?
 normal's tilt (fixed to world up, the node's transform is ignored); one per
 scene, the last attached wins. Placement goes through setTransform, the
 light's own fields through `setLight(light, { ... })` (frame-rate-safe,
-like setMeshParams). At most `MAX_LIGHTS` (8, exported from `/glsl`)
+like setMeshParams). At most `MAX_LIGHTS` (8, exported from the root and `/glsl`)
 lights per scene, directional, spot and point together (the hemisphere
-is not in the list) - the ninth throws at add(); it is a shader-source
-constant, fixed per app. `uLightDir` and `uLightPos` are core-driven:
+is not in the list) - a ninth is reported at the sync that settles the
+set, not at add() (a declarative swap's transient overlap is fine),
+the way a shadow-budget overflow is (see there), and the lights past
+the cap are not lit; it is a shader-source constant, fixed per app. `uLightDir` and `uLightPos` are core-driven:
 each light's slots are spatial-core shared-slot sinks following the
 node's world rotation (direction, negated so the shader reads the
 vector TOWARD the light) and world position, so a MOVING light costs no
@@ -1427,7 +1796,7 @@ LIGHT_POINT), `uLightDir[N]`/`uLightPos[N]`/`uLightColor[N]` (intensity
 folded into the color) and `uLightParams[N]` (cosInner, cosOuter,
 distance, decay) - so a custom fragment composing `LIGHT_SLOTS` +
 `LIGHT_LOOKUP` from `/glsl` reads the same list through `lightVector(i,
-worldPos, out l)` (returns the attenuation, 0 = skip the light; `lit`
+worldPos, out l)` (returns the attenuation, 0 = skip the light; `phong`
 is the shape), and a light change costs one write however many meshes.
 A custom fragment that declares only the old directional subset
 (`uLightCount`/`uLightDir`/`uLightColor`) still works - it just shades
@@ -1436,15 +1805,14 @@ scenes. Everything starts black: a lit scene with no light shows
 nothing, on purpose, like Three. `examples/lamps.tsx` is the spot/point
 shape (soft vs hard cone, casting spots, an orbiting bulb).
 
-### lit
+### phong
 
-`lit(opts)` is the standard look beside `unlit`: hemisphere ambient plus
-the directional list, Lambert diffuse, Blinn-Phong highlight when
+`phong(opts)` is the Blinn-Phong material (Three's MeshPhongMaterial, Unity
+URP's Simple Lit) beside `unlit`: hemisphere ambient plus the light list, Lambert diffuse, Blinn-Phong highlight when
 `specular` (0..1 strength) is set with `shininess` (default 30), a
 mirror of the scene's environment when `reflectivity` (0..1, the
 face-on weight; see Environment above) is set, blurred by the same
-`shininess`, the same `color`/`map`/`transparent` as unlit, `vertexColors: true` to
-multiply by the colored layout's aColor (so the geometry must carry it),
+`shininess`, the same `color`/`map`/`transparent`/`blend`/`vertexColors` as unlit,
 `triplanar: n` to sample `map` by world position at `n` repeats per
 world unit, blended across the three axis planes by the normal, and
 `alphaTest: t` for a cutout (a fragment whose final alpha is below `t`
@@ -1520,7 +1888,7 @@ split sum, `envRadiance` at the roughness over the cube's mip chain
 times the analytic `envBrdf` for the specular, `envIrradiance` on the
 diffuse beside the hemisphere - with no `reflectivity` switch: the
 environment is intrinsic to the model, and a baked environment with no
-lights at all lights a scene (`examples/environment.tsx`). Light intensities read as lit's
+lights at all lights a scene (`examples/environment.tsx`). Light intensities read as phong's
 (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
@@ -1554,7 +1922,7 @@ pre-order - name, parent index, local TRS; matrix-form nodes are
 TRS-decomposed, shear dropped; nodes that carry no part, joint or
 animation target anywhere - cameras, lights, unused empties - are
 pruned), `parts` (one per mesh primitive, its node's NAME kept, `node`
-index, vertices in the standard layout LOCAL to the node - except
+index, vertices in the base layout LOCAL to the node - except
 skinned parts: "skinned" layout, model-space bind pose, `skin` index),
 `skins` (joint node indices + inverse binds), `clips` (the animations
 as baked channel buffers: node/path/interpolation, times, values),
@@ -1564,7 +1932,9 @@ index into `images`, `doubleSided`, `transparent` = alphaMode BLEND,
 normal and emissive slots, `metalness`/`roughness` factors and the
 packed `metalnessRoughnessMap` - standard's inputs), `images`
 (the encoded PNG/JPEG bytes, undecoded) and `bounds` (world-space rest
-pose, conservative for parts under rotated nodes). External
+pose: a part's box through its node, a skinned part's per-joint boxes
+through the joints' rest transforms - where the skin places it, armature
+scale included; conservative under rotation). External
 files come through `resolve(uri)` (uri as written, still
 percent-encoded; `gltfExternalUris(bytes)` lists them so an async
 caller can read them first) - for a .gltf AND for a .glb, which is
@@ -1581,13 +1951,13 @@ first error a real file hits.
 
 #### createModel
 
-`createModel(data, { material?, label? })` - uploads the images (repeat
+`createModel(data, { material?, label?, autoFree? })` - uploads the images (repeat
 wrap, mipmapped, 4x anisotropic), makes one material per glTF material (default `standard`
 with the file's color, maps, normal scale, metalness/roughness and
 packed map, emissive and transparency - the glTF material model, so a
 scene showing a model wants an `environment` (a glTF metal in a scene
 with none renders near black); `material: (m, maps, skinned) =>
-lit({ color: m.color, map: maps.map ?? undefined, skinned })` for the
+phong({ color: m.color, map: maps.map ?? undefined, skinned })` for the
 Blinn-Phong look, or any other material; it is called once per material and shared), the node table as nested
 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)`,
@@ -1604,7 +1974,13 @@ them, nothing else frees them.
 #### loadGltf and loadModel
 
 `loadGltf(path)` / `loadModel(path)` - read from `assets/` with flux:fs
-and build. `loadModel` reads the baked `.srtm` written by `srt tool
+and build. Like every resource creator, a model frees with the owning
+reactive scope (`dispose()` at its cleanup; `autoFree: false` opts out):
+for the loaders that scope is the caller's at the call, captured before
+the await, so a model loaded inside a memo goes with the memo's rerun
+and one loaded in a component with its unmount. A load that settles
+after its scope is gone (unmounted mid-load) is freed on arrival and
+resolves already disposed - nothing owns it any more. `loadModel` reads the baked `.srtm` written by `srt tool
 3d/model <in.gltf|glb> -o assets/<name>.srtm`: the same parse run once
 under bun, stored in the GPU layout, so loading is views onto the file's
 bytes plus the image decodes. Numbers from a 32k-vertex, 6-texture model
@@ -1688,14 +2064,23 @@ Applied: `doubleSided` (the default material draws it with `cull:
 factor (a zero factor skips the map too - glTF's product rule, emission
 off), `pbrMetallicRoughness` factors as `m.metalness`/`m.roughness` and
 its packed texture as BOTH `maps.metalnessMap` and `maps.roughnessMap`
-(standard's channel-select options; the default `lit` ignores them).
-The `material(m, maps)` callback receives every uploaded texture
-by lit()/standard() option name (`maps.map`/`maps.normalMap`/
-`maps.emissiveMap`/`maps.metalnessMap`/`maps.roughnessMap`);
-`data.materials` is in file order, so the calls arrive in file order.
+(standard's channel-select options; the default `phong` ignores them).
+The `material(m, maps, skinned, vertexColors)` callback receives every
+uploaded texture by phong()/standard() option name (`maps.map`/
+`maps.normalMap`/`maps.emissiveMap`/`maps.metalnessMap`/
+`maps.roughnessMap`); `data.materials` is in file order, so the calls
+arrive in file order. A primitive's `COLOR_0` lands in its geometry's
+aColor (the "colored" layout, or the skinned list plus aColor for a
+rigged one; linear and premultiplied as glTF stores it) and the default
+material takes `vertexColors: true` for such parts - the callback's
+fourth argument says so, and a material shared by painted and unpainted
+parts is made once per variant, like the skinned split.
 A `.srtm` baked before the material records carried the PBR fields
-(file version 3) is rejected by loadModel - re-bake with `srt tool
-3d/model`.
+(file version 3), or before the vertex formats took the WebGPU spelling
+and byte counts (file version 5), is rejected by loadModel - re-bake
+with `srt tool 3d/model`. A baked part keeps a quantized export's
+bytes: u8 colors, u8/u16 joints and normalized weights, u16 uvs land in
+their own formats, positions and normals as floats.
 
 ### Animation
 
@@ -1779,14 +2164,66 @@ computed-once texture. `sampleChannel` (pure, from the root) stays the
 JS sampling core for checks and custom drivers;
 okf/done/animation-core.md records the design.
 
+### Morph targets
+
+Morph targets (blend shapes): a geometry carries named per-vertex
+deltas - `withMorphTargets(geometry, [{ name, position, normal? }])`
+for a hand-built shape, the loader's primitive targets for a glTF (its
+`extras.targetNames`, else `target<i>`; sparse accessors read) - packed
+SPARSE BY VERTEX on `geometry.morphs` (a header texel per vertex, then
+only the entries of the targets that move it; memory follows the
+authored deltas, never vertices x targets) and uploaded once per
+geometry as one rgba32f texture. A `morph: true` material (`phong`,
+`unlit`, `standard`; a custom class splices MORPH_DECLS and MORPH_APPLY
+from `@solidrt/3d/glsl` before its skin math) walks each vertex's
+entries in the vertex stage, before any skinning; a mesh under it
+whose geometry carries no targets is rejected at add(), and a plain
+material over morphed geometry draws the base shape. WEIGHTS belong to
+a NODE, glTF's `node.weights` model: a standalone mesh owns its own; a
+model's parts follow their glTF node (`model.nodes`), so a face split
+into skin, eyes and teeth parts takes one write. `setMorphWeights(node,
+{ smile: 0.7 })` writes by name (the others untouched), an array writes
+every target in order, the `<Mesh morphWeights>` prop is the
+declarative form; `getMorphWeights(node)` reads them back (from the
+core while in a scene), `getMorphNames(node)` lists the targets. The
+write lands in the spatial core's register (a row of a small weights
+texture, published at the flush like a skin palette - Three's
+morphTargetInfluences, Godot's set_blend_shape_value); a file's
+`mesh.weights` seed it. Weights ANIMATE two ways, both native: a glTF
+`weights` animation channel plays through the mixer like a TRS
+channel (into the owning node's register, crossfading across players
+by the same weighted average), and a write is a TARGET like a
+transform write - `setTransition(node, { weights: { duration: 300 } })`
+makes every setMorphWeights animate (springs by default; `from`/`exit`
+endpoints are one number per target, `delay` and `stagger` apply), and
+`setMorphWeights(node, { smile: 1 }, { duration: 300, bounce: 0.2 })`
+animates that one write on its own motion, declaration or not; a
+settle calls `onTransitionEnd` with component "weights". A playing
+weights track and a JS write are both producers of the register: the
+players advance before the frame's JS, so a write from onFrame wins
+that frame. `getMorphWeights` reads the core, so it shows a playing
+track and a mid-flight transition; the by-name partial write merges
+into the last JS-WRITTEN set, not the core's - write every target
+while a clip plays. An INSTANCED mesh morphs per instance: the
+population owns one weights texture with a row per record slot, each
+`<Instance>` (or addInstance node) owns a register published into its
+slot's row, and the shader reads the row by `gl_InstanceID` - so
+`setMorphWeights(instance, { smile: 1 })`, the `<Instance morphWeights>`
+prop, a `transition.weights` spring and a clip's weights track all work
+per copy, the shadow variants included, with no per-record data
+(Three's InstancedMesh morphs). Skinned plus morphed plus instanced
+composes. A custom class splicing MORPH_DECLS reads the row as
+`uMorphRow + gl_InstanceID`, which the stock decls already do. A record
+mesh (JS-written records, no nodes) cannot morph: rejected at add().
+
 ### Not in the subset
 
-Not in the subset, dropped: vertex colors, tangents and further UV sets;
-morph targets (the "weights" channel path); samplers are ignored (every
-texture repeats); additive blending draws as base color. The follow-ups
-are filed in okf/backlog/3d-model-loader.md. The `.srtm` container is
-VERSION 3 (node table in the header, node-local vertices, skins, clips);
-older bakes are rejected - re-bake with `srt tool 3d/model`.
+Not in the subset, dropped: tangents and further UV sets; samplers are
+ignored (every texture repeats); additive blending draws as base color.
+The follow-ups are filed in okf/backlog/3d-model-loader.md. The `.srtm`
+container is VERSION 8 (node table in the header, node-local vertices,
+skins, clips, packed morph targets); older bakes are rejected - re-bake
+with `srt tool 3d/model`.
 
 ## Traps
 
@@ -1809,6 +2246,16 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
   MODEL moves both. Shadows are the exception: the shadow variants
   (depth and cutout) skin by the same uBones palette, so a caster casts
   its pose.
+- Morphing is the same kind of effect: picking and the transparent sort
+  see the base shape, the shadow variants morph. The one thing the
+  retained side knows is the box: `geometryBounds` (and a model's
+  bounds) grow by the targets' extent, so a morphed shape is never
+  culled while its weights stay in 0..1 - a weight past 1 can leave it.
+  Normal deltas blend linearly like positions (Three's, Godot's and
+  glTF's rule): exact at a target, an approximation between two, so a
+  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.
 
 ### Materials and color
 
@@ -1818,8 +2265,8 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
   ambient probe, this does not). glTF's default metallic factor is 1,
   so an untextured asset is all metal, and createModel's default is
   `standard`: give a model scene an `environment` (loadEnvironment's
-  baked .srte, or the skybox's cube), or pass `lit` as the material.
-- Light intensities are the same numbers for `lit` and `standard`: 1
+  baked .srte, or the skybox's cube), or pass `phong` as the material.
+- Light intensities are the same numbers for `phong` and `standard`: 1
   lights a white matte surface to 1 face-on. A Three scene's intensities
   are a factor pi larger for the same look; divide when porting.
 - Transparency is an EXPLICIT material flag, Three's rule: `unlit({ color:
@@ -1833,8 +2280,8 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
   (or `shaderMaterial({ transparent: true })`) builds the pipeline with
   `blend: "alpha"` and `depthWrite: false` (depth test stays on, so it hides
   behind opaques without occluding other translucents). The one inference:
-  a `shaderMaterial` with any `blend` but "none" is transparent unless told
-  `transparent: false` - every blended draw belongs after the opaques, and
+  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
@@ -1857,9 +2304,11 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
   custom fragment (no material option yet); a draw target you create
   yourself can be `format: "rgba8-srgb"` and then decodes on sample (it
   is sampler-only: no display, readback or copy).
-- Reading the scene texture back (a probe's readTexture, a snapshot)
-  gives ENCODED pixels: an expected linear value v shows as
-  `linearToSrgb(v) * 255` - intensity 0.5 reads 188, not 128.
+- Reading `scene.texture` back (readTexture, a snapshot) gives ENCODED
+  pixels: an expected linear value v shows as `linearToSrgb(v) * 255` -
+  intensity 0.5 reads 188, not 128. The buffer, `scene.hdrTexture`, is
+  sampler-only (no readback, copy or display): read radiance through a
+  `createShaderTexture` pass over it, scaled into 0..1.
 
 ### Environment and background
 
@@ -1886,7 +2335,7 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
 - The environment binds through the light rewrite's map set (uEnv
   beside uShadowAtlas on every receiving target, new views included) and
   directly on setEnvironment; the placeholder cube is app-lifetime like
-  the shadow placeholder. A `lit` without `reflectivity` declares no
+  the shadow placeholder. A `phong` without `reflectivity` declares no
   environment sampler - the flag is part of the class key.
 
 ### Coordinates and rotation
@@ -1989,26 +2438,42 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
   flashes at the world origin for a frame.
 - Instancing pairs strictly at add(), like layout: an instanced material
   needs a createInstancedMesh or createRecordMesh mesh and vice versa,
-  and the record strides must match the material's attributes per slot
-  (the 16 floats of INSTANCE_MATRIX_ATTRIBUTES in slot 0 on an instanced
-  mesh, its style stride in slot 1; a record mesh is slot 0 only) - each
-  mismatch throws there, at creation for the mesh's own material and at
-  add() for a swapped one. The instance buffers are MESH-owned (unlike
-  shared geometry buffers): `disposeInstances` is their one free, and
-  the mesh cannot be re-added afterwards. Capacity grows by REPLACEMENT,
-  never resize: an addInstance or setRecords past capacity doubles into
-  new buffers and swaps them in (an instanced mesh's live records move
-  in one core `retargetRecords`, its style mirror republishes) -
-  amortized like a dynamic array, same policy as @solidrt/2d; size
-  `capacity` or the initial records to skip the copies. An instanced
-  mesh's style stride comes from its material AT CREATION: a later
-  setMaterial to a class with another slot-1 layout throws at the
+  and every instance buffer the material declares must be a layout the
+  mesh carries - the matrix (INSTANCE_MATRIX_ATTRIBUTES, the first
+  buffer of an instanced mesh) or a stream with the same attribute names
+  AND formats (a byte-equal layout in other formats decodes differently)
+  - each mismatch throws there, at creation for the mesh's own material
+  and at add() for a swapped one. The instance buffers are MESH-owned
+  (unlike shared geometry buffers): `disposeInstances` is their one
+  free, and the mesh cannot be re-added afterwards. Capacity grows by
+  REPLACEMENT, never resize: an addInstance or setRecords past capacity
+  doubles into new buffers and swaps them in (an instanced mesh's live
+  matrix records move in one core `retargetRecords`, every stream's
+  mirror republishes) - amortized like a dynamic array, same policy as
+  @solidrt/2d; size `capacity` or the initial records to skip the
+  copies. A mesh's stream layouts come from its material AT CREATION: a
+  later setMaterial to a class with another layout throws at the
   rebuild.
-- Style writes are mirrored, not immediate: `setInstanceStyle` lands in
-  `MeshInstances.style.data` and the scene's sync publishes the dirty
-  range - so a write on a mesh outside any scene shows once it is added
-  (the attach republishes the whole mirror), and reading the GPU buffer
-  back mid-frame can lag the mirror by one sync.
+- Record writes are mirrored, not immediate: `setInstanceStyle`,
+  `setRecords` and an `instanceAttribute` write land in the stream's
+  `data` and the scene's sync publishes the `dirty` range (`updateRecords`
+  marks it for accessor writes) - so a write on a mesh outside any scene
+  shows once it is added (the dirty range waits), and reading the GPU
+  buffer back mid-frame can lag the mirror by one sync. Growth replaces
+  `data`: hold the accessor, not the view.
+- The sugar is for FEW records, the mirror is for MANY. `setInstanceStyle`
+  over an all-float layout is indexed stores; over a packed layout (the
+  stock `float16x4` color included) it is a codec call per component,
+  and so is every accessor write. Measured at ten thousand instances
+  restyled every frame on a laptop under QuickJS: about 11 ms of JS per
+  frame through setInstanceStyle on a float layout, 19 ms on the half
+  color, 9 ms through the accessor, 5 ms through the mirror - and that
+  5 ms is the app's own per-instance tint math, the write itself is
+  free. A population restyled per frame writes the mirror in bulk:
+  a typed view over `stream.data` (a Float32Array as handed out, a
+  `Float16Array` over the stock color, indexed by slot times components)
+  filled in a plain loop, then ONE `updateRecords(mesh, { first, count
+  })` - zero per-component calls, the same shape as `setRecords`.
 - Instanced casters: `castShadow` on a populated mesh needs a depth pass
   with the instance placement in it - the stock materials' `instanced`
   carries one, a custom class needs `shadowVertex` (see shadows below);
@@ -2023,8 +2488,8 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
 - An instance node's own fields hold its LOCAL pose (relative to its
   parent, as for any node); the record the core writes is its pose
   relative to the MESH, composed through any group between them. A
-  removed instance's children stay parented to the dead node: remove()
-  one to re-use it. `disposeInstances` on an instanced mesh flushes the
+  destroyed instance takes its children with it, like any destroyed
+  node. `disposeInstances` on an instanced mesh flushes the
   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.
@@ -2076,7 +2541,10 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
   `overrideMaterial` is validated against every mesh's layout (at
   createView for the meshes present, at add() for later ones) exactly like
   a mesh's own material, so an override reading `aColor` throws for a
-  standard-layout mesh. Views are disposed by the scene; `view.dispose()`
+  base-layout mesh. An instanced mesh the override cannot place (it
+  declares no `instanceBuffers`) is skipped, which the view's output
+  cannot show, so the scene warns once per view naming it and the count
+  (over the settled set, at the flush after the attach). Views are disposed by the scene; `view.dispose()`
   only for dropping one early.
 - SCENE-WIDE uniforms go through that same shared channel via
   `scene.setParams({ uTime })`, and this is the single highest-leverage
@@ -2088,9 +2556,9 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
   however many meshes read it, with the motion itself in vertex shaders
   off that one clock. `params`/`setMeshParams` is the PER-MESH answer and
   is O(meshes) per frame; reach for it only when the value genuinely
-  differs per mesh. (`scene.texture` IS the draw target id, so
-  `setTargetParams(scene.texture, ...)` is the same write - setParams is
-  the sanctioned spelling.)
+  differs per mesh. (`scene.texture` is the RESOLVE's id, not the buffer the meshes
+  draw into, so `setTargetParams(scene.texture, ...)` reaches the
+  resolve alone - setParams is the only spelling.)
 
 ### Shader materials
 
@@ -2121,7 +2589,8 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
   the material then rejects standard geometry at add(). Do not mention
   aColor you do not read.
 - A custom fragment that ends in `fragColor = vec4(...)` bypasses the
-  scene: no fog, no exposure or tone mapping, no encode - and a
+  scene: no fog (exposure, tone mapping and the encode still happen, in
+  the resolve, so it must write LINEAR premultiplied light) - and a
   hand-rolled loop over `uLightDir` renders a spot light as a
   directional one (a lit rectangle on the floor, no cone). What you
   declare is what runs, and the engine injects nothing, so pick a tier
@@ -2183,7 +2652,8 @@ older bakes are rejected - re-bake with `srt tool 3d/model`.
   otherwise the shape is simply wrong, there is no open-profile mode.
 - `useScene()`/`Group`/`Mesh` throw outside `<Scene>` (default-less
   context).
-- Geometry local bounds cache on the Geometry (like its GPU buffers):
-  geometry is immutable after creation. Mutating `vertices` after a mesh
-  used them leaves stale bounds AND a stale GPU buffer - make a new
-  Geometry instead.
+- Geometry local bounds cache on the Geometry (like its GPU buffers and
+  the core's picking copy): mutating `vertices` after a mesh used them
+  leaves stale bounds, a stale GPU buffer AND a stale picking shape
+  until `updateVertices` publishes the range - write through the
+  accessor and call it, or make a new Geometry.