@solidrt/3d 0.0.50 → 0.0.52

package/AGENTS.md

@@ -4,60 +4,139 @@ A retained 3D scene graph above `@solidrt/core/gpu`. Meshes, materials and
 a camera compile to ONE depth-buffered draw target (`createDrawTarget` +
 one `addDraw` entry per mesh); the scene's output is an ordinary texture
 id composited as a `<texture>` leaf, so it takes layout, transforms,
-blendMode and pointer events like any element. Design rationale:
-`okf/research/scene-graph-3d.md` in the repo.
+blendMode and pointer events like any element.
 
 ## The model
 
 - Two layers. The imperative core is Solid-free: `createScene`,
   `createMesh(geometry, material)`, `add`/`remove`, `setTransform`,
-  `lookAt`, `getRotation`, `setVisible`, `setRenderOrder` - plain objects with dirty flags, batched to a
-  microtask,
-  one `setDrawParams` (uModel, plus uNormal for materials declaring it)
-  per changed mesh and ONE `setTargetParams` (the shared uViewProj +
-  uCamPos) per camera change, however many meshes. The component
-  face (`Scene`/`Group`/`Mesh`/`PerspectiveCamera`) syncs props into that
-  core over context and renders nothing itself.
+  `lookAt`, `getRotation`, `setVisible`, `setRenderOrder` - plain objects
+  over the spatial core (`flux:spatial`, `alloy/src/spatial/`): every node
+  in a scene has a core node, JS keeps the LOCAL position/quaternion/scale
+  as the readable truth and forwards each write, and the core's flush
+  (one call per microtask) recomputes only the moved subtrees and writes
+  each entry's uModel (plus uNormal for materials declaring it) and its
+  visibility switch itself - a move costs its subtree, never the scene.
+  ONE `setTargetParams` (the shared uViewProj + uCamPos) per camera
+  change, however many meshes. World matrices live in the core only:
+  `worldPosition`/`lookAt`/picking read them back (`worldMatrix`, pending
+  writes included). See okf/backlog/spatial-core.md for what still runs
+  in JS and why. The component face (`Scene`/`Group`/`Mesh`/
+  `PerspectiveCamera`) syncs props into that core over context and renders
+  nothing itself.
 - Rendering is the runtime's. The target is `render: "auto"`: it
   re-renders when entries change, so a STATIC scene costs zero passes and
   the library registers no frame loop. Continuous animation is the app's
   own `onFrame` writing a signal (declarative) or `setTransform` on a
   `ref`-grabbed node (the frame-rate escape hatch - signals carry
   structure, per-frame motion goes straight to the scene).
-- Two named vertex layouts (`Geometry.layout`, absent = "standard"):
-  "standard" is `aPos` vec3 + `aNormal` vec3 + `aUV` vec2 - what every
-  generator emits - and "colored" appends `aColor` vec4, the per-vertex
-  data channel (a tint, baked AO, any four scalars; standard name, your
-  contents). Derive colored geometry with `withColors(geometry, fill)` -
-  fill is a flat 4-per-vertex array or a per-vertex callback receiving
-  `(index, pos, normal, uv)`. Geometry and material layouts must match
-  (layout is stride); a mismatched pair throws at add(). The whole layout
+- VIEWS: `scene.createView({ width, height, overrideMaterial?, depth?,
+  clearColor?, ... })` renders the same scene into a second target from
+  its own camera (`view.setCamera`, the scene's CameraUpdate shape). Each
+  mesh gets one entry in the view's target bound as one more draw sink of
+  its CORE node, so the one flush writes every target - the app writes
+  nothing per view. Geometry buffers and (without an override) materials
+  are shared; the light set and `scene.setParams` names fan out to every
+  view, `view.setParams` is the view's own channel; the scene background
+  is not mirrored; a view has no picking. `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 (the override cannot know their record layout) and draws in add
+  order. `depth: "texture"` exposes `view.depthTexture`, the shadow-map
+  input. `ortho: { left, right, top, bottom }` on any camera swaps
+  perspective for `orthographic()` (`fov` ignored; `ortho: null` returns);
+  the scene's own camera takes it too, and pick() follows.
+  `examples/scene-views.tsx` is the shape.
+- SHADOWS are a view: `<DirectionalLight castShadow shadow={{ mapSize?,
+  bias?, normalBias?, camera? }}>` (`createDirectionalLight({ castShadow,
+  shadow })`, `setLight`) makes the scene own an internal
+  `createView({ depth: "texture", overrideMaterial: depth pass })` drawing
+  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 directional light may cast (each map is a pass, capped by
+  MAX_LIGHTS = MAX_SHADOWS): shadow slot i is directional light i's -
+  the map's depth id binds as the target-level `uShadowMap<i>` of the
+  scene and every non-shadow view (a white texel when light i does not
+  cast), `uShadowMatrix[i]` is its view's own view-projection (the whole
+  array is one write per shadow-camera move), `uShadowCast[i]` says
+  whether it casts, `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
+  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 3x3 PCF
+  on each casting light's own term. `examples/shadows.tsx` (three
+  casting lights) is the shape.
+- RETARGETED motion is native: `setTransition(node, { position:
+  { duration: 400 }, ... })` makes setTransform writes TARGETS the core
+  animates toward every frame (position/scale per lane, rotation along
+  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.
+- 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()`
+  = `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
+  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 colored vertices cost 12 floats
-  regardless - keep data-light passes (a wireframe reading only aPos) on
-  standard geometry.
+  attributes only keep the stride), so extra channels cost their floats on
+  every draw of that geometry - keep data-light passes (a wireframe
+  reading only aPos) on standard geometry. `layoutStride`/`layoutSlot`/
+  `layoutKey`/`layoutAttributes` are the layout arithmetic; two layouts
+  with equal keys interleave identically (merge requires that).
   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). Geometry GPU buffers are
-  lazy, shared, and app-lifetime (owner-scoped free would break sharing);
-  `disposeGeometry` frees them.
+  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. `disposeGeometry` is the immediate explicit free.
 - Materials dedupe hard: one program + one pipeline per material CLASS
   (unlit color, unlit map, each opaque or transparent), `depth: true` +
   `cull: "back"`; an instance is
   just per-entry uniforms (`uColor`) and bindings (`uMap`).
-- The pure pieces (`math.ts`, `bvh.ts`, `order.ts`) have check rigs in
-  `checks/`, run headless on flux from the repo root:
-  `bunx srt bundle -f --stdout packages/3d/checks/<name>-check.ts | target/release/flux - [seed]`.
-  They print PASS or FAIL lines and throw on failure (the flux binary exits
-  0 either way - read the output). Extend the rig when you change the module.
+- The pure pieces (`math.ts`, `order.ts`, `geometry.ts`,
+  `profile.ts`, `sweep.ts`, `gltf.ts`, `model-file.ts`) are Solid-free and
+  GPU-free BY DESIGN so they can be checked headless (and, for the two
+  model modules, run under bun in `tools/model.ts`); keep them that way.
+  The rigs under `checks/`
+  (`geometry-check`, `sweep-check`, `pick-check`, `order-check`,
+  `gltf-check`) run on
+  flux from the repo root: `bunx srt bundle -f --stdout
+  packages/3d/checks/<name>.ts | target/release/flux -`. Run the ones
+  touching what you changed.
 
 ## Components
 
 | Component | Props |
 | --- | --- |
-| `Scene` | `width`, `height` (target pixels), `clearColor?`, `background?` (fragment GLSL), `label?`, `ref?(scene)`, `output?(texture)`, `events?` (mesh pointer events, default on) |
+| `Scene` | `width`, `height` (target pixels), `clearColor?`, `background?` (fragment GLSL), `samples?` (1/2/4/8 MSAA), `label?`, `ref?(scene)`, `output?(texture)`, `events?` (mesh pointer events, default on) |
 | `Group` | `position?`, `rotation?` (Euler radians, XYZ order), `quaternion?` (either, not both), `scale?` (number = uniform), `visible?`, pointer events (below), `ref?(node)` |
 | `Mesh` | `geometry`, `material`, transforms as Group, `params?` (per-mesh uniforms, merge semantics - no unset), 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, 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 |
 | `PerspectiveCamera` | `fov?` (vertical DEGREES, default 60), `near?`, `far?`, `position?`, `lookAt?`, `up?` |
 
 Output composition: without `output`, `Scene` emits a minimal
@@ -76,8 +155,11 @@ Camera control: `createOrbitCamera(scene, { target?, azimuth?, elevation?,
 distance?, min/maxDistance?, min/maxElevation?, orbitSpeed?, rotateSpeed?,
 zoomSpeed?, zoomAnchor?, rotateAnchor?, panSpeed?, viewport?, clampTarget? })`
 - drag-to-rotate, pinch- and wheel-to-zoom, two-finger pan, optional
-auto-orbit. Input runs on core's `createTransform` recognizer, so drag and
-pinch arbitrate in the app-wide gesture arena (a viewport inside a scroller
+auto-orbit. The first argument is anything with the scene's `setCamera`: a
+Scene, or a View to drive one view's camera independently (one orbit per
+view, each handed the handlers of its own viewport element). Input runs on
+core's `createTransform` recognizer, so drag and pinch arbitrate in the
+app-wide gesture arena (a viewport inside a scroller
 does not double-handle) and rotation starts after the recognizer's slop;
 `zoomSpeed` weights both wheel and pinch. Two-finger translation pans (the
 scene tracks the fingers 1:1 at target depth, weighted by `panSpeed`) when
@@ -112,13 +194,16 @@ Picking: `scene.pick(x, y)` is project()'s inverse - the camera ray
 through a scene pixel, returning `Hit[]` (`{ mesh, distance, point }`,
 world units, nearest first; every hit along the ray, not just the front
 one). `scene.raycast(origin, direction)` is the world-space primitive
-under it. The volume tier: hits test each mesh's local bounding box,
-transformed exactly under any node transform (non-uniform scale
-included), so results are conservative - a ray through a knot's hole
-still hits (no `face`/`uv` fields until a triangle tier exists).
-Broadphase is a dynamic AABB tree (BVH) the sync walk keeps current from
-its own dirty set - maintenance is O(changed), a query O(log meshes) -
-so per-pointer-move picking puts no ceiling on scene size. Both methods
+under it.
+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),
+so hits carry `face`, `uv` and a world-space `normal` facing the ray, and
+a ray through a knot's hole misses. An instanced mesh is box-only (its
+explicit population bounds; records are opaque), so its hits have none of
+the three. Both methods
 flush pending writes first (the lookAt/project immediacy contract), and
 both skip invisible meshes.
 
@@ -137,40 +222,71 @@ automatically (opt out: `events={false}`); 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 natural
-size, under any ancestor transforms or viewBox fits (the hit test
+size, under any ancestor transforms or design-size fits (the hit test
 undoes them; localX/localY arrive in the leaf's layout frame). A leaf
 laid out at a different size (the supersampling pattern) uses
 `scene.handlersFor(() => ({ width, height }))` with its layout size.
 
-Geometry: `box(w?, h?, d?)`; `plane(w?, h?)`, `circle(radius?, seg?)` and
-`ring(inner?, outer?, seg?)` (XY, facing +z - rotate `[-Math.PI/2, 0, 0]`
-for a floor); `sphere(radius?, wSeg?, hSeg?)`;
-`cylinder(rTop?, rBottom?, height?, radialSeg?)` (y axis, capped; unequal
-radii taper it) and `cone(radius?, height?, radialSeg?)`;
-`torus(radius?, tube?, radialSeg?, tubularSeg?)` (lying flat, hole on the
-y axis) and `torusKnot(radius?, tube?, tubularSeg?, radialSeg?, p?, q?)`
+Geometry generators take ONE options object, every field optional with
+a default, named as Three names them: `box({ width, height, depth })`
+(1x1x1); `plane({ width, height })`, `circle({ radius, segments })` and
+`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, 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.
-`withColors(geometry, fill, label?)` derives a "colored"-layout copy of
-any standard-layout geometry (generator or hand-built), adding the
-`aColor` vec4 channel; the source is untouched.
-`fillColors(vertices, fill, first?, count?)` is the in-place primitive
-under it: writes the aColor slots of a colored-layout interleave you
-already own (a merging builder's packed buffer), reading pos/normal/uv
-from the buffer itself - so a packer that bakes transforms while writing
-hands the baker world-space vertices. `fill` indexes relative to
-`first`. It trusts the buffer's layout (no tag to check); withColors is
-the checked path.
+No positional form: `box()` is the default cube, `box({ label: "rock" })`
+names it. 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
+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
+`withColors(box(), fill)`. `packGeometry(verts, indices, options?)` is
+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.
+`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
+buffer itself - so a builder that bakes transforms while writing hands
+the baker world-space vertices. `fill` indexes relative to `first`.
+`fillColors(geometry, fill, first?, count?)` is its aColor spelling.
+
+Geometry as data: `transformGeometry(geometry, { position?, rotation?,
+quaternion?, scale? }, label?)` bakes a placement into a copy (the
+setTransform shape: Euler XYZ radians or a quaternion, number = uniform
+scale), positions through the matrix and normals through its
+inverse-transpose, renormalized - correct under non-uniform scale; uvs,
+colors, indices and layout copy through. `mergeGeometries(parts, label?)`
+concatenates parts into one geometry with offset indices (uint32 past 64k
+vertices); parts must share one layout, a mixed list throws. Together
+they collapse a static scene to one mesh per material - transform each
+part into place, merge, draw once - so only what actually moves keeps a
+node, a draw entry and a per-frame `uModel` write of its own. Both are
+pure array math (Three's `applyMatrix4` + `mergeGeometries`), no GPU
+call, and the source geometries are untouched. `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.
 
 Profile kit (2D outlines to solids, real texture UVs): a `Profile` is a
 closed XY polygon, bare `[x, y]` points crease, `{ p, smooth }` points
 share an averaged normal - `fillet(points, radius, segs?)` and
 `roundRect(w?, h?, radius?, segs?)` emit those (arc corners smooth).
 Winding is normalized, so either authoring direction works.
-`extrude(profile, depth?, bevel?, bevelSegs?)` sweeps along z, centered,
-with a quarter-round bevel at both rims; `lathe(profile, segs?, angle?,
-start?)` revolves a CLOSED (x = radius, y = height) profile about the y
+`extrude(profile, { depth, bevel, bevelSegments })` sweeps along z,
+centered, with a quarter-round bevel at both rims; `lathe(profile, {
+segments, angle, start })` revolves a CLOSED (x = radius, y = height) profile about the y
 axis - watertight by construction, flat caps on partial sweeps;
-`sweep(profile, path)` runs the profile along an open 3D polyline with
+`sweep(profile, path, options?)` runs the profile along an open 3D polyline with
 MITRED joints (each cross-section sits on its bend's bisector plane, so
 bends never gape or overlap) and flat caps at both ends. The path
 mirrors the profile convention: bare `[x, y, z]` points crease (a strap
@@ -178,10 +294,10 @@ folding over an edge), `{ p, smooth }` points shade continuous (tag a
 sampled curve's points); the profile's y starts as close to world up as
 the first segment allows, then parallel-transports without spinning.
 Closed loops are NOT supported yet - overlap the ends by a segment to
-fake one. `tube(path, radius?, radialSegs?)` is the round-profile
+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)` fills one flat (facing +z,
+custom work along a path. `shape(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.
@@ -190,6 +306,17 @@ Materials:
 
 - `unlit({ color?, map? })` - straight `[r, g, b, a?]` 0..1, premultiplied
   internally.
+- `sprite({ color?, map?, transparent?, 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
+  tree/character sprite; the default `"full"` is Three's Sprite, flat to
+  the screen). No per-frame JS however many sprites. `transparent`
+  defaults to TRUE here (cutouts; Three's SpriteMaterial default), cull is
+  off. Draw with `createSprite(material)` / `<Sprite>`: a Mesh over a
+  shared unit plane, no geometry argument, `scale` = world size, rotation
+  ignored. Picks by a unit box around its center (its reach at any
+  facing), so hits carry no normal/face/uv. `examples/sprites.tsx`.
 - `shaderMaterial({ vertex, fragment, params?, textures?, depth?,
   depthWrite?, blend?, cull?, topology?, label? })` - your own GLSL, the
   custom-look escape hatch. The STANDARD UNIFORM SET: the vertex stage
@@ -207,9 +334,11 @@ Materials:
   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
-  geometry's layout by name; a vertex stage reading `in vec4 aColor` opts
-  the material into the "colored" layout, and its meshes then need
-  `withColors()` geometry. Sources without `#version` get the standard
+  geometry's layout by name; the ones the linked program actually reads
+  (engine reflection, instance attributes excluded) must all be in the
+  mesh's geometry layout or add() throws - so a used `in vec4 aColor`
+  needs `withColors()` geometry and a custom channel needs
+  `withAttribute()`. One program per class, one pipeline per layout met. Sources without `#version` get the standard
   pipeline preamble. App-driven uniforms beyond the standard set: seed
   via `params`, then write per mesh with
   `setMeshParams(mesh, { name: value })` (validated names; values persist
@@ -225,6 +354,35 @@ Materials:
   pipeline with its own values. `dispose()` lives on the class alone.
   `shaderMaterial(opts)` is exactly a class with one instance (its
   `dispose` forwards to the class).
+- `instanceAttributes: [{ name, format }]` 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 of the mesh's instance buffer. Its meshes come from
+  `createInstancedMesh` (below); a `createMesh` mesh is rejected at add().
+
+Instancing - one draw entry covering a population:
+`createInstancedMesh(geometry, material, records, count?, { bounds?,
+label? })` returns an ordinary Mesh whose entry draws the geometry once
+per record. `records` is the interleaved per-instance data (stride = the
+material's instanceAttributes summed, a mismatch throws), uploaded to a
+mesh-owned buffer whose capacity starts at the records given. `count` picks how
+many records draw (default all). Everything mesh works unchanged:
+setTransform moves the whole population through one uModel, setVisible
+zeroes the drawn count and restores the record count on unhide,
+renderOrder/params/geometry/material swaps apply. `setInstances(mesh,
+records, count?)` rewrites records 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), `setInstanceCount(mesh, n)` is the population dial (clamped to capacity;
+frame-rate-safe), and `disposeInstances(mesh)` detaches and frees the
+record buffer - the one explicit free, geometry-buffer rule. Records are
+opaque data (position/yaw/tint/whatever your shader reads), NOT matrices:
+a per-instance mat4 would be four vec4 columns reassembled in the shader,
+but most fleets want a few floats. Picking: the library cannot know where
+records place instances, so an instanced mesh has NO picking leaf unless
+you pass `bounds` (local, covering the population) - then it picks and
+transparent-sorts conservatively as one box. `examples/instanced.tsx` is
+the live proof.
 
 Background: `scene.setBackground(source | null)`, the `background` option
 on createScene, and the reactive `Scene` prop. Fragment GLSL drawn as the
@@ -245,28 +403,148 @@ Lighting GLSL (`@solidrt/3d/glsl`): exported string constants composed
 into shaderMaterial sources with plain template literals - `LIT_VERTEX`
 (the standard vertex stage: clip position plus vWorldPos/vNormal/vUv
 varyings, normals via mat3(uNormal)), `LIT_VERTEX_COLORED` (the same
-plus the colored layout's aColor forwarded raw as vColor - using it opts
-the material into that layout) and the pure functions `HEMISPHERE`
+plus the colored layout's aColor forwarded raw as vColor - using it makes
+the material need that channel) and the pure functions `HEMISPHERE`
 (`hemisphere(n, sky, ground)`), `LAMBERT` (`lambert(n, l)`),
 `BLINN_SPECULAR` (`blinnSpecular(n, v, l, shininess)`), `FRESNEL`
-(`fresnel(n, v, power)`). Lights, colors and exponents are arguments, so
-nothing is pinned but the function names; future lit material classes
-compose from these same constants - customizing never means leaving the
-system.
+(`fresnel(n, v, power)`), and the shadow trio composed IN ORDER:
+`SHADOW_SLOTS` (the scene's shadow set: `uShadowMap0..N-1`,
+`uShadowMatrix[N]`, `uShadowCast[N]`, `uShadowBias[N]`,
+`uShadowNormalBias[N]`, slot i = directional light i), `SHADOW`
+(`shadow(map, coord, bias)` - one map's 3x3 PCF factor) and
+`SHADOW_LOOKUP` (`lightShadow(i, worldPos, n)` - light i's factor, 1
+when it does not cast; it hides the if-chain that picks the map, since
+GLSL ES 3.00 forbids dynamic sampler indexing). A receiving fragment
+multiplies light i's term by `lightShadow(i, ...)`, exactly what `lit`
+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
+same constants - customizing never means leaving the system.
+
+Lights and `lit`: 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
+and position/scale do not matter - deliberately a direction, not Three's
+position-minus-target. `createHemisphereLight({ sky?, ground?, intensity?
+})` / `<HemisphereLight>` is the ambient term, a gradient by the WORLD
+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` (4, exported from `/glsl`)
+directional lights per scene - the fifth throws at add(); it is a
+shader-source constant, fixed per app. `uLightDir` is core-driven: each
+directional light's slot is a spatial-core shared-slot sink following
+the node's world rotation, so a MOVING light costs no JS. The sync
+rewrites the rest whenever a light attaches, detaches or changes a
+field -
+`uHemiSky`/`uHemiGround` (vec3, intensity folded in), `uLightCount` (int),
+`uLightDir[MAX_LIGHTS]`/`uLightColor[MAX_LIGHTS]` (world-space vector
+TOWARD the light, normalized; intensity folded into the color) - so a
+custom fragment declaring those names reads the same list, and a light
+change costs one write however many meshes. Everything starts black: a
+lit scene with no light shows nothing, on purpose, like Three.
+
+`lit(opts)` is the standard look beside `unlit`: hemisphere ambient plus
+the directional list, Lambert diffuse, Blinn-Phong highlight when
+`specular` (0..1 strength) is set with `shininess` (default 30), the
+same `color`/`map`/`transparent` as unlit, `vertexColors: true` to
+multiply by the colored layout's aColor (so the geometry must carry it),
+and `triplanar: n` to sample `map` by world position at `n` repeats per
+world unit, blended across the three axis planes by the normal. Triplanar
+is an OPTION, not the default: generators emit 0..1 UVs per face, so a
+map on a plane is a decal (UV) while a map on generated scenery wants one
+density across parts of any size (triplanar); the map must be created
+with `wrap: "repeat"`. Internally one `shaderMaterialClass` per option
+combination (map x vertexColors x triplanar x transparent), cached for
+the app's lifetime, one pipeline per vertex layout - a thousand lit
+meshes share one program. The view vector comes from the shared uCamPos;
+`uTriplanar` is declared only by the triplanar classes so the other
+classes do not warn about an inactive uniform.
+
+## Models
+
+Authored models come in as glTF 2.0 (.gltf with its .bin and image files
+next to it, or single-file .glb) and become a Group of meshes, Three's
+`gltf.scene`. Three layers, use the lowest that fits:
+
+- `parseGltf(bytes, resolve?)` - the pure parser (no engine, runs under
+  bun and on flux): `ModelData` = `parts` (one per mesh node, its NAME
+  kept, vertices in the standard layout with the node's WORLD transform
+  baked in), `materials` (base color factor, `map` = index into `images`,
+  `doubleSided`, `transparent` = alphaMode BLEND), `images` (the encoded
+  PNG/JPEG bytes, undecoded) and `bounds`. A .gltf's external files come
+  through `resolve(uri)` (uri as written, still percent-encoded;
+  `gltfExternalUris(bytes)` lists them so an async caller can read them
+  first); .glb and data: uris need none. Missing normals produce FLAT
+  shading (the spec's rule): the primitive is un-indexed, one vertex per
+  corner. A mirroring node flips the winding so `cull: "back"` still
+  keeps the outside. Non-triangle primitives are skipped; a required
+  extension the parser does not implement throws naming it, and Draco or
+  meshopt compression throws "re-export without mesh compression" -
+  Blender exports Draco by DEFAULT, so that is the first error a real
+  file hits.
+- `createModel(data, { material?, label? })` - uploads the images (repeat
+  wrap, mipmapped), makes one material per glTF material (default `lit({
+  color, map, transparent })`; pass `material(m, map)` for anything else,
+  it is called once per material and shared), one mesh per part, all
+  children of the returned `Model` (a Group): `add(scene.root, model)`,
+  place it with `setTransform`, find parts by name in `model.parts`
+  (`{ name, mesh }`), `model.bounds` for framing a camera. `dispose()`
+  detaches it and frees the geometry buffers and textures - the model owns
+  them, nothing else frees them.
+- `loadGltf(path)` / `loadModel(path)` - read from `assets/` with flux:fs
+  and build. `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
+  on a release client: `parseGltf` 124 ms on flux (22 ms under bun) against
+  40 ms for the whole baked load - the runtime parse is fine for small
+  models and a binary import (`import bytes from "./x.glb" with { type:
+  "binary" }` then `createModel(parseGltf(bytes))`, see
+  `examples/model.tsx`); bake anything big.
+
+Not in the subset, reported or dropped: `doubleSided` is reported and NOT
+applied (the standard materials cull back faces); vertex colors, tangents
+and further UV sets are dropped; samplers are ignored (every texture
+repeats); alphaMode MASK draws opaque; emissive/additive parts of a model
+draw as their base color (a model's "glow" cards come out as dark wedges).
+The follow-ups are filed in okf/backlog/3d-model-loader.md.
 
 ## Traps
 
+- A model's vertices are in WORLD space at parse time (node transforms
+  baked), so `model.bounds` and each part's geometry already include the
+  file's placement; the Model group starts at identity and `setTransform`
+  on it moves the whole thing. Parts cannot be moved relative to their
+  glTF parent - that is the retained-hierarchy follow-up, not a bug.
 - The y-down clip flip is baked into `perspective()`; scene code and
   geometry are plain y-up right-handed, and CCW-outward winding culls
   correctly with `cull: "back"`. Do NOT negate y anywhere else, and do not
   "fix" the negated row of `perspective()` - both would mirror the winding
   and show mesh interiors.
 - `visible: false` keeps the entry, drawn with `instanceCount: 0` (a
-  cheap off switch). Hidden meshes skip uModel writes; the fresh matrix is
+  cheap off switch); unhiding writes 1, or the mesh's own record count
+  when it is instanced - never a bare 1 into an instanced entry. Hidden
+  meshes skip uModel writes; the fresh matrix is
   written on unhide. A freshly attached entry starts off the same way and
-  sync() turns it on when it writes uModel - never add one live: it has no
-  world matrix yet, and drawn before the sync microtask it flashes at the
-  world origin for a frame.
+  the core's flush turns it on when it writes uModel - never add one
+  live: it has no world matrix yet, and drawn before the sync microtask it
+  flashes at the world origin for a frame.
+- Instancing pairs strictly at add(), like layout: an instanced material
+  needs a createInstancedMesh mesh (records included) and vice versa, and
+  the record stride must match the material's attributes - each mismatch
+  throws there. The instance buffer is MESH-owned (unlike shared geometry
+  buffers): `disposeInstances` is its one free, and the mesh cannot be
+  re-added afterwards. Capacity grows by REPLACEMENT, never resize:
+  `setInstances` past capacity doubles (at least to the records written)
+  into a new buffer and swaps it in - amortized like a dynamic array, same
+  policy as @solidrt/2d; size the initial records to skip the copies.
+- An instanced mesh without explicit `bounds` has no BVH leaf: it never
+  picks, pointer events never target it, and its transparent sort key
+  falls back to the node's world position. That is deliberate - records
+  are opaque to the library, so any inferred box would be a guess. Supply
+  `bounds` for anything pickable or transparent.
 - Transparency is an EXPLICIT material flag, Three's rule: `unlit({ color:
   [r, g, b, 0.5] })` still draws opaque; `unlit({ ..., transparent: true })`
   (or `shaderMaterial({ transparent: true })`) builds the pipeline with
@@ -362,7 +640,34 @@ system.
   target state), independent of mesh count - never reintroduce per-mesh
   camera writes (uEye-style per-mesh params are exactly the O(scene) cost
   the shared channel removed). Scene scale honestly: hundreds to a
-  few thousand objects, bounded by the interpreter, not the GPU.
+  few thousand objects, bounded by the interpreter, not the GPU. A view
+  is one more such write per camera change and one more entry per mesh
+  at attach; a view's per-frame cost is the core's (one params write per
+  sink per moved node), never JS.
+- A CASTING light's position matters (nothing else about a directional
+  light's position does): the shadow camera is placed AT the light node's
+  world position, Three's rule, so a `castShadow` sun at the origin
+  pointing down shadows nothing above it - give it a `position` above the
+  scene and a frustum (`shadow.camera`) that covers the casters. Acne
+  knobs are Three's: `shadow.bias` (map depth units) and
+  `shadow.normalBias` (world units along the receiver normal, the one to
+  reach for first, ~0.02); the depth pass culls FRONT faces (Three's
+  shadowSide default), so closed casters need little bias but a
+  single-sided plane casts nothing. Opting out of receiving is on the
+  MATERIAL here (`receiveShadow: false`), not the object (Three's
+  `mesh.receiveShadow`) - Godot's split, and URP's - and instanced
+  meshes never cast (the depth override cannot know their records) - the
+  additive follow-up is a per-class `shadowVertex`. Every casting light
+  is a full extra pass over the casters plus a sampler unit on every
+  receiving program (MAX_LIGHTS of those are always bound, placeholders
+  included), so cast from the lights that matter, not all of them.
+- A mesh's entries are mirrored into every view at attach and dropped at
+  detach; `setGeometry`/`setMaterial` rebuild them everywhere. An
+  `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()`
+  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
   pattern in the library. It merges an app-owned name in beside
@@ -408,18 +713,19 @@ system.
   a cache. A class instance has no `dispose` of its own; disposing the
   class invalidates every instance.
 - A parameterised class whose variants (mapped/unmapped, ...) are SEPARATE
-  classes must have every variant reference every shared uniform it is
-  seeded with: a declared-but-unused per-entry name compiles out and
-  throws at add(). Open item: `okf/backlog/gpu-inactive-uniform-two-tier.md`.
+  classes may seed every variant with one param/texture object: a uniform
+  a variant declares but does not use compiles out, and the engine then
+  accepts the write with a warning and skips it. A name no variant
+  DECLARES still throws at add().
 - The standard-set contract is checked TEXTUALLY at shaderMaterial()
   creation (uModel and uViewProj must appear in the vertex source) and
-  strictly at add() for the per-entry names: a uModel or uNormal that is
-  declared but never USED compiles out, and the scene's entry seed then
-  throws at attach (the engine rejects unknown entry uniform names). The
-  shared names have no such backstop - a declared-but-unused uViewProj or
-  uCamPos is skipped silently (shared params tolerate zero coverage), so
-  the symptom is an untransformed or unlit render, not an error. Use what
-  you declare.
+  at add() for the per-entry names: a uModel or uNormal that is declared
+  but never USED compiles out, and the scene's entry seed is then skipped
+  with an engine warning (the engine rejects only names the program never
+  declared). The shared names have no such backstop - a declared-but-unused
+  uViewProj or uCamPos is skipped silently (shared params tolerate zero
+  coverage), so the symptom is an untransformed or unlit render, not an
+  error. Use what you declare.
 - The layout scan is textual the same way: any `aColor` token in the
   vertex source - a comment counts - selects the "colored" layout, and
   the material then rejects standard geometry at add(). Do not mention
@@ -431,11 +737,11 @@ system.
   interpreter-hostile; that tier is core work (BVH descent per the
   differentiators ladder).
 - `scene.handlers` vs `handlersFor`: localX/localY arrive in the leaf's
-  LAYOUT frame (every ancestor transform and viewBox fit is already
+  LAYOUT frame (every ancestor transform and design-size fit is already
   undone by the element hit test). `handlers` therefore assumes leaf
   layout == target pixels; scaling by `getBoundingBox` would be WRONG -
   the box composes transforms, and it would double-correct the built-in
-  leaf under a viewBox. Only a leaf whose layout size deliberately
+  leaf under a design size. Only a leaf whose layout size deliberately
   differs from the target (supersampling) needs `handlersFor`, fed the
   layout size the app itself set.
 - Hover (enter/leave) reacts to pointer MOTION only: a mesh animating