@solidrt/3d 0.0.62 → 0.0.64

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,12 +545,15 @@ 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.
+`src/splat-data.ts` is its own published entry the same way
+(`@solidrt/3d/splat`, guarded by `tests/splat-data.test.ts`).
 The rigs under `checks/`
 (`geometry-check`, `sweep-check`, `pick-check`, `dispatch-check`,
 `gltf-check`) run on
@@ -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)` |
@@ -1333,7 +1344,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 +1505,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 +1538,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
@@ -1614,8 +1686,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 +2006,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 +2030,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 +2049,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 +2071,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
@@ -2483,6 +2591,79 @@ 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`.
 
+## 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
 
 ### Models and skinning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.62",
+  "version": "0.0.64",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -9,6 +9,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./model": "./src/model-data.ts",
+    "./splat": "./src/splat-data.ts",
     "./math": "./src/math.ts",
     "./glsl": "./src/glsl.ts"
   },
@@ -20,6 +21,6 @@
   ],
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.9",
-    "@solidrt/core": "0.0.62"
+    "@solidrt/core": "0.0.64"
   }
 }

package/src/camera.ts

@@ -135,8 +135,11 @@ export function ensureCamera(cam: Camera, width: number, height: number): void {
 // billboard needs no reconstruction from uViewProj. The inverse rides too:
 // uInvViewProj carries a clip position back to world, which is how the
 // background slot (and any shader declaring it) gets a world-space ray
-// per pixel without knowing the projection.
-export function cameraParams(cam: Camera): ShaderParams {
+// per pixel without knowing the projection. The target's pixel size rides
+// as uViewport (the size the camera's aspect came from), so a pixel-space
+// footprint (the splat material) needs no app write and is per target -
+// each view feeds its own.
+export function cameraParams(cam: Camera, width: number, height: number): ShaderParams {
   let v = cam.view
   return {
     uViewProj: cam.viewProj,
@@ -144,5 +147,6 @@ export function cameraParams(cam: Camera): ShaderParams {
     uCamPos: cam.eye,
     uCamRight: [v[0], v[4], v[8]],
     uCamUp: [v[1], v[5], v[9]],
+    uViewport: [width, height],
   }
 }

package/src/components/directional-light.tsx

@@ -13,6 +13,9 @@ export type DirectionalLightProps = TransformProps & {
   direction?: Vec3
   color?: Vec3
   intensity?: number
+  /** Layer filter bitmask, default all bits set: the light lights and
+   * shadows only the meshes whose `layers` intersect it. */
+  layers?: number
   /** Render a shadow map from this light (any directional light may;
    * each is a pass). Its shadow camera sits at the light's WORLD
    * position, so give a casting light a `position` above the scene. */
@@ -32,6 +35,7 @@ export let DirectionalLight: VoidComponent<DirectionalLightProps> = props => {
       direction: props.direction,
       color: props.color,
       intensity: props.intensity,
+      layers: props.layers,
       castShadow: props.castShadow,
       shadow: props.shadow,
     }),
@@ -39,8 +43,8 @@ export let DirectionalLight: VoidComponent<DirectionalLightProps> = props => {
   add(ctx.parent, light)
   syncNode(light, props)
   createEffect(
-    () => [props.direction, props.color, props.intensity, props.castShadow, props.shadow] as const,
-    ([direction, color, intensity, castShadow, shadow]) => setLight(light, { direction, color, intensity, castShadow, shadow }),
+    () => [props.direction, props.color, props.intensity, props.layers, props.castShadow, props.shadow] as const,
+    ([direction, color, intensity, layers, castShadow, shadow]) => setLight(light, { direction, color, intensity, layers, castShadow, shadow }),
   )
   untrack(() => props.ref)?.(light)
   onCleanup(() => destroy(light))

package/src/components/hemisphere-light.tsx

@@ -6,17 +6,25 @@ import { createHemisphereLight, setLight } from "../light.ts"
 import type { HemisphereLight as HemisphereLightNode } from "../light.ts"
 import type { Vec3 } from "../math.ts"
 
-export type HemisphereLightProps = { sky?: Vec3; ground?: Vec3; intensity?: number; ref?: (light: HemisphereLightNode) => void }
+export type HemisphereLightProps = {
+  sky?: Vec3
+  ground?: Vec3
+  intensity?: number
+  /** Layer filter bitmask, default all bits set: a mesh outside it gets
+   * no hemisphere term. */
+  layers?: number
+  ref?: (light: HemisphereLightNode) => void
+}
 
 /** The scene's ambient term as a node (createHemisphereLight); one per
  * scene, the last mounted wins. */
 export let HemisphereLight: VoidComponent<HemisphereLightProps> = props => {
   let ctx = useContext(SceneContext)
-  let light = untrack(() => createHemisphereLight({ sky: props.sky, ground: props.ground, intensity: props.intensity }))
+  let light = untrack(() => createHemisphereLight({ sky: props.sky, ground: props.ground, intensity: props.intensity, layers: props.layers }))
   add(ctx.parent, light)
   createEffect(
-    () => [props.sky, props.ground, props.intensity] as const,
-    ([sky, ground, intensity]) => setLight(light, { sky, ground, intensity }),
+    () => [props.sky, props.ground, props.intensity, props.layers] as const,
+    ([sky, ground, intensity, layers]) => setLight(light, { sky, ground, intensity, layers }),
   )
   untrack(() => props.ref)?.(light)
   onCleanup(() => destroy(light))

package/src/components/index.ts

@@ -33,6 +33,8 @@ export { InstancedLod, Lod } from "./lod.tsx"
 export type { InstancedLodProps, LodProps } from "./lod.tsx"
 export { RecordMesh } from "./record-mesh.tsx"
 export type { RecordMeshProps } from "./record-mesh.tsx"
+export { SplatMesh } from "./splat-mesh.tsx"
+export type { SplatMeshProps } from "./splat-mesh.tsx"
 export { PerspectiveCamera } from "./perspective-camera.tsx"
 export type { PerspectiveCameraProps } from "./perspective-camera.tsx"
 export { OrbitCamera } from "./orbit-camera.tsx"

package/src/components/instanced-mesh.tsx

@@ -8,7 +8,7 @@ import type { PopulatedMeshProps } from "./mesh.tsx"
 import { add, destroy, setMorphWeights } from "../node.ts"
 import type { MorphWeights, SceneNode } from "../node.ts"
 import { addInstance, createInstancedMesh, disposeInstances, setCastShadow, setGeometry, setInstanceStyle } from "../mesh.ts"
-import type { InstancedMesh as InstancedMeshNode, InstanceNode } from "../mesh.ts"
+import type { InstancedMesh as InstancedMeshNode, InstanceNode, InstanceOrderOptions } from "../mesh.ts"
 import type { Geometry } from "../geometry.ts"
 import type { Material } from "../material.ts"
 
@@ -30,6 +30,10 @@ export type InstancedMeshProps = Omit<PopulatedMeshProps, "onPointerEnter" | "on
    * transparent sort. Optional here - instances pick by themselves, and
    * without it the mesh culls by the union of their boxes. */
   bounds?: ArrayLike<number>
+  /** Draw the records in key order, decided core-side (fixed at
+   * creation; see InstanceOrderOptions): back-to-front for a transparent
+   * population, an explicit sort field for a stepped one. */
+  instanceOrder?: InstanceOrderOptions
   /** Debug label for the record buffers. */
   label?: string
   /** The node the instance records are relative to (default the mesh;
@@ -63,7 +67,7 @@ export let InstancedMeshContext = createContext<InstancedMeshNode | null>(null)
 export let InstancedMesh: ParentComponent<InstancedMeshProps> = props => {
   let ctx = useContext(SceneContext)
   let mesh = untrack(() =>
-    createInstancedMesh(props.geometry, props.material, { capacity: props.capacity, bounds: props.bounds, anchor: props.anchor, label: props.label }),
+    createInstancedMesh(props.geometry, props.material, { capacity: props.capacity, bounds: props.bounds, anchor: props.anchor, instanceOrder: props.instanceOrder, label: props.label }),
   )
   add(ctx.parent, mesh)
   createEffect(

package/src/components/mesh.tsx

@@ -5,8 +5,9 @@ import { syncNode } from "./node-props.ts"
 import type { TransformProps, PointerEventProps } from "./node-props.ts"
 import { add, destroy, setMorphWeights } from "../node.ts"
 import type { MorphWeights } from "../node.ts"
-import { createMesh, setCastShadow, setCulling, setGeometry, setLayers, setMaterial, setMeshParams, setRenderOrder } from "../mesh.ts"
+import { createMesh, setCastShadow, setCulling, setEnvironment, setGeometry, setLayers, setMaterial, setMeshParams, setRenderOrder } from "../mesh.ts"
 import type { Mesh as MeshNode } from "../mesh.ts"
+import type { EnvironmentOptions } from "../environment.ts"
 import type { ShaderParams } from "@solidrt/core/gpu"
 import type { Geometry } from "../geometry.ts"
 import type { Material } from "../material.ts"
@@ -29,6 +30,12 @@ export type MeshProps = TransformProps & PointerEventProps & {
    * draws the mesh when its mask intersects this. Not inherited from
    * ancestor Groups. */
   layers?: number
+  /** This mesh's environment instead of the scene's (setEnvironment as a
+   * prop): `null` removes the environment term - the sealed-interior
+   * pair to masked lights - a `{ cube, intensity?, rotation? }` samples
+   * that cube, absent follows the scene. Rebuilds the mesh's entries on
+   * change: a state switch, not a per-frame dial. */
+  environment?: EnvironmentOptions | null
   /** Frustum culling switch (setCulling as a prop; default true). */
   frustumCulled?: boolean
   /** World units the culled box grows by (setCulling as a prop; default 0). */
@@ -71,6 +78,10 @@ export function syncMesh(mesh: MeshNode, props: Omit<MeshProps, "geometry" | "ma
     () => props.layers,
     l => setLayers(mesh, l ?? 1),
   )
+  createEffect(
+    () => props.environment,
+    e => setEnvironment(mesh, e),
+  )
   createEffect(
     () => [props.frustumCulled, props.cullMargin] as const,
     ([culled, margin]) => setCulling(mesh, { frustumCulled: culled !== false, cullMargin: margin ?? 0 }),

package/src/components/point-light.tsx

@@ -11,6 +11,9 @@ import type { Vec3 } from "../math.ts"
 export type PointLightProps = TransformProps & {
   color?: Vec3
   intensity?: number
+  /** Layer filter bitmask, default all bits set: the light lights and
+   * shadows only the meshes whose `layers` intersect it. */
+  layers?: number
   /** Falloff cutoff in world units (0 = no cutoff). */
   distance?: number
   /** Falloff exponent; default 2 (inverse square). */
@@ -34,6 +37,7 @@ export let PointLight: VoidComponent<PointLightProps> = props => {
     createPointLight({
       color: props.color,
       intensity: props.intensity,
+      layers: props.layers,
       distance: props.distance,
       decay: props.decay,
       castShadow: props.castShadow,
@@ -43,8 +47,8 @@ export let PointLight: VoidComponent<PointLightProps> = props => {
   add(ctx.parent, light)
   syncNode(light, props)
   createEffect(
-    () => [props.color, props.intensity, props.distance, props.decay, props.castShadow, props.shadow] as const,
-    ([color, intensity, distance, decay, castShadow, shadow]) => setLight(light, { color, intensity, distance, decay, castShadow, shadow }),
+    () => [props.color, props.intensity, props.layers, props.distance, props.decay, props.castShadow, props.shadow] as const,
+    ([color, intensity, layers, distance, decay, castShadow, shadow]) => setLight(light, { color, intensity, layers, distance, decay, castShadow, shadow }),
   )
   untrack(() => props.ref)?.(light)
   onCleanup(() => destroy(light))

package/src/components/record-mesh.tsx

@@ -5,7 +5,7 @@ import { syncMesh } from "./mesh.tsx"
 import type { PopulatedMeshProps } from "./mesh.tsx"
 import { add, destroy } from "../node.ts"
 import { createRecordMesh, disposeInstances, setCastShadow, setGeometry, setRecordCount, setRecords } from "../mesh.ts"
-import type { RecordMesh as RecordMeshNode } from "../mesh.ts"
+import type { InstanceOrderOptions, RecordMesh as RecordMeshNode } from "../mesh.ts"
 import type { Geometry } from "../geometry.ts"
 import type { Material } from "../material.ts"
 
@@ -25,6 +25,14 @@ export type RecordMeshProps = PopulatedMeshProps & {
    * creation. Without them the mesh has no picking leaf, so pointer events
    * never target it. */
   bounds?: ArrayLike<number>
+  /** Draw the records in key order, decided core-side (fixed at
+   * creation; see InstanceOrderOptions): back-to-front for a transparent
+   * population, an explicit sort field for a JS-stepped one. */
+  instanceOrder?: InstanceOrderOptions
+  /** Transfer the records to the engine at creation (fixed; see
+   * RecordMeshOptions.transfer): the write-once form - no JS mirror, so
+   * a later `records` value throws instead of rewriting. */
+  transfer?: boolean
   /** Draw into the scene's shadow map (setCastShadow as a prop); default
    * false. Needs a `castShadow` light AND a material class declaring
    * `shadowVertex` (the depth pass with the instance placement) - the
@@ -39,7 +47,11 @@ export type RecordMeshProps = PopulatedMeshProps & {
 export let RecordMesh: VoidComponent<RecordMeshProps> = props => {
   let ctx = useContext(SceneContext)
   let mesh = untrack(() =>
-    createRecordMesh(props.geometry, props.material, props.records, props.count, { bounds: props.bounds }),
+    createRecordMesh(props.geometry, props.material, props.records, props.count, {
+      bounds: props.bounds,
+      instanceOrder: props.instanceOrder,
+      transfer: props.transfer,
+    }),
   )
   add(ctx.parent, mesh)
   createEffect(

package/src/components/scene.tsx

@@ -3,7 +3,7 @@ import type { Element, ParentComponent, PointerFeed, TextureId } from "@solidrt/
 import { SceneContext } from "./context.tsx"
 import { createScene } from "../scene.ts"
 import { feedPointer } from "../scene-pointer.ts"
-import type { BloomOptions, EnvironmentOptions, FogOptions, ResolveInput, Scene as SceneHandle, SkyboxOptions, ToneMapping } from "../scene.ts"
+import type { BlendSpace, BloomOptions, EnvironmentOptions, FogOptions, ResolveInput, Scene as SceneHandle, SkyboxOptions, ToneMapping } from "../scene.ts"
 import type { ScenePointerEvent, SceneTapEvent, SceneWheelEvent } from "../node.ts"
 import type { CameraUpdate } from "../camera.ts"
 
@@ -75,6 +75,12 @@ export type SceneProps = ScenePointerProps & {
   toneMapping?: ToneMapping
   /** Output exposure (scene.setExposure), default 1. Reactive. */
   exposure?: number
+  /** The buffer's blend space (SceneOptions.blendSpace), default
+   * "linear"; fixed at creation. "display" blends sRGB-encoded values
+   * in an rgba8 buffer that is itself the displayed image - the mode a
+   * splat capture is faithful in - and rejects resolve, bloom,
+   * toneMapping and exposure. */
+  blendSpace?: BlendSpace
   /** The scene target's layer mask (scene.setLayers as a prop; default 1):
    * the scene draws the meshes whose `layers` intersect it. Reactive. */
   layers?: number
@@ -175,6 +181,7 @@ export let Scene: ParentComponent<SceneProps> = props => {
       fog: props.fog,
       toneMapping: props.toneMapping,
       exposure: props.exposure,
+      blendSpace: props.blendSpace,
       resolve: props.resolve,
       bloom: props.bloom,
       layers: props.layers,