@solidrt/3d 0.0.63 → 0.0.65

package/AGENTS.md

@@ -161,8 +161,11 @@ Groups), and each target carries a mask (default 1) - `layers` on
 createScene/createView, live via `setLayers` on the scene handle and
 each view. A mesh draws where mask & layers is non-zero, so a minimap's
 marker meshes live on bit 2: invisible in the main render, drawn by
-the map view whose mask admits them. Shadow views follow the SCENE's
-mask (what the scene cannot see must not darken it), and
+the map view whose mask admits them. LIGHTS carry a `layers` mask too
+(all bits by default, see Lights below): a light lights and shadows
+only the meshes its mask intersects. Shadow views follow the SCENE's
+mask (what the scene cannot see must not darken it) narrowed by their
+light's own `layers`, and
 pick()/raycast()/overlap()/sweep() skip scene-masked-out meshes like
 invisible ones - unless the query passes its own `{ layers }`, which is
 how a low-poly collision mesh lives undrawn in the scene yet answers
@@ -172,8 +175,12 @@ hides its whole interior, but frustum culling cannot know that and
 there is no occlusion or portal culling. Put the interior, the shell
 and an opening "plug" on their own layers and switch the scene mask by
 the camera's zone (inside, outside, in the doorway) - the reactive
-`<Scene layers>` makes it one signal, and a light's reach is masked
-the same way once lights carry layers.
+`<Scene layers>` makes it one signal - and mask each light (and the
+hemisphere) to its side the same way, so the sun does not light the
+room through its shell nor the room's bulb the street. Light `layers`
+cannot mask the ENVIRONMENT term (image lighting is per target, not
+per light): the interior meshes take `environment={null}` - or an
+interior probe's cube - instead (Mesh.environment, see Environment).
 Per-view fog: `fog: FogOptions | null` on createView overrides the
 scene's fog for that view (null = unfogged - the clear minimap over a
 fogged scene); absent follows the scene. `overrideMaterial` (Three's
@@ -538,27 +545,30 @@ faces); an instance is just per-entry uniforms (`uColor`) and bindings
 ### Pure pieces and checks
 
 The pure pieces (`math.ts`, `color.ts`, `geometry.ts`,
-`profile.ts`, `sweep.ts`, `gltf.ts`, `model-file.ts`) are Solid-free and
+`profile.ts`, `sweep.ts`, `gltf.ts`, `model-file.ts`, `splat-data.ts`)
+are Solid-free and
 GPU-free BY DESIGN so they can be checked headless and run under bun:
 `src/model-data.ts` re-exports exactly this set as the published
 `@solidrt/3d/model` entry (the bake tool and app bake scripts), and
-`tests/model-data.test.ts` imports it under `bun test`, so a runtime
-import creeping into any of them fails there; keep them that way.
-The rigs under `checks/`
-(`geometry-check`, `sweep-check`, `pick-check`, `dispatch-check`,
-`gltf-check`) run on
-flux from the repo root: `bunx srt bundle -f --stdout
-packages/3d/checks/<name>.ts | target/release/flux -`. Run the ones
-touching what you changed. `raycast-check.tsx` and
-`collision-check.tsx` are the exceptions: they assert the documented
-picking contract (triangle accuracy, the box tier, pick/raycast
-parity, layer masks, the `{ meshes }` filter) and collision contract
-(exact sweep times, the surface rule, the slide filter, layers and
-meshes on overlap/sweep, moveAndSlide's landing) against a real scene,
-so they run on the playback client instead:
-`bunx srt render packages/3d/checks/<name>.tsx --project --duration 3
---size 128x128`. Run them whenever a doc edit touches picking or
-collision claims - two copies of this contract have drifted before.
+`tests/model-data.test.ts` imports it under `srt test`, on the bare flux
+binary, so a gui or `srt:` import creeping into any of them fails there
+(a headless `flux:` import would not); keep them that way.
+`src/splat-data.ts` is its own published entry the same way
+(`@solidrt/3d/splat`, guarded by `tests/splat-data.test.ts`).
+The tests under `tests/` run with `bun run srt test packages/3d` from the
+repo root, or one file, or `--filter <text>` for the tests whose name
+contains it: the pure modules on the bare flux binary, and the files
+that need a GPU (`.test.tsx`, importing `@solidrt/test`) on the
+headless dev client. Run them after a change. `raycast.test.tsx` and
+`collision.test.tsx` assert the documented picking contract (triangle
+accuracy, the box tier, pick/raycast parity, layer masks, the
+`{ meshes }` filter) and collision contract (exact sweep times, the
+surface rule, the slide filter, layers and meshes on overlap/sweep,
+moveAndSlide's landing) against a real scene; run them whenever a doc
+edit touches picking or collision claims - two copies of this contract
+have drifted before. `fog.test.tsx` reads the fog example's pixels
+through its debug commands, and `camera-components.test.tsx` drives
+`<OrbitCamera>` and `<FirstPersonCamera>` with a real drag and key.
 
 ## Components
 
@@ -573,9 +583,10 @@ collision claims - two copies of this contract have drifted before.
 | `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), `frustumCulled?` (default true; false for geometry a vertex stage moves beyond the node's box - a billboard, a fullscreen quad; see Culling), `cullMargin?` (world units of slack around the box for bounded displacement), pointer events (below), `ref?(mesh)` |
 | `Sprite` | as Mesh minus `geometry`: a camera-facing unit quad, `scale` is its world size, rotation is ignored; pair with a `sprite()` material |
-| `InstancedMesh` | as Mesh (an instanced `material`: a stock one with `instanced`/`instanceColors`, or a class declaring INSTANCE_MATRIX_ATTRIBUTES), plus `capacity?` (instance slots, default 64; the buffers double past it), `bounds?` (an optional cull box, never a hit: instances pick by themselves, and without it the mesh culls by their union), `label?`; a PARENT: `<Instance>` children populate it, `<Group>` children are squads; the record buffers are component-owned and freed on unmount, and `anchor?` (a SceneNode, fixed at creation: the ancestor the records are relative to, so `<Instance mesh>` children may sit anywhere under it - see createInstancedMesh) |
+| `InstancedMesh` | as Mesh (an instanced `material`: a stock one with `instanced`/`instanceColors`, or a class declaring INSTANCE_MATRIX_ATTRIBUTES), plus `capacity?` (instance slots, default 64; the buffers double past it), `bounds?` (an optional cull box, never a hit: instances pick by themselves, and without it the mesh culls by their union), `instanceOrder?` (draw the records in key order, fixed at creation - see "Instance order"), `label?`; a PARENT: `<Instance>` children populate it, `<Group>` children are squads; the record buffers are component-owned and freed on unmount, and `anchor?` (a SceneNode, fixed at creation: the ancestor the records are relative to, so `<Instance mesh>` children may sit anywhere under it - see createInstancedMesh) |
 | `Instance` | one instance of the enclosing `InstancedMesh`: transforms, `transition`, pointer events as Group, plus `style?` (the material's style record, one value per component - `[r, g, b, a]` under `instanceColors`), `ref?(instance)`; a parent too (a `<Mesh>` under an instance rides with it), and `mesh?` (the population, fixed at creation, when the instance is placed outside its `<InstancedMesh>` - inside that mesh's `anchor` subtree) |
-| `RecordMesh` | as Mesh, plus `records` (the per-instance records in the material's first instance layout, an ArrayBufferView; buffer capacity starts at the first value and grows on larger rewrites), `count?` (records drawn, default all), `bounds?` (local [minX..maxZ] over the population - without it the mesh never picks); the record buffers are component-owned and freed on unmount |
+| `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), `instanceOrder?` (draw the records in key order, fixed at creation - see "Instance order"), `transfer?` (hand the records to the engine at creation, the write-once form - a later `records` value then throws; see "Instance order"); the record buffers are component-owned and freed on unmount |
+| `SplatMesh` | as Mesh, plus `data` (a baked SplatData from loadSplat; write-once under the default transfer - swap clouds by remounting), `count?` (splats drawn, default all; records are importance-sorted at bake, so a prefix is the scene at that size), `material?` (a fork of the stock splat class) and `transfer?` (default true: records go to the engine, halving residency; see "Splats"); bounds, the back-to-front instance order and the stock material come from the bake |
 | `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)` |
@@ -799,7 +810,7 @@ driving - the predicate every camera control shares) are reactive
 (HUD-safe); the pose is plain state via `pose()`/`set()` (also the
 debug-command shape). It drives position and target only; fov/near/far
 stay on scene.setCamera (or the Scene `camera` prop). The auto-orbit
-pauses while a gesture is open. checks/orbit-check.ts pins every stage
+pauses while a gesture is open. tests/orbit.test.ts pins every stage
 headless.
 
 In a component tree, skip the wiring: `<OrbitCamera input={input}
@@ -857,7 +868,7 @@ the shot's recording target, so an `<OrbitCamera>` or
 it, the container runs the blend on frames while one is in flight. A
 shot's picks and raycasts (`anchor`, `occlusion`) go through the
 owner's actual camera, which is the shot's own only while it is live
-and at rest. Pinned in checks/orbit-check.ts; probes/shots-3d-probe.tsx
+and at rest. Pinned in tests/orbit.test.ts; probes/shots-3d-probe.tsx
 is the live guard.
 
 ### First-person camera
@@ -920,8 +931,8 @@ swap with it), `moveSpeed`/`lookSpeed` follow their props, and a pitch
 clamp change re-clamps at once. Like the orbit control it drives
 position and yaw/pitch only: fov/near/far stay on scene.setCamera (or
 the Scene `camera` prop), so a walker in a scene bigger than the default
-`far` of 100 sets one there. checks/orbit-check.ts and
-checks/first-person-check.ts pin both controls headless (they import
+`far` of 100 sets one there. tests/orbit.test.ts and
+tests/first-person.test.ts pin both controls headless (they import
 `@solidrt/core/input` only).
 
 ### Overlay projection
@@ -1073,7 +1084,9 @@ repeats within 300 ms and 20 px on the same target (a double tap is
 tap. Wheel walks like a move with `deltaX/deltaY` (a node stopping it
 keeps the zoom out). Every event carries `native`, the leaf's element
 event, for core's recognizers, and the element fields (pointerId,
-pointerType, button, modifiers) plus `x`/`y` in scene pixels
+pointerType, button, modifiers, `timeStamp`, and `predicted`: a move to
+draw with, not to measure with - core's AGENTS.md has both) 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
@@ -1087,7 +1100,7 @@ natural 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.
-checks/dispatch-check.ts pins the walk, claiming, capture, hover, wheel
+tests/dispatch.test.ts pins the walk, claiming, capture, hover, wheel
 and tap rules headless; examples/pick.tsx is the live guard.
 
 ### Geometry generators
@@ -1333,7 +1346,10 @@ 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) and `uniform mat4 uNormal` (the world
+without knowing the projection), `uniform vec2 uViewport` (the target's
+pixel size, shared likewise and per target - each view feeds its own -
+so a pixel-space footprint like the splat material's needs no app
+write) 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
@@ -1491,7 +1507,8 @@ or in five figures, belong to the function face.
 #### createRecordMesh
 
 `createRecordMesh(geometry, material, records, count?, { bounds?,
-label? })` is the raw form: `records` is the per-instance data laid out
+instanceOrder?, 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
@@ -1523,6 +1540,63 @@ unhide, renderOrder/params/geometry/material swaps apply, and
 explicit free, geometry-buffer rule. `examples/fleet.tsx` (instances,
 components) and `examples/instanced.tsx` (records) are the live proofs.
 
+#### Instance order
+
+`instanceOrder` on either create (and the components) draws a
+population's records in key order, decided core-side; slots as you write
+them never move. `{ position: "iCenter", retain: true, descending: true
+}` names a float32x3/x4 attribute holding a local-space position: records
+draw by their depth along the scene camera's view direction, which the
+SCENE feeds the core whenever the camera or the mesh turns meaningfully
+(mapped through the mesh's rotation; an epsilon gate meters the
+re-sorts) - back-to-front transparency over 100k+ records with zero
+per-frame JS, and with `retain` a camera turn re-sorts and republishes
+core-side while a parked camera uploads nothing. `{ field: "age" }`
+names a float32 attribute and draws by its value, re-ordered when the
+records publish. The costs, by design: an ordered mesh publishes the
+LIVE record set whole on any write (a byte range has no stable position
+under a permutation; `count` defines the sorted population), and one
+buffer holds ONE order - the scene target's entry owns it, views and
+shadow passes draw the same gathered buffers, and a mesh layered out of
+the scene target keeps its last order. Where the key sits decides
+nothing else: raw instancing stays buffer-order everywhere (Three,
+Unity, Godot), so this knob has no engine counterpart to compare
+against; the core primitive is okf/done/gpu-instance-order.md.
+
+`transfer: true` (createRecordMesh only) is the write-once form for a
+large population: the records go to the ENGINE at creation and the mesh
+keeps no JS mirror, so the record bytes are resident once CPU-side
+(engine mirror) plus the GPU buffer, instead of twice more (JS mirror,
+plus the creation bytes the app would keep). The contract is loud:
+setRecords, updateRecords, instanceAttribute and growth throw naming
+the transfer; setRecordCount still works (with an instanceOrder the
+engine re-sorts and republishes the first n records of ITS copy),
+and so do setVisible, transforms, re-attach and disposeInstances (which
+frees the engine copy with the buffer). Takes a single-stream material;
+with an instanceOrder the engine's retained copy is implied. The engine
+mirror is BUFFER-lifetime, so a detached-and-re-attached ordered entry
+(setLayers re-admission included) seeds its order from it with no
+publish from JS - true for every retained ordered mesh since this
+landed, transfer or not.
+
+The INDEXED form, `instanceOrder: { position: "iCenter", records:
+LAYOUT, descending: true }` (createRecordMesh only), is for a population
+whose records live in a DATA TEXTURE the vertex stage fetches by record
+index - a splat cloud, any large write-once set whose per-instance
+frontend cost matters. `records` is the layout of the record bytes you
+pass (the key attribute lives there), and the material's ONE instance
+buffer is the id stream: uint32/uint32x4 attributes the engine fills
+with the sorted record indices, K ids per instance record, so one drawn
+instance covers K records - repeat the geometry K times and pick the
+record with `gl_VertexID` (quad `gl_VertexID / 4`), fetch it by id
+(`texelFetch` on an `rgba32ui` texture the app built from the same
+bytes and bound per mesh), and cull the id 0xFFFFFFFF that pads the
+last group. Transfer is implied (the records are the engine's sort
+key source), a re-sort uploads 4 bytes per record instead of the
+record, and `count` stays in records while the entry draws
+ceil(count / K) instances (`drawCount`). `MeshInstances.textures` holds
+data textures the population owns, freed by disposeInstances.
+
 ### Background
 
 Background: `scene.setBackground(source | null)`, the `background` option
@@ -1590,7 +1664,7 @@ 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 `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`
+BAKED one: `bun run srt tool 3d/environment sky.hdr -o assets/sky.srte`
 turns an equirectangular Radiance .hdr (Poly Haven's are CC0) into the
 six faces plus the GGX-prefiltered mip chain in linear float, and
 `await loadEnvironment("assets/sky.srte")` uploads it as an explicit
@@ -1614,8 +1688,27 @@ sky-lit reflections: ONE `uEnv` samplerCube bound on every target the
 scene draws into (a 1x1 black placeholder while unset) and one
 shared-params write (`uEnvIntensity`, `uEnvRotation`, `uEnvOn`), however
 many meshes reflect; no per-material envMap (Three's Basic/Phong
-`envMap`) - a custom material composes ENVIRONMENT from
-`@solidrt/3d/glsl`. `reflectivity` 0..1 is the
+`envMap` sits on the MATERIAL, but materials are shared here) - a
+custom material composes ENVIRONMENT from `@solidrt/3d/glsl`, and a
+single object's exception is PER MESH: `Mesh.environment`
+(`setEnvironment(mesh, env)`, the `environment` prop on every mesh
+component). `null` removes the environment term from that mesh - the
+sealed-interior pair to masked lights, since light `layers` cannot mask
+image lighting; Unity's reflectionProbeUsage Off, Godot's
+disable_ambient_light in spirit - an `{ cube, intensity?, rotation? }`
+samples that cube instead of the scene's (an interior probe's cube, a
+baked room - Unity assigns probes by volume with an anchor override,
+Godot by probe box and cull_mask; here the app assigns explicitly),
+and absent follows the scene. The same uEnv* names written per ENTRY,
+which beat the target's shared values, so it costs nothing per frame;
+the change rebuilds the mesh's entries, a state switch (a doorway
+crossing), not a per-frame dial. Applied where the material reflects at
+all (`standard`, `phong({ reflectivity })`, a custom ENVIRONMENT
+composer - `Material.env`); on any other material it is a no-op, so an
+interior can be masked wholesale. A reflection probe drawing such a
+mesh never samples its own cube through it (the black placeholder
+stands in, the same rule the scene's own environment follows on probe
+faces). `reflectivity` 0..1 is the
 face-on weight, rising to 1 at grazing angles (Schlick), mixed in as
 `rgb = mix(rgb, reflection, weight)`: 1 is chrome, ~0.05 a glossy
 dielectric with rim reflections; Three's Phong `reflectivity` under its
@@ -1915,7 +2008,7 @@ resolve - at one of three tiers, top first:
    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
+   cone-faded, layer-masked 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).
@@ -1939,7 +2032,7 @@ instance or every caster move warns about the skipped write.
 ### Lights
 
 Lights and `phong`: lights are graph NODES, like Three. `createDirectionalLight({
-direction?, color?, intensity? })` / `<DirectionalLight>` is parallel light
+direction?, color?, intensity?, layers? })` / `<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
@@ -1958,7 +2051,16 @@ decay? })` / `<PointLight>` is the omnidirectional version: position
 only, same falloff, no cone. `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
+scene, the last attached wins. EVERY light (the hemisphere included)
+takes `layers?: number`, a filter bitmask defaulting to all bits set:
+the light lights, and a casting light shadows, only the meshes whose
+`layers` intersect it (Unity's cullingMask, Godot's light_cull_mask;
+Three has none) - the sealed-interiors pattern's light half (see Views
+and layers), one integer AND per light per fragment on two uniforms,
+so the branch is coherent per draw. A mesh a casting light's mask
+excludes also draws into none of its shadow maps. The environment term
+is not a light and not masked: its per-mesh knob is `Mesh.environment`
+(see Environment). Placement goes through setTransform, the
 light's own fields through `setLight(light, { ... })` (frame-rate-safe,
 like setMeshParams). At most `MAX_LIGHTS` (8, exported from the root and `/glsl`)
 lights per scene, directional, spot and point together (the hemisphere
@@ -1971,13 +2073,21 @@ node's world rotation (direction, negated so the shader reads the
 vector TOWARD the light) and world position, 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), `uLightType[N]` (LIGHT_DIRECTIONAL | LIGHT_SPOT |
+`uHemiMask` (int, the hemisphere's layers), `uLightCount` (int),
+`uLightType[N]` (LIGHT_DIRECTIONAL | LIGHT_SPOT |
 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` +
+folded into the color), `uLightParams[N]` (cosInner, cosOuter,
+distance, decay) and `uLightMask[N]` (each light's layers; masks cross
+as SIGNED 32-bit ints, all bits = -1, the shader only ANDs the bits) -
+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; `phong`
 is the shape), and a light change costs one write however many meshes.
+The mesh side of the mask is `uniform int uLayers` (declared by
+LIGHT_LOOKUP, tested first in lightVector): a per-entry param the scene
+seeds from `mesh.layers` and follows through setLayers on every
+material whose source mentions it - never per frame, and never
+something a fragment declares itself.
 A custom fragment that declares only the old directional subset
 (`uLightCount`/`uLightDir`/`uLightColor`) still works - it just shades
 every light as directional, so keep such materials to directional-only
@@ -2117,7 +2227,9 @@ index into `images`, `doubleSided`, `transparent` = alphaMode BLEND,
 `alphaMode` as written and `alphaCutoff`, spec default 0.5, the
 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
+(each `{ bytes, name, uri? }`: the encoded PNG, JPEG or KTX2 file,
+undecoded; its name in the document, else the uri of its file, else
+"image<i>"; the `uri` when it is a file of its own) and `bounds` (world-space rest
 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
@@ -2165,7 +2277,8 @@ its true roots; a hierarchy reaching a node twice (a cycle) throws.
 #### createModel
 
 `createModel(data, { material?, label?, autoFree? })` - uploads the images (repeat
-wrap, mipmapped, 4x anisotropic), makes one material per glTF material (default `standard`
+wrap, mipmapped, 4x anisotropic; each texture is labeled `<label>-<image name>`, so the
+`/gpu` inventory names the image), 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
@@ -2213,14 +2326,118 @@ 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
+at build time, 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.
 
+#### Compressed textures
+
+`srt tool 3d/model <in> -o assets/<name>.srtm` bakes the images
+too: each becomes a KTX2 compressed texture with its mip chain. The file is the
+same for every platform; at load each device turns the images into the
+block format its GPU samples (BC7 on desktops, ETC2 elsewhere), which
+holds them in a quarter of the memory of the decoded image. Measured on
+the Khronos Sponza sample (69 images): 363 MB of textures as PNG/JPEG,
+91 MB compressed. The encode is slow (a minute for that
+model) and runs once, at bake time. Block compression is lossy: judge
+the result on your own textures. What it saves is GPU memory; the file
+shrinks for color maps and can grow for data maps.
+
+How the images are compressed, and whether, is the app's to say, in the
+`textures` group of the `solidrt` key in its package.json (the project
+the tool runs in, whose root is where the tool is run). These are the
+defaults; name only what differs:
+
+```json
+"solidrt": {
+  "textures": {
+    "compress": true,
+    "color": { "codec": "etc1s", "quality": 0.75 },
+    "normal": { "codec": "uastc", "quality": 0.9 },
+    "data": { "codec": "uastc", "quality": 0.9 },
+    "files": []
+  }
+}
+```
+
+Three levels, the narrower one winning: the app (`compress`), a kind
+of map (`compress`, `codec`, `quality`), and single files:
+
+```json
+"files": [
+  { "match": "assets/sponza/textures/lion_*.png", "codec": "uastc", "quality": 0.95 },
+  { "match": ["assets/ui/**", "assets/hero.glb#lut*"], "compress": false }
+]
+```
+
+- `match` is a glob pattern, or a list of them, against the image's
+  path FROM THE PROJECT ROOT, written with "/": `*` inside a segment,
+  `**` across segments, `?`, `[a-z]`, `[!a-z]` (`matchesGlob` of
+  flux:path; no `{a,b}`, list the patterns). Not the uri the glTF
+  writes: two models with a `textures/base.png` each are two files.
+- An image embedded in the model (a .glb) has no file of its own: the
+  model's path names every image in it, and `#name` after it picks
+  the ones of that name (the glTF image's `name`, "image<i>" without
+  one).
+- An entry sets `compress`, `codec`, `quality` or several, over what
+  the image's kind says. Where several entries name one image, a
+  later entry wins, field by field.
+- `"compress": false` keeps the image as its PNG or JPEG. That is for
+  what must come back exact (a lookup table, a distance field) and
+  for sharp art and text, which block compression damages.
+- A pattern that names nothing FAILS the bake, before anything is
+  encoded: no file of the project matches it, or the baked model has
+  no embedded image of that name. A misspelled pattern would
+  otherwise do nothing and say nothing.
+
+`--compress` and `--no-compress` stand in for the app's `compress` for
+one run (a quick bake while the model is still changing); what a kind
+or an entry says about itself still holds.
+
+The kinds are core's and say what the texels are (`@solidrt/core/textures`).
+This package maps a material's slots onto them: base color and emissive
+maps are `color`, normal maps are `normal`, metallic-roughness maps
+(occlusion rides in the same image) are `data`.
+An image several slots share takes the most demanding kind, normal over
+color over data, and stays sRGB when one of them is a color slot;
+`modelImageUses(data)` returns that per image, the rule the loader and
+the bake both follow, for a bake script of your own.
+`codec` and `quality` are `encodeTexture`'s: "etc1s" is small (a
+quarter of a JPEG), "uastc" is accurate and large (often larger than
+the JPEG it replaces), `quality` is 0..1. A normal map steers the
+lighting and shows its errors, and a metallic-roughness map packs
+unrelated values into its channels, which the small codec handles
+badly, so both take the accurate one (what the Khronos KTX guide
+recommends). Set `data` to "etc1s" when the download matters more than
+roughness detail: on the Khronos Sponza sample that is 9 MB less for
+about 2 dB in the views that glossy surfaces fill. An unknown key, codec or field fails the bake naming the key,
+before anything is encoded, and the bake prints how many images it
+compressed with which codec and quality, and how many it kept. The color space (sRGB for `color`), the mip chain and the
+wrap are not settings: they follow how `createModel` samples. The
+settings are the app's, not this package's: an app's own bake script,
+or another extension's, reads the same group with
+`textureSettings(packageJson)` from `@solidrt/core/textures` and asks
+`textureSettingFor(settings, kind, { file, name }, matchesGlob)` per
+texture (core's AGENTS.md has the rest).
+
+`loadModel` and `loadGltf` handle such a model as they are, and
+`loadGltf` reads a glTF that carries KTX2 images itself
+(`KHR_texture_basisu`). Only the primitives show the step: transcoding
+is asynchronous and `createModel` is not, so bytes obtained another way
+go through `transcodeModelImages` between the two:
+
+```ts
+let data = await transcodeModelImages(decodeModel(bytes))
+let model = createModel(data)
+```
+
+`createModel` on data whose KTX2 images were not transcoded throws and
+names the function. Data without KTX2 images needs no such step.
+
 #### Baking your own geometry
 
 Geometry an app GENERATES (a terrain, a city block, a hundred thousand
@@ -2479,9 +2696,82 @@ mesh (JS-written records, no nodes) cannot morph: rejected at add().
 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`.
+container is VERSION 11 (node table in the header, node-local vertices,
+skins, clips, packed morph targets, app data, images under their
+names); older bakes are rejected - re-bake with `srt tool 3d/model`.
+
+## Splats
+
+Captured 3D Gaussian splat scenes (phone scans, photogrammetry
+successors) as ordinary content, the model-loading split repeated:
+
+- `@solidrt/3d/splat` (src/splat-data.ts) is the runtime-free data side,
+  the model-data rule: `parseSplat(bytes, { format?, keepOrientation? })`
+  reads a trainer's `.ply`, the de-facto `.splat` interchange or a
+  GUNZIPPED `.spz` (Niantic, version 2 or 3; the entry stays
+  decompression-free, so inflate first) and bakes it - the 3D covariance
+  precomputed per splat (R S St Rt, the vertex-stage wall every
+  bake-less viewer pays at each corner), records importance-sorted (size
+  times opacity, so the first n are the scene at n), y-down captures
+  (.ply, .splat) stood up to y-up (positions and covariances rotated
+  together; `keepOrientation` opts out, `.spz` is y-up already), bounds
+  measured. `encodeSplat`/`decodeSplat` round-trip the `.srts` container
+  (the record and SH blocks, next bullet); decode is a header parse
+  plus byte VIEWS, nothing per-splat. `srt tool 3d/splat <in> [-o
+  out.srts] [--sh 0..3] [--keep-orientation]` is the parse and bake
+  under bun (tools/splat.ts); an app bake script uses the same entry.
+- The `.srts` record (version 2) is 32 bytes = two rgba32ui texels:
+  center float32x3 + sRGB color and opacity unorm8x4, then the
+  covariance upper triangle as six float16 + a spare word
+  (SPLAT_ATTRIBUTES as a byte layout, SPLAT_RECORD_TEXELS). `--sh 1..3`
+  bakes that many spherical-harmonic bands beyond the base color from a
+  trainer's `.ply` or an `.spz` (`.splat` has none), capped at the
+  capture's: a second texel block of 2/3/6 texels per splat
+  (SPLAT_SH_TEXELS; the halves packed pairwise, coefficient-major with
+  rgb interleaved), 32/48/96 bytes per splat of texture, so the
+  default is 0 and a bake opts in. The y-up flip negates the
+  coefficients whose basis is odd in (y, z).
+- On the runtime, `loadSplat(path)` reads a `.srts` (fetch + decode,
+  the loadModel shape) and `createSplatMesh(data, { count?, material?,
+  label? })` / `<SplatMesh>` shows it: a RecordMesh in the INDEXED form
+  (see "Instance order") - the records handed to the engine as the
+  depth sort's key source AND uploaded once as the `rgba32ui` record
+  texture the vertex stage fetches by id (`uSplatRecords`, plus
+  `uSplatSh` when baked; bound per mesh, so a forked material keeps
+  them), SPLAT_GROUP (16) splats per drawn instance of a merged-quad
+  geometry, the header bounds as the cull and picking box, and the
+  id stream sorted back to front core-side - the cloud composes as a
+  mesh (depth-tested against opaque geometry, placed by the transparent
+  entry sort, transformed by its node), a camera turn re-sorts and
+  republishes 4 bytes per splat with zero per-frame JS, and a parked
+  camera uploads nothing. Write-once: treat the SplatData as consumed
+  and drop it; at 1M splats the cloud is resident as the engine's 32 MB
+  key copy plus 32 MB of texture plus a 4 MB id buffer, and
+  disposeInstances frees all three. `splatMaterialClass(shDegree)` is
+  the stock class per degree (a shared instance each), and
+  `splatVertexSource(shDegree)` / SPLAT_FRAGMENT / SPLAT_ID_ATTRIBUTES
+  are exported for forks; `count` rounds up to whole groups.
+- The vertex stage projects the baked covariance through the Jacobian
+  of `uViewProj * uModel` (no focal/view uniforms; any node transform
+  shapes the footprint with the same matrix that moves the center),
+  reads the target size from the standard `uViewport`, and evaluates
+  the SH bands per corner from the view direction (`uCamPos` through
+  the transposed model rotation - exact under rotation and uniform
+  scale). The data textures' row width is the device's (up to 4096),
+  compiled into the source.
+- Why this shape: on the Pixel 7 at 1M splats the one-quad-per-instance
+  form spent two thirds of its vertex side on the instancing frontend;
+  the indexed form takes the full-res frame from 45 to 31 ms and the
+  vertex side from 24 to 8 ms, the per-vertex fetch and random id order
+  cost under a millisecond, and SH1-3 are near free (the bands cost
+  memory, not time). What remains at 1M is fill (overdraw). The table
+  is in okf/done/gaussian-splats.md.
+- Two capture caveats worth knowing at the app level: captures are
+  TRAINED against sRGB blending, so show them in a display-space scene
+  (`blendSpace: "display"`) - a linear scene lays a milky veil over
+  stacked translucents - and a capture is only clean near the camera
+  path it was taken from (elsewhere it is floaters), so keep the camera
+  near that path.
 
 ## Traps
 

package/examples/README.md

@@ -1,6 +1,6 @@
 # @solidrt/3d examples
 
-One concept per file; run with `bunx srt run <file>` from an app that
+One concept per file; run with `bun run srt run <file>` from an app that
 depends on `@solidrt/3d` (or in-repo from the package directory).
 
 - `scene-basic.tsx` - the whole v1 surface: a `<Scene>` composited as a
@@ -58,7 +58,7 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   sky as a faint face-on gloss. Drag to look around.
 - `environment.tsx` - a baked HDR environment lighting the scene ALONE
   (no lights, no hemisphere): `loadEnvironment` reads the .srte that
-  `bunx srt tool 3d/environment <panorama>.hdr -o assets/environment.srte`
+  `bun run srt tool 3d/environment <panorama>.hdr -o assets/environment.srte`
   bakes from any equirectangular .hdr (Poly Haven's are CC0; the asset
   is not committed, bake one first), used as background and environment
   with ACES tone mapping. A metal row and a red dielectric row, roughness
@@ -200,4 +200,4 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   stays above the boundary - the two rules that avoid
   PENDING_ASYNC_UNTRACKED_READ and the suspend-retry element leak. Needs
   the asset baked into the running app:
-  `bunx srt tool 3d/model examples/model.glb -o assets/model.srtm`.
+  `bun run srt tool 3d/model examples/model.glb -o assets/model.srtm`.