@solidrt/3d 0.0.55 → 0.0.56

package/src/scene.ts

@@ -27,322 +27,162 @@
 // broadphase and its leaves, the transparent sort's centers and the light
 // params. They read world matrices back from the core, and only for the
 // subtrees that moved since they last looked.
-
-import { addDraw, createBuffer, createDrawTarget, createTexture, depthTexture, destroyBuffer, destroyProgram, destroyRenderPipeline, destroyTexture, limits, removeDraw, setDrawBuffers, setDrawOrder, setDrawParams, setTargetParams, setTargetRect, setTargetSize, setTargetTextures, writeBuffer } from "@solidrt/core/gpu"
+//
+// This file is the scene half: createScene and everything one scene
+// instance owns (targets, views, sync, picking). The node layer it
+// renders - the graph, transforms, meshes, lights - lives in node.ts,
+// mesh.ts and light.ts, talking back through the SceneHooks seam
+// (node.ts); the camera record is camera.ts, and the per-scene shadow
+// and pointer subsystems are scene-shadows.ts / scene-pointer.ts,
+// built here with the scene's seams as their deps.
+
+import { addDraw, createCubeDrawTarget, createDrawTarget, depthTexture, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, renderTarget, setDrawBuffers, setDrawOrder, setDrawParams, setDrawTextures, setTargetParams, setTargetRect, setTargetSize, setTargetTextures } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
-import type { NodeId, NodeTransition } from "flux:spatial"
-import { on } from "srt:events"
-import type { BufferId, DrawId, FilterMode, ProgramId, RenderPipelineId, ShaderParams, TextureId, VertexAttribute, WrapMode } from "@solidrt/core/gpu"
+import type { NodeId } from "flux:spatial"
+import type { DrawId, FilterMode, ProgramId, RenderPipelineId, ShaderParams, TextureId, WrapMode } from "@solidrt/core/gpu"
 import { getOwner, onCleanup } from "@solidrt/core"
 import type { PointerEvent as ElementPointerEvent } from "@solidrt/core"
-// The scene's lookAt() aims a node; math's builds a camera's view matrix -
-// the same pairing (and the same name) as Three's Object3D/Matrix4.
-import { cascadeSplit, compose, copy, eulerFromQuat, frustumSliceSphere, identity, lookAt as lookAtMatrix, mat4, multiply, orthographic, perspective, quat, quatFromFrame, snapToGrid, transformPoint, transformVector, updateRotation, updateScale } from "./math.ts"
-import type { Mat4, Quat, TransformUpdate, Vec3, Vec4 } from "./math.ts"
-import { MAX_CASCADES, MAX_LIGHTS, MAX_SHADOW_MAPS } from "./glsl.ts"
-import { geometryBounds, layoutKey, plane, validateGeometry } from "./geometry.ts"
-import { acquireGeometryBuffers, releaseGeometryBuffers } from "./geometry-gpu.ts"
-import type { GeometryBuffers } from "./geometry-gpu.ts"
+import { copy, mat4, transformPoint } from "./math.ts"
+import { linearColor } from "./color.ts"
+import type { Mat4, Quat, Vec3, Vec4 } from "./math.ts"
+import { MAX_LIGHTS, MAX_SHADOW_MAPS } from "./glsl.ts"
+import { cameraParams, cameraState, ensureCamera, makeCamera, updateCamera } from "./camera.ts"
+import type { Camera, CameraState, CameraUpdate } from "./camera.ts"
+import { makeShadowSystem } from "./scene-shadows.ts"
+import { makePointerInput } from "./scene-pointer.ts"
+import { geometryBounds, layoutKey, validateGeometry } from "./geometry.ts"
 import type { Geometry } from "./geometry.ts"
-import { backgroundPipeline, missingAttributes, shadowDepthMaterial } from "./material.ts"
-import { orderEntries } from "./order.ts"
+import { acquireGeometryBuffers, releaseGeometryBuffers } from "./geometry-gpu.ts"
+import { backgroundPipeline, missingAttributes, SKYBOX_FRAGMENT } from "./material.ts"
+import { createEnvironmentPlaceholder, createPrefilter, probeFormat } from "./environment.ts"
+import type { Prefilter } from "./environment.ts"
 import type { Material } from "./material.ts"
+import { orderEntries } from "./order.ts"
+import { fillTransform, leaveScene, makeNode, worldInto } from "./node.ts"
+import type { SceneHooks, SceneNode, ScenePointerEvent } from "./node.ts"
+import { checkInstancePairing, checkMask, instanceBinding, localBounds, publishInstanceStyle } from "./mesh.ts"
+import type { InstancedMesh, InstanceNode, Mesh } from "./mesh.ts"
+import type { CastingLight, Light } from "./light.ts"
 
 const IDENTITY = mat4()
 const RESOLVED = Promise.resolve()
-// How a cascaded light slices the camera range: 0 uniform, 1
-// logarithmic, halfway the "practical" split (near slices small, far
-// ones not starved).
-const CASCADE_SPLIT_LAMBDA = 0.5
-// |y| of a light direction above this is straight up or down, where
-// world up cannot serve as the shadow map's roll reference.
-const VERTICAL_LIGHT = 0.99
-// lookAt()'s default roll reference. Read-only: quatFromFrame never
-// writes its inputs, so one shared vector is safe.
-const WORLD_UP: Vec3 = [0, 1, 0]
-// The FFI carriers: one transform write (position, quaternion, scale) and
-// one world-matrix read. Values are copied at the boundary, so one of each
-// serves every call.
-let transformScratch = new Float32Array(10)
-let worldRead = new Float32Array(16)
-// lookAt()/worldPosition() scratch: nothing here outlives a single call.
-let worldScratch = mat4()
-let localScratch = mat4()
+
+// raycast()'s FFI carriers; values are copied at the boundary, so one of
+// each serves every call.
 let rayOriginScratch = new Float32Array(3)
 let rayDirScratch = new Float32Array(3)
-let pointScratch: Vec4 = [0, 0, 0, 0]
-
-// Settle routing: the core's "spatialTransitionEnd" event carries the node
-// id, so nodes with a transition DECLARED (only those can settle) are
-// indexed by their core id while in a scene, and one lazy subscription,
-// started at the first declaration, routes to the node's onTransitionEnd.
-// Target-only, like the element transitions.
-let declared = new Map<NodeId, SceneNode>()
-let subscribed = false
-
-function declareTransition(id: NodeId, node: SceneNode): void {
-  declared.set(id, node)
-  if (subscribed) return
-  subscribed = true
-  on("spatialTransitionEnd", (event: { node: NodeId; component: TransitionEndEvent["component"] }) => {
-    let node = declared.get(event.node)
-    if (!node) return
-    try {
-      node.onTransitionEnd?.({ component: event.component })
-    } catch (err) {
-      console.error("Error in onTransitionEnd handler:", err)
-    }
-  })
+// overlap()/sweep()'s carriers: the volume in flux:spatial's packed
+// layout, one array per kind (capsule: a, b, radius; box: center, half
+// extents, rotation), and the sweep's motion.
+let capsuleScratch = new Float32Array(7)
+let boxScratch = new Float32Array(10)
+let motionScratch = new Float32Array(3)
+const IDENTITY_QUAT: Quat = [0, 0, 0, 1]
+
+/** Pack a volume into its kind's scratch array and name the kind; a
+ * sphere is a capsule whose segment is one point. */
+function packVolume(volume: Volume, site: string): "capsule" | "box" {
+  if ("halfExtents" in volume) {
+    let s = boxScratch
+    let h = volume.halfExtents
+    if (!(h[0] >= 0 && h[1] >= 0 && h[2] >= 0)) throw new Error(site + ": halfExtents must be >= 0, got " + h)
+    let q = volume.rotation ?? IDENTITY_QUAT
+    s[0] = volume.center[0]
+    s[1] = volume.center[1]
+    s[2] = volume.center[2]
+    s[3] = h[0]
+    s[4] = h[1]
+    s[5] = h[2]
+    s[6] = q[0]
+    s[7] = q[1]
+    s[8] = q[2]
+    s[9] = q[3]
+    return "box"
+  }
+  if (!(volume.radius >= 0)) throw new Error(site + ": radius must be >= 0, got " + volume.radius)
+  let s = capsuleScratch
+  let a = "center" in volume ? volume.center : volume.a
+  let b = "center" in volume ? volume.center : volume.b
+  s[0] = a[0]
+  s[1] = a[1]
+  s[2] = a[2]
+  s[3] = b[0]
+  s[4] = b[1]
+  s[5] = b[2]
+  s[6] = volume.radius
+  return "capsule"
 }
-let aimScratch: Vec3 = [0, 0, 0]
-let upScratch: Vec3 = [0, 0, 0]
+
 // pick()'s camera-ray scratch.
 let pickDir: Vec3 = [0, 0, 0]
-// setTransform's rotation compare happens AFTER conversion, so an euler and
-// the quaternion it produces are the same write. Nothing outlives the call.
-let rotScratch = quat()
-let scaleScratch: Vec3 = [1, 1, 1]
-
-// The scene half a node needs to reach: attach/detach entries and schedule
-// a sync. Kept separate from the public Scene type so internals stay off
-// the app-facing surface. The camera (uViewProj + uCamPos) is written
-// through the shared channel only when it changes - attach never re-seeds
-// it, because target state survives entry churn.
-type SceneHooks = {
-  _schedule(): void
-  _attach(mesh: Mesh): void
-  _detach(mesh: Mesh): void
-  _attachLight(light: Light): void
-  _detachLight(light: Light): void
-  _lightChanged(): void
-  _setParams(mesh: Mesh, params: ShaderParams): void
-  _setCount(mesh: Mesh): void
-  /** Re-point the mesh's entry at its (replaced) instance buffer. */
-  _setBuffer(mesh: Mesh): void
-  /** The mesh's castShadow flag changed: re-evaluate the filtered views. */
-  _setCast(mesh: Mesh): void
-  /** A light's castShadow/shadow options changed. */
-  _shadowChanged(light: DirectionalLight): void
-  _reorder(): void
-  /** The node's transform changed (for the sort and light bookkeeping). */
-  _moved(node: SceneNode): void
-}
-
-export type SceneNode = {
-  kind: "group" | "mesh" | "light"
-  parent: SceneNode | null
-  children: SceneNode[]
-  /** Read freely; write through setTransform/setVisible so changes sync. */
-  position: Vec3
-  /** The stored rotation, always a UNIT quaternion. Euler triples convert
-   * on the way in (setTransform's `rotation`) and out (getRotation) - there
-   * is no second rotation field to fall out of step with this one. */
-  quaternion: Quat
-  scale: Vec3
-  visible: boolean
-  /** Pointer event handlers - plain fields, assign freely (they touch no
-   * GPU state, so they need no setTransform-style write path; components
-   * sync their props here). Down/move/up dispatch on the hit mesh and
-   * bubble through its ancestors (stopPropagation stops the walk);
-   * enter/leave fire on the mesh alone. Events flow once the element
-   * showing the scene carries `scene.handlers`. */
-  onPointerDown?: (event: ScenePointerEvent) => void
-  onPointerMove?: (event: ScenePointerEvent) => void
-  onPointerUp?: (event: ScenePointerEvent) => void
-  onPointerEnter?: (event: ScenePointerEvent) => void
-  onPointerLeave?: (event: ScenePointerEvent) => void
-  /** A declared transition (setTransition) settled naturally on one
-   * component; a cancel, snap or scene leave never fires. */
-  onTransitionEnd?: (event: TransitionEndEvent) => void
-  /** The core node while in a scene (created at add, freed at remove). */
-  _node: NodeId | null
-  _moved: boolean
-  _scene: SceneHooks | null
-  /** The declared transition, re-applied on every scene enter. */
-  _transition: NodeTransition | string | null
-}
-
-/** The orthographic frustum a casting light renders its shadow map from,
- * in the light's own space (x right, y up, looking along its direction),
- * Three's DirectionalLightShadow camera. Everything outside it is lit. */
-export type ShadowCamera = { left: number; right: number; top: number; bottom: number; near: number; far: number }
-
-export type ShadowOptions = {
-  /** Shadow map resolution in texels, square (default 1024). */
-  mapSize?: number
-  /** Depth bias against acne, in the map's 0..1 depth (default 0). */
-  bias?: number
-  /** Offset a receiving point along its normal before the lookup, in
-   * world units (default 0) - the acne fix that keeps contact shadows. */
-  normalBias?: number
-  /** The light frustum; absent keys keep the defaults +-5, 0.5..500.
-   * Ignored by a cascaded light (its frustums follow the scene camera). */
-  camera?: Partial<ShadowCamera>
-  /** Split the shadow into this many cascades (1..MAX_CASCADES, default
-   * 1 = the `camera` box). With more, the light renders one map per slice
-   * of the SCENE camera's frustum (near .. far, tightest first), each
-   * `mapSize` texels wide and fitted every time the camera or the light
-   * moves, and a receiver samples the tightest one that has the point:
-   * sharp contact shadows near the camera and coarser ones toward the
-   * horizon, for a scene the box cannot cover at one map's resolution.
-   * Views (`scene.createView`) sample the same maps, fitted to the scene
-   * camera, not their own. Each cascade is a tile of the atlas. */
-  cascades?: number
-  /** How far from the scene camera a cascaded light shadows, in world
-   * units (default null = the camera's far). The cascades span
-   * near..distance and a point past it is lit, so pulling it in sharpens
-   * every cascade; it also bounds the maps' depth range, which is what
-   * `bias` is measured against. A box light ignores it. */
-  distance?: number | null
-}
-
-/** A directional light node: parallel rays travelling along `direction`
- * in the node's LOCAL space, so a parent's rotation turns the light with
- * it (the default `[0, -1, 0]` is a sun straight overhead; the length is
- * ignored). Scale does not affect it, and neither does position UNLESS
- * it casts: a casting light's shadow camera sits at its WORLD position
- * looking along its world direction (Three's rule), so place a casting
- * sun above the scene. Write through setLight. */
-export type DirectionalLight = SceneNode & {
-  kind: "light"
-  type: "directional"
-  direction: Vec3
-  /** Linear [r, g, b] 0..1. */
-  color: Vec3
-  intensity: number
-  /** Render a shadow map from this light (any directional light may;
-   * each map is a full extra pass over the casting meshes); meshes with
-   * `castShadow` draw into it, `lit` materials read it (unless
-   * `receiveShadow: false`). */
-  castShadow: boolean
-  /** The resolved shadow options (read; write through setLight). */
-  shadow: { mapSize: number; bias: number; normalBias: number; camera: ShadowCamera; cascades: number; distance: number | null }
-}
-
-/** The ambient term: a sky/ground gradient by the WORLD normal's
- * vertical tilt (fixed to world up, not the node's). One per scene - the
- * last attached wins. Write through setLight. */
-export type HemisphereLight = SceneNode & {
-  kind: "light"
-  type: "hemisphere"
-  sky: Vec3
-  ground: Vec3
-  intensity: number
-}
-
-export type Light = DirectionalLight | HemisphereLight
-
-export type Mesh = SceneNode & {
-  kind: "mesh"
-  geometry: Geometry
-  material: Material
-  /** Explicit draw-order key (default 0), Three's name: lower draws first.
-   * Sorts within the opaque group and within the transparent group; the
-   * transparent group always follows the opaque one. Set with setRenderOrder. */
-  renderOrder: number
-  /** Draw into the scene's shadow map (default false, Three's default).
-   * Set with setCastShadow. A casting instanced mesh is skipped (the
-   * depth pass cannot know its record layout). */
-  castShadow: boolean
-  _entry: DrawId | null
-  /** The geometry-buffer reference the entry was built from, acquired at
-   * attach and what _detach releases - like _transparent, a snapshot,
-   * because setGeometry swaps mesh.geometry before the rebuild. */
-  _buffers: GeometryBuffers | null
-  /** material.transparent as of the last attach - the entry's actual
-   * pipeline state, and what _detach counts against (setMaterial swaps
-   * mesh.material before the rebuild). */
-  _transparent: boolean
-  /** World-space center of the local bounds, refreshed at sort time: the
-   * transparent sort key. */
-  _center: Vec3
-  _params: ShaderParams | null
-  /** Instance state when the mesh was made by createInstancedMesh; null on
-   * an ordinary mesh. */
-  _instances: MeshInstances | null
-  /** True for a createSprite mesh: its quad faces the camera in the
-   * vertex stage, so it picks by a unit box instead of its flat triangles. */
-  _sprite: boolean
-}
-
-/** The per-mesh half of instancing: the record buffer and its bookkeeping.
- * Read the public fields freely; write through setInstances /
- * setInstanceCount so the draw range follows. */
-export type MeshInstances = {
-  /** The GPU record buffer, owned by the mesh (disposeInstances frees it). */
-  buffer: BufferId
-  /** Floats per record - the material's instanceAttributes summed. */
-  stride: number
-  /** Records the buffer has room for; doubles when setInstances writes
-   * more (a replacement buffer, never a resize). */
-  capacity: number
-  /** The buffer label, carried to replacement buffers on growth. */
-  label: string | undefined
-  /** Records currently drawn (the entry's instanceCount while visible). */
-  count: number
-  /** Explicit LOCAL bounds covering the whole population ([minX, minY,
-   * minZ, maxX, maxY, maxZ]), or null: the mesh then has no picking leaf -
-   * records are opaque data, so the library cannot derive where the
-   * instances are. */
-  bounds: Float32Array | null
-}
-
-/** A mesh from createInstancedMesh: an ordinary Mesh whose entry draws
- * `instances.count` copies of the geometry, one record each. */
-export type InstancedMesh = Mesh & { _instances: MeshInstances }
+// worldInto's out for the light/center readbacks below; nothing here
+// outlives a single call.
+let worldScratch = mat4()
 
 /** One picking intersection, Three's intersect result: the mesh, the
  * camera-ray distance in world units, the world-space point, and for a
  * triangle hit (every ordinary mesh - the test is per triangle, so a ray
  * through a knot's hole misses) the world-space geometric `normal` facing
  * the ray, the triangle index `face` and the interpolated texture `uv`.
- * An instanced mesh is picked by its explicit population box and a sprite
- * by a unit box around its center, so those three are absent on their
- * hits. */
+ * An instanced mesh is picked per instance, by the geometry's triangles
+ * placed as that instance (`instance` names it, Three's instanceId). A
+ * record mesh is picked by the faces of its explicit population box and
+ * a sprite by those of a unit box around its center, so their hits carry
+ * the struck face's `normal` and no `face`/`uv`. */
 export type Hit = {
   mesh: Mesh
+  /** The instance struck, for an instanced mesh. */
+  instance?: InstanceNode
   distance: number
   point: Vec3
-  normal?: Vec3
+  normal: Vec3
   face?: number
   uv?: [number, number]
 }
 
-/** The settled component of a node transition. */
-export type TransitionEndEvent = {
-  component: "position" | "rotation" | "scale"
-}
+/** A pixel's camera ray (screenRay): `direction` is NOT normalized - its
+ * camera-forward component is 1, so `origin + w * direction` is the world
+ * point at camera-forward distance `w` (unproject's mapping). */
+export type ScreenRay = { origin: Vec3; direction: Vec3 }
 
-/**
- * The event a mesh (or ancestor group) handler receives: the element
- * pointer vocabulary carried over, plus the 3D fields. `point`/`distance`
- * are null exactly when the ray misses the dispatch mesh - which happens
- * only during a captured drag or on a leave.
- */
-export type ScenePointerEvent = {
-  /** The mesh the event is about (the hit, or the captured mesh during a
-   * drag) - constant while the event bubbles. */
-  mesh: Mesh
-  /** Node whose handler is running; changes as the event bubbles. */
-  currentTarget: SceneNode
-  /** World-space hit point on `mesh`, or null when the ray misses it. */
-  point: Vec3 | null
-  /** Camera-ray distance to `point` in world units, or null with it. */
-  distance: number | null
-  /** Pointer position in scene pixels - project()'s coordinate space. */
-  x: number
-  y: number
-  pointerId: number
-  pointerType: string
-  button?: number
-  shiftKey: boolean
-  ctrlKey: boolean
-  altKey: boolean
-  metaKey: boolean
-  /** Stops the bubble walk after the current handler. */
-  stopPropagation(): void
+/** Filters for one raycast/overlap/sweep query. */
+export type QueryOptions = {
+  /**
+   * Layer mask replacing the scene's for this query (Unity's layerMask,
+   * Three's raycaster.layers): hits come from meshes whose `layers`
+   * intersect it, wherever the scene mask would look. A mask the scene
+   * excludes makes a ray-only mesh - a low-poly collision mesh living
+   * undrawn in the same scene, the physics-collider pattern.
+   */
+  layers?: number
+  /** Only these meshes report hits (Three's intersectObjects, an
+   * include-list); composes with `layers`. */
+  meshes?: Mesh[]
 }
 
+/** A query volume for overlap()/sweep(): a sphere, a capsule (the radius
+ * swept along the segment a-b) or an oriented box (half extents along
+ * the axes of `rotation`, identity when absent) - Unity's Overlap/Cast
+ * trio, Godot's Sphere/Capsule/BoxShape3D. */
+export type Sphere = { center: Vec3; radius: number }
+export type Capsule = { a: Vec3; b: Vec3; radius: number }
+export type OrientedBox = { center: Vec3; halfExtents: Vec3; rotation?: Quat }
+export type Volume = Sphere | Capsule | OrientedBox
+
+/** One mesh an overlap() volume touches: its deepest contact - the point
+ * on the mesh, the unit direction out of it, and the depth along that
+ * direction that clears the contact (Unity's ComputePenetration, Godot's
+ * get_rest_info, per mesh). `instance` names the instance touched on an
+ * instanced mesh, which reports once per instance. */
+export type Overlap = { mesh: Mesh; instance?: InstanceNode; point: Vec3; normal: Vec3; depth: number }
+
+/** One mesh a sweep() volume touches on its way: `time` is the fraction
+ * of the motion at first touch (0 for a volume already in contact and
+ * moving in), `point` the touch point on the mesh, `normal` the unit
+ * normal there facing the volume (Unity's RaycastHit from a cast,
+ * Godot's KinematicCollision3D). `instance` as on Overlap. */
+export type Impact = { mesh: Mesh; instance?: InstanceNode; time: number; point: Vec3; normal: Vec3 }
+
 /** Element handlers wiring a scene's pointer events: spread onto whatever
  * element shows `scene.texture` (the built-in `<Scene>` leaf wires them
  * automatically). `scene.handlers` expects the leaf laid out at the target
@@ -354,25 +194,6 @@ export type SceneHandlers = {
   onPointerLeave(event: ElementPointerEvent): void
 }
 
-/** An orthographic projection's view-space extents, in world units (the
- * same box at every depth). */
-export type OrthoExtent = { left: number; right: number; top: number; bottom: number }
-
-export type CameraUpdate = {
-  /** Vertical field of view in DEGREES (default 60). */
-  fov?: number
-  near?: number
-  far?: number
-  position?: Vec3
-  target?: Vec3
-  up?: Vec3
-  /** An orthographic projection with these extents (`fov` is then
-   * ignored); null returns to perspective. Three's OrthographicCamera as
-   * a camera option: a top-down map, an isometric view, a shadow-map
-   * light. */
-  ortho?: OrthoExtent | null
-}
-
 /**
  * Scene fog, by RADIAL distance from the camera, in one of two forms:
  * linear (Three's `Fog`, Unity's linear mode) fades toward `color` from
@@ -403,7 +224,8 @@ export type FogOptions = (
       density: number
     }
 ) & {
-  /** Straight [r, g, b], 0..1. */
+  /** Straight [r, g, b], 0..1, sRGB like every color option (decoded to
+   * linear light for the mix). */
   color: [number, number, number]
   /** World y at and below which the fog is full; default 0. Only acts
    * with a `heightFalloff`. */
@@ -413,13 +235,164 @@ export type FogOptions = (
   heightFalloff?: number
 }
 
+// The shared-param writes a fog value compiles to (null = the three zeros
+// that turn the factor off) - one source for scene.setFog and a view's own
+// `fog`, so both validate and spell the uniforms identically.
+function fogParams(fog: FogOptions | null): ShaderParams {
+  if (fog === null) return { uFogInv: 0, uFogDensity: 0, uFogHeightFalloff: 0 }
+  let color = linearColor(fog.color)
+  let height = fog.height ?? 0
+  let falloff = fog.heightFalloff ?? 0
+  if (!Number.isFinite(height) || !Number.isFinite(falloff) || falloff < 0) {
+    throw new Error(`fog: height must be finite and heightFalloff finite and >= 0, got ${height} / ${falloff}`)
+  }
+  let params: ShaderParams = { uFogColor: color, uFogHeight: height, uFogHeightFalloff: falloff }
+  if ("density" in fog) {
+    let { density } = fog
+    if (!Number.isFinite(density) || density <= 0) {
+      throw new Error(`fog: density must be finite and > 0, got ${density}`)
+    }
+    return { ...params, uFogInv: 0, uFogDensity: density }
+  }
+  let { near, far } = fog
+  if (!(Number.isFinite(near) && Number.isFinite(far)) || far <= near) {
+    throw new Error(`fog: near/far must be finite with near < far, got ${near}..${far}`)
+  }
+  return { ...params, uFogNear: near, uFogInv: 1 / (far - near), uFogDensity: 0 }
+}
+
+// `params` minus `names` - the scene-params fan-out around a view's own
+// names. Returns the input untouched (no copy) when nothing intersects.
+function withoutNames(params: ShaderParams, names: Set<string>): ShaderParams {
+  let hit = false
+  for (let k of names) {
+    if (k in params) {
+      hit = true
+      break
+    }
+  }
+  if (!hit) return params
+  let out: ShaderParams = {}
+  for (let k of Object.keys(params)) if (!names.has(k)) out[k] = params[k]!
+  return out
+}
+
+/**
+ * A skybox: the scene's background sampled from a cube map along each
+ * pixel's view ray (setBackground's object form). Three's
+ * `scene.background = cubeTexture` with `backgroundIntensity` and
+ * `backgroundRotation`; Unity's Skybox/Cubemap `_Exposure` and
+ * `_Rotation`; Godot's `background_energy_multiplier` and `sky_rotation`.
+ * Under an orthographic camera every pixel looks the same way, so the
+ * skybox is one flat color there (a sky needs perspective in every
+ * engine).
+ */
+export type SkyboxOptions = {
+  /** A cube map (createCubeTexture, faces in +X, -X, +Y, -Y, +Z, -Z
+   * order), sampled as GL defines it: each face is what a lookup in that
+   * direction returns. No lookup flip (Godot's and Unity's convention):
+   * a Three-style face set (each face as seen from inside) is mirrored
+   * per image at load, not in the shader. A 2D texture id throws. */
+  cube: TextureId
+  /** Multiplier on the sampled color, >= 0; default 1. */
+  intensity?: number
+  /** Turn about world y in RADIANS (default 0): the sky turns as a node
+   * with rotation [0, r, 0] would. Radians like node rotation and Three;
+   * Unity's `_Rotation` is degrees. */
+  rotation?: number
+}
+
+/**
+ * The scene's environment: a cube map every `lit` material with
+ * `reflectivity` mirrors (scene.setEnvironment). The same three fields
+ * as a skybox, and typically the same cube - Three's `scene.environment`
+ * with `environmentIntensity` and `environmentRotation`; Unity's
+ * environment reflections source, Godot's reflected light from the sky.
+ */
+export type EnvironmentOptions = {
+  /** A cube map (loadEnvironment's baked chain; equirectToCube for an LDR
+   * panorama; createCubeTexture with `mipmap: true` for a hand-baked
+   * sky), faces in +X, -X, +Y, -Y, +Z, -Z order, looked up like the
+   * skybox (no flip). A 2D texture id throws. */
+  cube: TextureId
+  /** Multiplier on the reflected color, >= 0; default 1. */
+  intensity?: number
+  /** Turn about world y in RADIANS (default 0), the skybox's convention:
+   * the environment turns as a node with rotation [0, r, 0] would. */
+  rotation?: number
+}
+
+// The uniform turn a rotated cube map is looked up through: the INVERSE
+// of the sky's turn, because a lookup along view direction v must find
+// the texel that sat at R(-r) v before the sky turned by +r.
+function cubeTurn(rotation: number): Mat4 {
+  let c = Math.cos(rotation)
+  let n = Math.sin(rotation)
+  // prettier-ignore
+  return [
+    c, 0, n, 0,
+    0, 1, 0, 0,
+    -n, 0, c, 0,
+    0, 0, 0, 1,
+  ]
+}
+
+function checkCubeKnobs(o: { intensity?: number; rotation?: number }, site: string): { intensity: number; rotation: number } {
+  let intensity = o.intensity ?? 1
+  let rotation = o.rotation ?? 0
+  if (!Number.isFinite(intensity) || intensity < 0) throw new Error(site + ": intensity must be a finite number >= 0, got " + intensity)
+  if (!Number.isFinite(rotation)) throw new Error(site + ": rotation must be a finite angle in radians, got " + rotation)
+  return { intensity, rotation }
+}
+
+// The entry params a skybox compiles to.
+function skyboxParams(sky: SkyboxOptions, site: string): ShaderParams {
+  let k = checkCubeKnobs(sky, site)
+  return { uSkyIntensity: k.intensity, uSkyRotation: cubeTurn(k.rotation) }
+}
+
+// The shared params an environment compiles to (null = off: uEnvOn 0
+// makes every reflective material's term vanish; the set ENVIRONMENT in
+// `@solidrt/3d/glsl` declares).
+function environmentParams(env: EnvironmentOptions | null): ShaderParams {
+  if (env === null) return { uEnvIntensity: 0, uEnvRotation: cubeTurn(0), uEnvOn: 0 }
+  let k = checkCubeKnobs(env, "scene.setEnvironment")
+  return { uEnvIntensity: k.intensity, uEnvRotation: cubeTurn(k.rotation), uEnvOn: 1 }
+}
+
+/** The output tone mapping (setToneMapping): "none" clamps, "aces" is the
+ * filmic curve every engine ships (Three's ACESFilmic, Godot's ACES,
+ * Unity's ACES). */
+export type ToneMapping = "none" | "aces"
+
+// The uToneMapping value per mode; the OUTPUT set branches on it.
+const TONE_MAPPING_CODE: Record<ToneMapping, number> = { none: 0, aces: 1 }
+
 export type SceneOptions = {
+  /** The target's clear, written as given: encoded pixels, untouched by
+   * exposure and tone mapping (a GLSL background or skybox goes through
+   * both). */
   clearColor?: [number, number, number, number]
   /** Scene-wide fog; see setFog. */
   fog?: FogOptions
-  /** Fragment GLSL drawn behind the meshes, inside the scene's own pass -
-   * see setBackground. */
-  background?: string
+  /** Output tone mapping, default "none"; see setToneMapping. */
+  toneMapping?: ToneMapping
+  /** Output exposure, default 1; see setExposure. */
+  exposure?: number
+  /** The scene target's layer mask (bitmask, default 1): the scene draws
+   * the meshes whose `layers` intersect it. Live via scene.setLayers. */
+  layers?: number
+  /** The scene target's depth storage: true (default) for a buffer,
+   * "texture" for a sampleable one exposed as `scene.depthTexture` - the
+   * input for a depth-reading post effect in `output` (depth fog, SSAO,
+   * depth of field). Not with `samples` (the engine has no multisampled
+   * sampleable depth): render larger and display smaller instead. */
+  depth?: true | "texture"
+  /** The background drawn behind the meshes, inside the scene's own pass:
+   * fragment GLSL or a skybox - see setBackground. */
+  background?: string | SkyboxOptions
+  /** The cube map reflective materials mirror; see setEnvironment. */
+  environment?: EnvironmentOptions
   label?: string
   /** `autoFree: false` opts out of owner-scoped auto-dispose (then call dispose yourself). */
   autoFree?: boolean
@@ -442,6 +415,17 @@ export type ViewOptions = {
    * draws in add order (no renderOrder or transparent sort).
    */
   overrideMaterial?: Material
+  /** The view's layer mask (bitmask, default 1): the view draws the
+   * meshes whose `layers` intersect it - a minimap admitting marker
+   * meshes only. Live via view.setLayers. */
+  layers?: number
+  /**
+   * The view's own fog: FogOptions overrides the scene's, null turns fog
+   * off in this view (an unfogged minimap over a fogged scene). Absent
+   * follows the scene. The fog names become view-owned params - the
+   * scene's setParams/setFog fan-out skips them (see View.setParams).
+   */
+  fog?: FogOptions | null
   /** The view target's depth storage: true (default) for a buffer,
    * "texture" for a sampleable one exposed as `view.depthTexture`. Not
    * with `into` (the depth is the parent's). */
@@ -471,25 +455,111 @@ export type View = {
   depthTexture: TextureId | null
   /** Partial camera update, exactly scene.setCamera. */
   setCamera(update: CameraUpdate): void
+  /** Current camera state, exactly scene.camera. */
+  camera(): CameraState
   setSize(width: number, height: number): void
   /** Move and resize a view created `into` an atlas (top-left origin);
    * throws on a view with a target of its own. */
   setRect(rect: { x: number; y: number; width: number; height: number }): void
-  /** View-owned shared params on the view's target (the scene's own
-   * setParams names fan out to every view already). */
+  /** View-owned shared params on the view's target. Names written here
+   * (and the `fog` option's) become the view's OWN: the scene's
+   * setParams/setFog fan-out skips them from then on, so a view override
+   * is never clobbered by the next scene-wide write. */
   setParams(params: ShaderParams): void
+  /** Replace the view's layer mask (bitmask): entries for newly admitted
+   * meshes attach, masked-out ones detach. */
+  setLayers(mask: number): void
   /** Destroy the view's target (its entries die with it). Idempotent;
    * views also die with their scene. */
   dispose(): void
 }
 
+/** A dynamic environment rendered from a point in the scene; see
+ * Scene.createReflectionProbe. */
+export type ReflectionProbeOptions = {
+  /** Where the probe looks out from, world space (live via setPosition). */
+  position: Vec3
+  /** Face edge in texels; default 128 (Unity's probe default). */
+  size?: number
+  /** The face cameras' near and far planes (defaults 0.1 and 100). */
+  near?: number
+  far?: number
+  /** Layer mask (bitmask, default 1): which meshes the probe sees. */
+  layers?: number
+  clearColor?: [number, number, number, number]
+  /** Convolve the faces into the roughness chain after each update
+   * (default true: Unity's and Godot's probes; `standard` blurs it by
+   * roughness like a baked environment). `false` keeps the sharp cube
+   * alone - Three's CubeCamera - at a sixth of the passes. */
+  prefilter?: boolean
+  label?: string
+}
+
+export type ReflectionProbe = {
+  /** The cube map: what `environment={{ cube }}` and `background={{
+   * cube }}` take. The prefiltered chain (roughness 0 sharp at level 0,
+   * blurred below, the same rule as a baked .srte), or with `prefilter:
+   * false` the sharp faces alone - then `standard` reflects it at its
+   * roughness 0 look whatever its roughness. */
+  cube: TextureId
+  setPosition(position: Vec3): void
+  /** Render the six faces now - six passes over the scene's draw list,
+   * seeing the meshes where the last frame's flush placed them - then
+   * (unless `prefilter: false`) the chain: one small pass per face per
+   * level. Call it when the surroundings changed (every frame for a
+   * moving scene, once for a still one). The probe's own cube is never
+   * sampled by the faces it renders (a black environment stands in): one
+   * bounce. */
+  update(): void
+  /** Destroy the cube (idempotent; probes also die with the scene). */
+  dispose(): void
+}
+
+// The face cameras of a reflection probe, GL order (+X, -X, +Y, -Y, +Z,
+// -Z): the direction each looks along and its up vector, chosen so that
+// through the x-mirrored projection (Camera.mirror) each face lands in
+// GL's own cube layout - plain world-up cameras, unlike Three's rolled
+// CubeCamera set, because target images here are stored top-down.
+const PROBE_FACE_DIRECTION: Vec3[] = [
+  [1, 0, 0],
+  [-1, 0, 0],
+  [0, 1, 0],
+  [0, -1, 0],
+  [0, 0, 1],
+  [0, 0, -1],
+]
+const PROBE_FACE_UP: Vec3[] = [
+  [0, 1, 0],
+  [0, 1, 0],
+  [0, 0, -1],
+  [0, 0, 1],
+  [0, 1, 0],
+  [0, 1, 0],
+]
+// Default face edge of a reflection probe (Unity's default resolution),
+// and of a baked background (the bake tool's default).
+const PROBE_SIZE = 128
+// A cube face spans a quarter turn.
+const PROBE_FOV = 90
+// The output stage of a cube that holds light rather than display pixels
+// (a probe's faces, a baked sky): no sRGB encode, no tone mapping, unit
+// exposure - so the environment lookups read radiance.
+const LINEAR_OUTPUT: ShaderParams = { uOutputEncode: 0, uToneMapping: TONE_MAPPING_CODE.none, uExposure: 1 }
+
 export type Scene = {
   /** The scene's output: an ordinary texture id (`<texture src>`). */
   texture: TextureId
+  /** The scene target's depth as a sampler-only texture id when created
+   * with `depth: "texture"`, else null. */
+  depthTexture: TextureId | null
   /** The tree root; add(scene.root, node) attaches top-level nodes. */
   root: SceneNode
   /** Partial camera update; absent keys keep their current value. */
   setCamera(update: CameraUpdate): void
+  /** The camera as the next frame draws it: setCamera's own fields, a
+   * fresh snapshot per call (arrays are copies - mutate freely, write
+   * back through setCamera). Reflects a pending setCamera immediately. */
+  camera(): CameraState
   setSize(width: number, height: number): void
   /**
    * Scene-wide uniforms: merge app-owned names into the target's SHARED
@@ -513,46 +583,141 @@ export type Scene = {
    * The background is not fogged: match colors (see FogOptions).
    */
   setFog(fog: FogOptions | null): void
+  /** Replace the scene target's layer mask (bitmask): entries for newly
+   * admitted meshes attach, masked-out ones detach. Shadow views follow
+   * this mask - what the scene cannot see must not darken it. */
+  setLayers(mask: number): void
+  /**
+   * Set, replace, or remove (null) the scene's background, drawn as the
+   * FIRST entry of the scene's own pass - one target, no second texture
+   * layer, no separate resize plumbing. It draws with depth off before
+   * every mesh and covers the whole target, so the clearColor stops being
+   * visible. Two forms:
+   *
+   * Fragment GLSL. The fragment gets the shader-target contract (vUV 0..1
+   * top-left origin, iResolution, fragColor; no `#version` line means the
+   * standard preamble), so a source written for createShaderTexture ports
+   * verbatim, PLUS `vRay`: the world-space view ray through the pixel
+   * (unnormalized; normalize it), which makes a directional sky - a
+   * horizon gradient, a sun disc, stars - a few lines of fragment code.
+   * The background is an ordinary scene entry, so it may also declare
+   * `uniform vec3 uCamPos` (the ray's origin) and any name written through
+   * scene.setParams (an app clock for an animated sky).
+   *
+   * A skybox (SkyboxOptions): `{ cube, intensity?, rotation? }` samples a
+   * cube map along the same ray. Replacing one skybox with another
+   * rewrites the entry's params and textures without recompiling, so
+   * `rotation` can animate from the reactive prop.
+   *
+   * Three's `scene.background = color` is `clearColor` here; a 2D image
+   * form can arrive later as a non-breaking widening.
+   */
+  setBackground(source: string | SkyboxOptions | null): void
   /**
-   * Set, replace, or remove (null) the scene's background: fragment GLSL
-   * drawn as the FIRST entry of the scene's own pass - one target, no
-   * second texture layer, no separate resize plumbing. The fragment gets
-   * the shader-target contract exactly (vUV 0..1 top-left origin,
-   * iResolution, fragColor; no `#version` line means the standard
-   * preamble), so a source written for createShaderTexture ports verbatim.
-   * It draws with depth off before every mesh and covers the whole target,
-   * so the clearColor stops being visible. Three's `scene.background =
-   * color` is `clearColor` here; the texture form can arrive later as a
-   * non-breaking widening. No app-driven uniforms in v1 - a background is
-   * static art (anything animated is a mesh's own shaderMaterial).
+   * Set, replace, or remove (null) the scene's environment: the cube map
+   * every `lit` material created with `reflectivity` mirrors, blurred by
+   * its `shininess`. Scene-level like Three's `scene.environment`,
+   * Unity's environment reflections and Godot's sky-lit reflections: one
+   * cube bound on every target the scene draws into, one shared-params
+   * write for intensity and rotation, however many meshes reflect (a
+   * custom material composes ENVIRONMENT from `@solidrt/3d/glsl`). No
+   * per-material map. Typically the skybox's own cube, turned with it.
+   * Not an ambient light source yet: the hemisphere light stays the
+   * ambient term.
    */
-  setBackground(source: string | null): void
+  setEnvironment(env: EnvironmentOptions | null): void
+  /**
+   * The output stage's tone mapping, applied by every library material,
+   * the skybox and a GLSL background that ends with outputColor: "none"
+   * (default) clamps the linear result, "aces" compresses highlights on
+   * the filmic curve. One shared-params write (`uToneMapping`, the OUTPUT
+   * set in `@solidrt/3d/glsl` declares), like Three's
+   * renderer.toneMapping and Godot's Environment tonemap; a custom
+   * fragment that writes fragColor directly is untouched. The clearColor
+   * is not tone mapped: with a curve on, draw the backdrop as a
+   * background.
+   */
+  setToneMapping(mode: ToneMapping): void
+  /**
+   * The output stage's exposure (default 1): the linear result is scaled
+   * by it before tone mapping, so a scene lit in physical-ish units is
+   * brought into range here rather than by dimming every light. One
+   * shared-params write (`uExposure`), like Three's toneMappingExposure.
+   */
+  setExposure(exposure: number): void
   /**
    * Project a world point to scene pixels: origin top-left, y down - the
    * output texture's own coordinate space, ready for overlay layout (HUD
-   * markers, labels). `w` is the clip-space w, the point's camera-forward
-   * distance (useful for depth-ordering or distance-scaling markers).
-   * Returns null for a point at or behind the camera plane - such a point
-   * has no place on screen. Reflects a pending setCamera immediately.
+   * markers, labels). `w` is the point's camera-forward distance in world
+   * units under either projection (useful for depth-ordering or
+   * distance-scaling markers, and unproject's exact input). Returns null
+   * for a point at or behind a PERSPECTIVE camera's plane - such a point
+   * has no place on screen; a parallel projection places every point, so
+   * an orthographic camera never returns null and `w` may be zero or
+   * negative there (negative near is legal ortho). Reflects a pending
+   * setCamera immediately.
    */
   project(point: Vec3): { x: number; y: number; w: number } | null
+  /**
+   * project()'s exact inverse (Unity's ScreenToWorldPoint, Godot's
+   * project_position): the world point at scene pixel (`x`, `y`) and
+   * camera-forward distance `w`, copied into `out` (or a fresh Vec3).
+   * project()'s `w` round-trips under either projection - the
+   * drag-at-depth recipe: project the grabbed point once, keep its `w`,
+   * unproject each pointer move to slide the object at its original
+   * depth. Reflects a pending setCamera immediately, like project().
+   */
+  unproject(x: number, y: number, w: number, out?: Vec3): Vec3
   /** The camera's view-projection matrix, copied into `out` (or a fresh
    * mat4). The batch escape hatch; for single points use project(). */
   viewProj(out?: Mat4): Mat4
   /**
    * Cast the camera ray through a scene pixel (top-left origin, y down -
    * project()'s space, the inverse direction) and return every visible
-   * mesh it hits, nearest first. The volume tier: hits test the mesh's
-   * bounding box, transformed exactly (any node transform, including
-   * non-uniform scale), so a hit through a concave gap - a knot's hole -
-   * still reports. Broadphase runs over a BVH kept in step by the sync
-   * walk: a query costs O(log meshes), not O(meshes). Reflects pending
-   * setTransform/add writes immediately (the sync is flushed).
+   * mesh it hits, nearest first. An ordinary mesh tests per triangle
+   * against its geometry (hits carry `face`, `uv`, a world-space `normal`
+   * facing the ray, and a ray through a knot's hole misses); an instanced
+   * mesh or sprite is tested by its box's faces (a `normal`, no
+   * `face`/`uv`). Broadphase runs over a BVH kept in step
+   * by the sync walk, and a large geometry's triangles are BVH-indexed
+   * too (built by the first ray that reaches it), so merged static
+   * geometry stays cheap to query. Reflects pending setTransform/add
+   * writes immediately (the sync is flushed).
    */
   pick(x: number, y: number): Hit[]
   /** pick()'s world-space half: the same query along an arbitrary ray.
    * `direction` need not be normalized; distances are world units. */
-  raycast(origin: Vec3, direction: Vec3): Hit[]
+  raycast(origin: Vec3, direction: Vec3, opts?: QueryOptions): Hit[]
+  /**
+   * Every mesh the volume touches (Unity's OverlapSphere/Box/Capsule,
+   * Godot's intersect_shape), each with its deepest contact. Tested per
+   * triangle in world space against the same shapes raycast() uses, so
+   * an undrawn collider layer answers through `opts.layers`, and any
+   * transform holds; an instanced mesh or sprite counts by its box.
+   * Surfaces, not solids: a volume wholly inside a closed mesh with no
+   * triangle in reach touches nothing. Unordered; reflects pending writes
+   * like raycast().
+   */
+  overlap(volume: Volume, opts?: QueryOptions): Overlap[]
+  /**
+   * The volume moved by `motion`: every mesh it touches on the way, at
+   * its first touch, earliest first (Unity's SphereCast/CapsuleCast/
+   * BoxCast, Godot's cast_motion). A volume already in contact reports
+   * time 0 while the motion closes in, and nothing while it leaves or
+   * slides along the contact - what lets a move-and-slide proceed along
+   * a wall. A zero motion touches nothing. Same testing as overlap().
+   */
+  sweep(volume: Volume, motion: Vec3, opts?: QueryOptions): Impact[]
+  /**
+   * pick()'s ray half (Unity's ScreenPointToRay, Godot's
+   * project_ray_origin/normal): the camera ray through a scene pixel,
+   * fresh arrays each call, for intersection work pick() cannot do - a
+   * drag plane, a ground grid, a raycast with the hits filtered
+   * yourself. `direction`'s camera-forward component is 1 (see
+   * ScreenRay), and raycast() takes it as-is. Reflects a pending
+   * setCamera immediately.
+   */
+  screenRay(x: number, y: number): ScreenRay
   /**
    * Element pointer handlers driving the mesh event fields
    * (onPointerDown/Move/Up/Enter/Leave on nodes): spread onto the element
@@ -586,11 +751,43 @@ export type Scene = {
    * nothing per view. Views share the scene's geometry buffers and
    * (unless `overrideMaterial`) its materials; the light set and
    * scene.setParams names fan out to every view, view.setParams is the
-   * view's own channel. The scene's background is not mirrored (a view's
-   * backdrop is its clearColor), and a view has no picking or pointer
-   * events. Views die with the scene; `view.dispose()` drops one early.
+   * view's own channel. A view's backdrop is its clearColor (the scene's
+   * background draws on probes, not on views), and a view has no picking
+   * or pointer events. Views die with the scene; `view.dispose()` drops
+   * one early.
    */
   createView(opts: ViewOptions): View
+  /**
+   * A reflection probe: the scene rendered into a cube map from a point,
+   * six faces at 90 degrees - Three's CubeCamera, Unity's and Godot's
+   * realtime ReflectionProbe - for the environment a moving object
+   * mirrors its surroundings through. A view under the hood (one entry
+   * list, the light set and scene params fanned out) that also draws the
+   * scene's background behind the meshes, as a probe does in every
+   * engine, rendered only by
+   * `probe.update()`, which the app calls when the surroundings moved:
+   * six scene passes each time, then the GPU prefilter into the roughness
+   * chain (unless `prefilter: false`), so `standard` blurs it by
+   * roughness exactly as it does a baked environment. Probes die with
+   * the scene.
+   */
+  createReflectionProbe(opts: ReflectionProbeOptions): ReflectionProbe
+  /**
+   * Bake the background into an environment: a reflection probe at the
+   * origin that sees no mesh (layer mask 0), so its six `size` faces
+   * (default 128) hold the background alone - the GLSL sky or the skybox,
+   * exactly as the scene draws it, written LINEAR (uOutputEncode 0, no tone mapping, unit exposure,
+   * so a sky ending in outputColor bakes its light; one writing fragColor
+   * raw bakes those bytes as light) - then GGX-prefiltered into the chain
+   * `standard` samples by roughness: Godot's sky-to-radiance bake, a
+   * procedural sky lighting the scene, or a hi-res LDR skybox reduced to
+   * an environment. A snapshot: bake again when the sky changed. Returns
+   * the cube for `environment={{ cube }}` - a mipmapped cube draw target,
+   * 8-bit linear like a probe, NOT auto-freed (an environment normally
+   * lives as long as the app; destroyTexture it otherwise). Throws
+   * without a background.
+   */
+  bakeBackground(size?: number): TextureId
   /** Destroy the target (entries die with it). Idempotent. Material
    * pipelines are shared and survive (app-lifetime, see material.ts);
    * geometry buffers are reference-counted and freed with their last
@@ -598,79 +795,6 @@ export type Scene = {
   dispose(): void
 }
 
-// A camera: the scene's own and one per view, the same state and the same
-// one-shared-write contract. `dirty` = the matrices need recomputing (a
-// setCamera or a resize), `pending` = the GPU write is owed to the next
-// sync. The recompute is split from the sync so project()/viewProj() see a
-// fresh matrix right after setCamera, before the microtask runs.
-type Camera = {
-  fov: number
-  near: number
-  far: number
-  eye: Vec3
-  target: Vec3
-  up: Vec3
-  ortho: OrthoExtent | null
-  dirty: boolean
-  pending: boolean
-  proj: Mat4
-  view: Mat4
-  viewProj: Mat4
-}
-
-function makeCamera(): Camera {
-  return {
-    fov: 60,
-    near: 0.1,
-    far: 100,
-    eye: [0, 0, 3],
-    target: [0, 0, 0],
-    up: [0, 1, 0],
-    ortho: null,
-    dirty: true,
-    pending: false,
-    proj: mat4(),
-    view: mat4(),
-    viewProj: mat4(),
-  }
-}
-
-function updateCamera(cam: Camera, update: CameraUpdate): void {
-  if (update.fov !== undefined) cam.fov = update.fov
-  if (update.near !== undefined) cam.near = update.near
-  if (update.far !== undefined) cam.far = update.far
-  if (update.position) cam.eye = [update.position[0], update.position[1], update.position[2]]
-  if (update.target) cam.target = [update.target[0], update.target[1], update.target[2]]
-  if (update.up) cam.up = [update.up[0], update.up[1], update.up[2]]
-  if (update.ortho !== undefined) {
-    let o = update.ortho
-    cam.ortho = o === null ? null : { left: o.left, right: o.right, top: o.top, bottom: o.bottom }
-  }
-  cam.dirty = true
-}
-
-function ensureCamera(cam: Camera, width: number, height: number): void {
-  if (!cam.dirty) return
-  cam.dirty = false
-  cam.pending = true
-  let o = cam.ortho
-  if (o === null) perspective(cam.proj, (cam.fov * Math.PI) / 180, width / height, cam.near, cam.far)
-  else orthographic(cam.proj, o.left, o.right, o.top, o.bottom, cam.near, cam.far)
-  lookAtMatrix(cam.view, cam.eye, cam.target, cam.up)
-  multiply(cam.viewProj, cam.proj, cam.view)
-}
-
-// The camera is target state: one shared write, whatever the target holds.
-// Entries are untouched - uModel is camera-independent, and uCamPos is
-// stored even when no current material declares it. The camera basis rides
-// along: the view matrix's first two rows are the camera's world-space
-// right and up (no clip flip - that lives in the projection), so a
-// billboard needs no reconstruction from uViewProj.
-function cameraParams(cam: Camera): ShaderParams {
-  let v = cam.view
-  return { uViewProj: cam.viewProj, uCamPos: cam.eye, uCamRight: [v[0], v[4], v[8]], uCamUp: [v[1], v[5], v[9]] }
-}
-
 // A material reads attributes by name; the geometry's layout must carry
 // every one it declares (the pipeline is built for that layout, so a
 // missing channel would have no home) - an error, like the rest of the
@@ -695,602 +819,6 @@ function entrySeed(material: Material, params: ShaderParams | null): ShaderParam
     : { uModel: IDENTITY, ...material.params, ...params }
 }
 
-// The uShadowAtlas binding while nothing casts: one white
-// texel (depth 1, never shadowed), shared by every scene for the app.
-let placeholder: TextureId | undefined
-
-function shadowPlaceholder(): TextureId {
-  if (placeholder === undefined) {
-    placeholder = createTexture(new Uint8Array([255, 255, 255, 255]), 1, 1, { autoFree: false, label: "scene-shadow-none" })
-  }
-  return placeholder
-}
-
-function makeNode(kind: SceneNode["kind"]): SceneNode {
-  return {
-    kind,
-    parent: null,
-    children: [],
-    position: [0, 0, 0],
-    quaternion: [0, 0, 0, 1],
-    scale: [1, 1, 1],
-    visible: true,
-    _node: null,
-    _moved: false,
-    _scene: null,
-    _transition: null,
-  }
-}
-
-export function createGroup(): SceneNode {
-  return makeNode("group")
-}
-
-export type DirectionalLightOptions = {
-  direction?: Vec3
-  color?: Vec3
-  intensity?: number
-  castShadow?: boolean
-  /** Shadow-map options, merged key by key (setLight keeps unmentioned ones). */
-  shadow?: ShadowOptions
-}
-export type HemisphereLightOptions = { sky?: Vec3; ground?: Vec3; intensity?: number }
-
-/** Every directional light may cast: the cap is MAX_LIGHTS (every map
- * is a tile of the scene's one shadow atlas, so the pass count does not
- * follow it, the fill does). */
-export const MAX_SHADOWS = MAX_LIGHTS
-export { MAX_CASCADES }
-
-function mergeShadow(into: DirectionalLight["shadow"], update: ShadowOptions): void {
-  if (update.mapSize !== undefined) into.mapSize = update.mapSize
-  if (update.bias !== undefined) into.bias = update.bias
-  if (update.normalBias !== undefined) into.normalBias = update.normalBias
-  if (update.camera !== undefined) Object.assign(into.camera, update.camera)
-  if (update.cascades !== undefined) {
-    let n = update.cascades
-    if (!Number.isInteger(n) || n < 1 || n > MAX_CASCADES) throw new Error("shadow.cascades must be an integer from 1 to " + MAX_CASCADES)
-    into.cascades = n
-  }
-  if (update.distance !== undefined) {
-    let d = update.distance
-    if (d !== null && !(d > 0)) throw new Error("shadow.distance must be a positive number or null")
-    into.distance = d
-  }
-}
-
-export function createDirectionalLight(opts: DirectionalLightOptions = {}): DirectionalLight {
-  let light = makeNode("light") as DirectionalLight
-  light.type = "directional"
-  light.direction = [...(opts.direction ?? [0, -1, 0])] as Vec3
-  light.color = [...(opts.color ?? [1, 1, 1])] as Vec3
-  light.intensity = opts.intensity ?? 1
-  light.castShadow = opts.castShadow === true
-  light.shadow = { mapSize: 1024, bias: 0, normalBias: 0, camera: { left: -5, right: 5, top: 5, bottom: -5, near: 0.5, far: 500 }, cascades: 1, distance: null }
-  if (opts.shadow !== undefined) mergeShadow(light.shadow, opts.shadow)
-  return light
-}
-
-export function createHemisphereLight(opts: HemisphereLightOptions = {}): HemisphereLight {
-  let light = makeNode("light") as HemisphereLight
-  light.type = "hemisphere"
-  light.sky = [...(opts.sky ?? [1, 1, 1])] as Vec3
-  light.ground = [...(opts.ground ?? [0.2, 0.2, 0.2])] as Vec3
-  light.intensity = opts.intensity ?? 1
-  return light
-}
-
-/** The write path for a light's own fields (color, intensity, direction
- * or sky/ground); absent keys keep their value. Its placement goes
- * through setTransform like any node. Frame-rate-safe. */
-export function setLight(light: DirectionalLight, update: DirectionalLightOptions): void
-export function setLight(light: HemisphereLight, update: HemisphereLightOptions): void
-export function setLight(light: Light, update: DirectionalLightOptions & HemisphereLightOptions): void {
-  if (update.intensity !== undefined) light.intensity = update.intensity
-  if (light.type === "directional") {
-    if (update.direction !== undefined) light.direction = [...update.direction] as Vec3
-    if (update.color !== undefined) light.color = [...update.color] as Vec3
-    let shadowChanged = false
-    if (update.castShadow !== undefined && update.castShadow !== light.castShadow) {
-      light.castShadow = update.castShadow
-      shadowChanged = true
-    }
-    if (update.shadow !== undefined) {
-      mergeShadow(light.shadow, update.shadow)
-      shadowChanged = true
-    }
-    if (shadowChanged) light._scene?._shadowChanged(light)
-  } else {
-    if (update.sky !== undefined) light.sky = [...update.sky] as Vec3
-    if (update.ground !== undefined) light.ground = [...update.ground] as Vec3
-  }
-  light._scene?._lightChanged()
-}
-
-export function createMesh(geometry: Geometry, material: Material): Mesh {
-  let mesh = makeNode("mesh") as Mesh
-  mesh.geometry = geometry
-  mesh.material = material
-  mesh.renderOrder = 0
-  mesh.castShadow = false
-  mesh._entry = null
-  mesh._buffers = null
-  mesh._transparent = false
-  mesh._center = [0, 0, 0]
-  mesh._params = null
-  mesh._instances = null
-  mesh._sprite = false
-  return mesh
-}
-
-// Every sprite draws the same unit quad, built once: geometry is data
-// and its GPU buffers are acquired per mesh, so one shared value is the
-// normal sharing story. The box is the quad's extent at any facing.
-let spriteQuad: Geometry | undefined
-const SPRITE_BOUNDS = new Float32Array([-0.5, -0.5, -0.5, 0.5, 0.5, 0.5])
-
-/**
- * A camera-facing quad, Three's `Sprite`: a unit plane drawn with a
- * `sprite()` material (any material works, but only a sprite material
- * turns the quad; there is no `geometry` argument). Size it with `scale` -
- * a scale of [2, 1, 1] is a 2 x 1 world-unit quad - and place it like any
- * mesh; its rotation is ignored, the camera decides the facing. Picking
- * is by a unit box around the center (the quad's reach at any facing, an
- * approximation), so hits carry no normal/face/uv.
- */
-export function createSprite(material: Material): Mesh {
-  if (spriteQuad === undefined) spriteQuad = plane({ label: "sprite" })
-  let mesh = createMesh(spriteQuad, material)
-  mesh._sprite = true
-  return mesh
-}
-
-/** The local box picking and sorting work from: explicit instance bounds
- * when the mesh is instanced (null without them - no leaf, no hits), the
- * unit box for a sprite, the geometry's own bounds otherwise. */
-function localBounds(mesh: Mesh): Float32Array | null {
-  if (mesh._instances !== null) return mesh._instances.bounds
-  return mesh._sprite ? SPRITE_BOUNDS : geometryBounds(mesh.geometry)
-}
-
-const ATTRIBUTE_FLOATS: Record<VertexAttribute["format"], number> = { f32: 1, vec2: 2, vec3: 3, vec4: 4 }
-
-function instanceStride(attributes: VertexAttribute[]): number {
-  let stride = 0
-  for (let a of attributes) stride += ATTRIBUTE_FLOATS[a.format]
-  return stride
-}
-
-export type InstancedMeshOptions = {
-  /** LOCAL bounds covering every instance the records place ([minX, minY,
-   * minZ, maxX, maxY, maxZ] - geometryBounds' shape), copied in. Records
-   * are opaque data, so only the app knows where its instances are: with
-   * bounds the mesh picks and transparent-sorts like any other
-   * (conservatively - one box around the whole population); without, it
-   * has no picking leaf and pointer events never target it. */
-  bounds?: ArrayLike<number>
-  /** Debug label for the record buffer. */
-  label?: string
-}
-
-/**
- * A mesh drawing `geometry` once per record of `records`: one draw entry,
- * one uModel write, N instances - the shape for forests, particles, and
- * every fleet whose per-copy data is a few floats rather than a merged
- * vertex buffer. The material must declare `instanceAttributes`
- * (shaderMaterialClass); its vertex stage reads each record through those
- * `in` variables. `records` is the interleaved attribute data (stride =
- * the attributes' floats summed) and is uploaded here; its length is the
- * buffer's initial capacity, which setInstances grows past on demand.
- * `count` limits how many records draw (default all), up to capacity.
- *
- * The result is an ordinary Mesh: add/remove, setTransform (uModel places
- * the whole population), setVisible (hiding zeroes the drawn count,
- * unhiding restores it), setMeshParams and renderOrder all apply. Update
- * records with setInstances, the drawn count with setInstanceCount, and
- * free the record buffer with disposeInstances when done for good.
- */
-export function createInstancedMesh(
-  geometry: Geometry,
-  material: Material,
-  records: Float32Array,
-  count?: number,
-  opts?: InstancedMeshOptions,
-): InstancedMesh {
-  let attributes = material.instanceAttributes
-  if (attributes === undefined) {
-    throw new Error(
-      "createInstancedMesh: the material declares no instanceAttributes - build it with shaderMaterialClass({ instanceAttributes: [...] })",
-    )
-  }
-  let stride = instanceStride(attributes)
-  if (records.length % stride !== 0) {
-    throw new Error(
-      "createInstancedMesh: " + records.length + " floats is not a whole number of " + stride + "-float records",
-    )
-  }
-  let bounds: Float32Array | null = null
-  if (opts?.bounds !== undefined) {
-    if (opts.bounds.length !== 6) {
-      throw new Error("createInstancedMesh: bounds must be [minX, minY, minZ, maxX, maxY, maxZ]")
-    }
-    bounds = new Float32Array(6)
-    for (let i = 0; i < 6; i++) bounds[i] = opts.bounds[i]!
-  }
-  let capacity = records.length / stride
-  let mesh = createMesh(geometry, material) as InstancedMesh
-  mesh._instances = {
-    buffer: createBuffer(records, { autoFree: false, label: opts?.label }),
-    stride,
-    capacity,
-    label: opts?.label,
-    count: Math.max(0, Math.min(Math.floor(count ?? capacity), capacity)),
-    bounds,
-  }
-  return mesh
-}
-
-/**
- * Overwrite an instanced mesh's records from the start of its buffer and
- * (by default) draw exactly the records written - pass `count` to draw
- * fewer, or to keep more previously written ones alive past a partial
- * rewrite. More records than the buffer holds grow it: capacity doubles
- * (or jumps to the records written when that is more), a new buffer is
- * created and written, the mesh's entry is re-pointed at it and the old
- * buffer freed - so a population grows without a new mesh, with the
- * copies amortized like any dynamic array (size the initial records to
- * skip them). Frame-rate-safe like setMeshParams when no growth happens.
- */
-export function setInstances(mesh: InstancedMesh, records: Float32Array, count?: number): void {
-  let inst = mesh._instances
-  if (records.length % inst.stride !== 0) {
-    throw new Error("setInstances: " + records.length + " floats is not a whole number of " + inst.stride + "-float records")
-  }
-  let written = records.length / inst.stride
-  if (written > inst.capacity) {
-    let previous = inst.buffer
-    inst.capacity = Math.max(written, inst.capacity * 2)
-    inst.buffer = createBuffer(inst.capacity * inst.stride * 4, { autoFree: false, label: inst.label })
-    mesh._scene?._setBuffer(mesh)
-    destroyBuffer(previous)
-  }
-  writeBuffer(inst.buffer, records)
-  setInstanceCount(mesh, count ?? written)
-}
-
-/** Set how many records draw (clamped to [0, capacity]). The visibility
- * switch composes: a hidden mesh stores the count and draws it on unhide. */
-export function setInstanceCount(mesh: InstancedMesh, count: number): void {
-  let inst = mesh._instances
-  let n = Math.max(0, Math.min(Math.floor(count), inst.capacity))
-  if (n === inst.count) return
-  inst.count = n
-  mesh._scene?._setCount(mesh)
-}
-
-/**
- * Detach the mesh (if attached) and free its record buffer. The buffer is
- * mesh-owned with no reference count (unlike geometry buffers it is never
- * shared), so this is the one explicit free; the mesh cannot be re-added
- * afterwards.
- */
-export function disposeInstances(mesh: InstancedMesh): void {
-  let inst: MeshInstances | null = mesh._instances
-  if (inst === null) return
-  if (mesh._scene) remove(mesh)
-  destroyBuffer(inst.buffer)
-  ;(mesh as Mesh)._instances = null
-}
-
-/** Attach `child` under `parent` (re-parenting detaches it first). */
-export function add(parent: SceneNode, child: SceneNode): void {
-  if (child.parent !== null) remove(child)
-  child.parent = parent
-  parent.children.push(child)
-  if (parent._scene) enterScene(child, parent._scene)
-}
-
-/** Detach `child` from its parent (and its meshes from the scene). */
-export function remove(child: SceneNode): void {
-  if (child._scene) leaveScene(child)
-  let parent = child.parent
-  if (parent !== null) {
-    let i = parent.children.indexOf(child)
-    if (i >= 0) parent.children.splice(i, 1)
-    child.parent = null
-  }
-}
-
-function enterScene(node: SceneNode, scene: SceneHooks): void {
-  node._scene = scene
-  node._node = spatial.createNode(fillTransform(node), node.visible)
-  if (node._transition !== null) {
-    spatial.setTransition(node._node, node._transition)
-    declareTransition(node._node, node)
-  }
-  // The parent is in the scene already (add() enters the child only then),
-  // and the scene root is the one node without a parent.
-  if (node.parent !== null && node.parent._node !== null) spatial.setParent(node._node, node.parent._node)
-  if (node.kind === "mesh") scene._attach(node as Mesh)
-  else if (node.kind === "light") scene._attachLight(node as Light)
-  for (let c of node.children) enterScene(c, scene)
-  scene._schedule()
-}
-
-function leaveScene(node: SceneNode): void {
-  let scene = node._scene
-  if (scene && node.kind === "mesh") scene._detach(node as Mesh)
-  else if (scene && node.kind === "light") scene._detachLight(node as Light)
-  node._scene = null
-  for (let c of node.children) leaveScene(c)
-  if (node._node !== null) {
-    declared.delete(node._node)
-    spatial.destroyNode(node._node)
-    node._node = null
-  }
-}
-
-/** The node's local transform in the FFI carrier. */
-function fillTransform(node: SceneNode): Float32Array {
-  let t = transformScratch
-  t[0] = node.position[0]; t[1] = node.position[1]; t[2] = node.position[2]
-  t[3] = node.quaternion[0]; t[4] = node.quaternion[1]; t[5] = node.quaternion[2]; t[6] = node.quaternion[3]
-  t[7] = node.scale[0]; t[8] = node.scale[1]; t[9] = node.scale[2]
-  return t
-}
-
-/** Forward a changed local transform to the core (no-op outside a scene:
- * entering pushes the whole transform). */
-function pushTransform(node: SceneNode): void {
-  if (node._node === null || node._scene === null) return
-  spatial.writeTransform(node._node, fillTransform(node))
-  node._scene._moved(node)
-}
-
-export type { TransformUpdate } from "./math.ts"
-
-/**
- * Declare (or with null clear) how the node's transform writes animate:
- * once set, setTransform writes are TARGETS the core animates toward
- * (position/scale per lane, rotation along the quaternion geodesic - a
- * spring keeps its velocity through retargets, the pursuit-safe shape),
- * so JS writes once per target change instead of once per frame. A spec
- * per component (position, rotation, scale) plus `all`; each
- * `{ duration, bounce? }` (a spring, the default) / `{ duration, curve }`
- * (a tween) / a shorthand string like "300ms ease-out". The declaration
- * lives on the node and re-applies whenever it enters a scene; the pose
- * it enters with always snaps. Clearing cancels running tracks in place
- * (the node keeps its mid-flight transform) and later writes snap. Each
- * natural settle calls the node's `onTransitionEnd` with the component
- * (the raw "spatialTransitionEnd" engine event on srt:events stays for
- * flux:spatial consumers; it carries the core id, `_node`).
- */
-export function setTransition(node: SceneNode, transition: NodeTransition | string | null): void {
-  node._transition = transition
-  if (node._node !== null) {
-    spatial.setTransition(node._node, transition)
-    if (transition === null) declared.delete(node._node)
-    else declareTransition(node._node, node)
-  }
-}
-
-/**
- * The one write path for node transforms (so the scene knows to sync).
- * Values are copied in; absent keys keep their current value. This is also
- * the frame-rate escape hatch: call it from onFrame on a node grabbed via
- * `ref`, bypassing signals entirely.
- *
- * A write that changes nothing schedules nothing, so driving every node
- * unconditionally from onFrame costs only the compare for the nodes that
- * did not move. Rotation is compared after conversion, so passing an euler
- * equal to the node's current quaternion is also a no-op.
- */
-export function setTransform(node: SceneNode, update: TransformUpdate): void {
-  // A no-op write costs nothing: driving every node from onFrame is the
-  // intended shape, and most nodes did not move. Exact compares, like
-  // setVisible - a value that survives a float round trip unchanged is the
-  // same value, and an epsilon would need a scale-dependent one anyway.
-  let changed = false
-  let p = update.position
-  if (p && (p[0] !== node.position[0] || p[1] !== node.position[1] || p[2] !== node.position[2])) {
-    node.position[0] = p[0]
-    node.position[1] = p[1]
-    node.position[2] = p[2]
-    changed = true
-  }
-  if (updateRotation(rotScratch, update, "setTransform")) {
-    let n = node.quaternion
-    if (rotScratch[0] !== n[0] || rotScratch[1] !== n[1] || rotScratch[2] !== n[2] || rotScratch[3] !== n[3]) {
-      n[0] = rotScratch[0]
-      n[1] = rotScratch[1]
-      n[2] = rotScratch[2]
-      n[3] = rotScratch[3]
-      changed = true
-    }
-  }
-  if (update.scale !== undefined) {
-    updateScale(scaleScratch, update.scale)
-    if (scaleScratch[0] !== node.scale[0] || scaleScratch[1] !== node.scale[1] || scaleScratch[2] !== node.scale[2]) {
-      node.scale[0] = scaleScratch[0]
-      node.scale[1] = scaleScratch[1]
-      node.scale[2] = scaleScratch[2]
-      changed = true
-    }
-  }
-  if (!changed) return
-  pushTransform(node)
-}
-
-/**
- * Aim a node at a WORLD-space point, Three's `Object3D.lookAt`: the node's
- * local +z ends up pointing at `target`, with `up` (world space, default
- * +y) choosing the roll about that axis. Ancestor transforms are undone,
- * so the aim holds under a rotated group - the ancestor chain is brought
- * up to date on the spot rather than waiting for the pending sync.
- *
- * +z because that is the library's own sweep axis (`extrude`, `sweep`,
- * `tube` run along z), so aiming their output needs no correction. For a
- * y-axis solid (`cylinder`, `cone`) reach for `quatFromTo` instead, which
- * takes the axis to aim as an argument.
- *
- * Writes `node.quaternion` - an ordinary rotation afterwards, readable and
- * overwritable by setTransform. To aim along a DIRECTION rather than at a
- * point, add it to the node's world position (`worldPosition`), the same
- * conversion Three asks for.
- *
- * Exact for rotation and uniform scale in the ancestor chain; a
- * non-uniformly scaled ancestor shears the frame and the aim is
- * approximate, exactly as in Three (both read the parent's upper 3x3 as
- * if it were a rotation).
- */
-export function lookAt(node: SceneNode, target: Vec3, up: Vec3 = WORLD_UP): void {
-  let parent = node.parent
-  if (parent === null) {
-    // No ancestors: parent space IS world space, aim straight from the
-    // node's own position.
-    aimScratch[0] = target[0] - node.position[0]
-    aimScratch[1] = target[1] - node.position[1]
-    aimScratch[2] = target[2] - node.position[2]
-    quatFromFrame(node.quaternion, aimScratch, up)
-  } else {
-    let world = worldInto(worldScratch, parent)
-    transformPoint(pointScratch, world, node.position)
-    aimScratch[0] = target[0] - pointScratch[0]
-    aimScratch[1] = target[1] - pointScratch[1]
-    aimScratch[2] = target[2] - pointScratch[2]
-    // World -> parent space for both vectors: rotating forward and up
-    // rotates the frame they build, so converting the inputs is the same
-    // as converting the resulting rotation, and needs no matrix inverse.
-    unrotate(aimScratch, world, aimScratch)
-    unrotate(upScratch, world, up)
-    quatFromFrame(node.quaternion, aimScratch, upScratch)
-  }
-  pushTransform(node)
-}
-
-/**
- * A node's rotation as Euler radians in XYZ order, copied into `out` (or a
- * fresh Vec3). A convenience for reading and debugging, NOT a peer of
- * `node.quaternion`: the conversion is lossy in the sense that it cannot
- * recover the triple that was written (see eulerFromQuat), only a triple
- * that means the same rotation. Anything composing or interpolating
- * rotations should work with the quaternion.
- */
-export function getRotation(node: SceneNode, out: Vec3 = [0, 0, 0]): Vec3 {
-  return eulerFromQuat(out, node.quaternion)
-}
-
-/**
- * A node's position in world space, copied into `out` (or a fresh Vec3) -
- * Three's `getWorldPosition`. Brings the ancestor chain up to date first,
- * so it is exact before the pending sync has run.
- */
-export function worldPosition(node: SceneNode, out: Vec3 = [0, 0, 0]): Vec3 {
-  let world = worldInto(worldScratch, node)
-  out[0] = world[12]
-  out[1] = world[13]
-  out[2] = world[14]
-  return out
-}
-
-/**
- * `out` = node's world matrix as the tree stands now. In a scene that is
- * one core read (pending writes included, nothing cleared); outside one
- * the chain is composed here. Scene membership is subtree-closed, so the
- * recursion meets a core node at the first in-scene ancestor at the
- * latest. One shared local scratch serves any depth - each frame uses it
- * only after its recursive call has returned.
- */
-function worldInto(out: Mat4, node: SceneNode): Mat4 {
-  if (node._node !== null) {
-    spatial.worldMatrix(node._node, worldRead)
-    for (let i = 0; i < 16; i++) out[i] = worldRead[i]!
-    return out
-  }
-  if (node.parent === null) identity(out)
-  else worldInto(out, node.parent)
-  return multiply(out, out, compose(localScratch, node.position, node.quaternion, node.scale))
-}
-
-/**
- * `out` = v with m's rotation undone: the transpose of m's upper 3x3 with
- * its columns normalized, so uniform scale divides out. out may alias v.
- */
-function unrotate(out: Vec3, m: Mat4, v: Vec3): Vec3 {
-  let x = v[0], y = v[1], z = v[2]
-  let l0 = Math.hypot(m[0], m[1], m[2]) || 1
-  let l1 = Math.hypot(m[4], m[5], m[6]) || 1
-  let l2 = Math.hypot(m[8], m[9], m[10]) || 1
-  out[0] = (m[0] * x + m[1] * y + m[2] * z) / l0
-  out[1] = (m[4] * x + m[5] * y + m[6] * z) / l1
-  out[2] = (m[8] * x + m[9] * y + m[10] * z) / l2
-  return out
-}
-
-/** Show or hide a node and its whole subtree (a hidden mesh costs one
- * `instanceCount: 0` draw range - the entry stays, drawing nothing). */
-export function setVisible(node: SceneNode, visible: boolean): void {
-  if (node.visible === visible) return
-  node.visible = visible
-  if (node._node !== null) {
-    spatial.setVisible(node._node, visible)
-    node._scene?._schedule()
-  }
-}
-
-/** Set a mesh's explicit draw-order key (see Mesh.renderOrder). */
-export function setRenderOrder(mesh: Mesh, order: number): void {
-  if (mesh.renderOrder === order) return
-  mesh.renderOrder = order
-  mesh._scene?._reorder()
-}
-
-/** Draw the mesh into the scene's shadow map, or stop (see Mesh.castShadow). */
-export function setCastShadow(mesh: Mesh, cast: boolean): void {
-  if (mesh.castShadow === cast) return
-  mesh.castShadow = cast
-  mesh._scene?._setCast(mesh)
-}
-
-/** Swap a mesh's geometry: its draw entry is rebuilt (the scene re-sorts
- * the list, so the mesh keeps its place). */
-export function setGeometry(mesh: Mesh, geometry: Geometry): void {
-  if (mesh._sprite) throw new Error("setGeometry: a sprite draws the shared unit quad and takes no geometry")
-  if (mesh.geometry === geometry) return
-  mesh.geometry = geometry
-  rebuildEntry(mesh)
-}
-
-/** Swap a mesh's material: its draw entry is rebuilt. */
-export function setMaterial(mesh: Mesh, material: Material): void {
-  if (mesh.material === material) return
-  mesh.material = material
-  rebuildEntry(mesh)
-}
-
-function rebuildEntry(mesh: Mesh): void {
-  let scene = mesh._scene
-  if (scene) {
-    scene._detach(mesh)
-    scene._attach(mesh)
-  }
-}
-
-/**
- * Write per-mesh uniforms - the channel for a custom material's app-driven
- * values (a time, a per-object tint). Names must be
- * declared and used by the mesh's material shaders (unknown names throw at
- * the call site, the engine's validation contract). Values persist on the
- * mesh: they survive geometry/material entry rebuilds and re-apply then.
- * Also the frame-rate path - like setTransform, call it from onFrame
- * freely.
- */
-export function setMeshParams(mesh: Mesh, params: ShaderParams): void {
-  if (mesh._params === null) mesh._params = {}
-  Object.assign(mesh._params, params)
-  mesh._scene?._setParams(mesh, params)
-}
-
 /**
  * Create a scene rendering into a depth-buffered draw target of the given
  * size. Returns the scene handle; `scene.texture` is the output. Inside a
@@ -1298,8 +826,15 @@ export function setMeshParams(mesh: Mesh, params: ShaderParams): void {
  * `autoFree: false`); outside one, call `dispose()` yourself.
  */
 export function createScene(width: number, height: number, opts?: SceneOptions): Scene {
+  let depthMode = opts?.depth ?? true
+  if (depthMode === "texture" && (opts?.samples ?? 1) > 1) {
+    throw new Error('createScene: depth "texture" cannot combine with samples (no multisampled sampleable depth) - render larger and display smaller instead')
+  }
+  // The scene target's layer mask; shadow views follow it (a mesh the
+  // scene cannot see must not darken it).
+  let sceneMask = checkMask(opts?.layers ?? 1, "createScene")
   let texture = createDrawTarget(width, height, null, {
-    depth: true,
+    depth: depthMode,
     clearColor: opts?.clearColor,
     filter: opts?.filter,
     wrap: opts?.wrap,
@@ -1311,15 +846,42 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   let scheduled = false
 
   // Picking: the index and the narrowphase live in the spatial core; this
-  // map turns a hit's core node back into the mesh. The pointer
-  // bookkeeping behind scene.handlers follows.
-  let byNode = new Map<NodeId, Mesh>()
+  // map turns a hit's core node back into the mesh, or the instance of an
+  // instanced mesh (each instance node is its own leaf).
+  let byNode = new Map<NodeId, Mesh | InstanceNode>()
+  // The per-query filter raycast/overlap/sweep share: a hit's core node
+  // back to its mesh (and instance), or null when the query mask excludes
+  // the mesh (skipped like an invisible one; the mask defaults to the
+  // scene's, so an undrawn layer needs an explicit opts.layers to report)
+  // or the include-list leaves it out.
+  let admitted = (qopts: QueryOptions | undefined, site: string) => {
+    let mask = qopts?.layers !== undefined ? checkMask(qopts.layers, site) : sceneMask
+    let include = qopts?.meshes !== undefined ? new Set(qopts.meshes) : null
+    return (node: NodeId): { mesh: Mesh; instance: InstanceNode | null } | null => {
+      let leaf = byNode.get(node)
+      if (leaf === undefined) return null
+      let instance = leaf.kind === "instance" ? leaf : null
+      let mesh = instance !== null ? instance.mesh : (leaf as Mesh)
+      if (mesh === null || (mesh.layers & mask) === 0) return null
+      if (include !== null && !include.has(mesh)) return null
+      return { mesh, instance }
+    }
+  }
   // Nodes whose transform changed since the last sync (deduped by the
   // _moved flag): what the light and transparent-order bookkeeping
   // reacts to, since which meshes moved is the core's knowledge now.
   let moved: SceneNode[] = []
-  let capture = new Map<number, Mesh>()
-  let hover = new Map<number, Mesh>()
+  // Instanced meshes with style writes to publish at the next sync.
+  let styleDirty = new Set<InstancedMesh>()
+  // Instanced meshes whose cull group - their live instance nodes - changed
+  // since the last sync: one setCullGroup per mesh however many entered
+  // or left.
+  let groupDirty = new Set<InstancedMesh>()
+  let instanceGroup = (mesh: InstancedMesh): NodeId[] => {
+    let members: NodeId[] = []
+    for (let n of mesh._instances.nodes.slots) if (n !== null && n._node !== null) members.push(n._node)
+    return members
+  }
 
   // Live meshes (those holding a draw entry) in add order; the background
   // entry never joins this list. Draw order is derived from it by
@@ -1333,47 +895,78 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   // light params at the end of the sync - one write, however many meshes.
   let lights: Light[] = []
   let lightsDirty = false
-  // uLightDir is CORE-DRIVEN: each directional light's slot is a
-  // shared-slot sink (bindDirectionSlot) following the node's world
-  // rotation, with -direction as the local vector (the shader wants the
-  // vector TOWARD the light) - so a light that merely moves costs no JS.
+  // uLightDir and uLightPos are CORE-DRIVEN: each light's slots are
+  // shared-slot sinks following the node's world transform - the
+  // direction slot (bindDirectionSlot) with -direction as the local
+  // vector (the shader wants the vector TOWARD the light; a spot's axis
+  // the same way), the position slot (bindPositionSlot) for the
+  // positional types - so a light that merely moves costs no JS.
   // This rewrite runs on attach/detach/field changes (and a new view)
-  // only and owns the rest: colors, count, hemisphere. The light set is
-  // scene state, so it lands on the scene target and every view target.
+  // only and owns the rest: types, colors, cone/falloff params, count,
+  // hemisphere. The light set is scene state, so it lands on the scene
+  // target and every view target.
   let vecScratch = new Float32Array(3)
+  // SPOT_PENUMBRA_MIN floors the cone's inner-outer cosine window so a
+  // hard rim (penumbra 0) is still a defined smoothstep edge pair.
+  const SPOT_PENUMBRA_MIN = 1e-3
   let writeLights = () => {
     lightsDirty = false
     let sky: Vec3 = [0, 0, 0]
     let ground: Vec3 = [0, 0, 0]
+    let types: number[] = []
     let colors: number[] = []
+    let coneFalloff: number[] = []
     let bias: number[] = []
     let normalBias: number[] = []
+    let radius: number[] = []
     let count = 0
     for (let light of lights) {
       if (light.type === "hemisphere") {
         let k = light.intensity
-        sky = [light.sky[0] * k, light.sky[1] * k, light.sky[2] * k]
-        ground = [light.ground[0] * k, light.ground[1] * k, light.ground[2] * k]
+        let s = linearColor(light.sky)
+        let g = linearColor(light.ground)
+        sky = [s[0]! * k, s[1]! * k, s[2]! * k]
+        ground = [g[0]! * k, g[1]! * k, g[2]! * k]
         continue
       }
-      vecScratch[0] = -light.direction[0]
-      vecScratch[1] = -light.direction[1]
-      vecScratch[2] = -light.direction[2]
-      spatial.bindDirectionSlot(light._node!, texture, "uLightDir", MAX_LIGHTS * 3, count, vecScratch)
-      for (let v of views) spatial.bindDirectionSlot(light._node!, v.texture, "uLightDir", MAX_LIGHTS * 3, count, vecScratch)
-      let c = light.color
+      if (light.type !== "point") {
+        vecScratch[0] = -light.direction[0]
+        vecScratch[1] = -light.direction[1]
+        vecScratch[2] = -light.direction[2]
+        spatial.bindDirectionSlot(light._node!, texture, "uLightDir", MAX_LIGHTS * 3, count, vecScratch)
+        for (let v of views) spatial.bindDirectionSlot(light._node!, v.texture, "uLightDir", MAX_LIGHTS * 3, count, vecScratch)
+      }
+      if (light.type !== "directional") {
+        spatial.bindPositionSlot(light._node!, texture, "uLightPos", MAX_LIGHTS * 3, count)
+        for (let v of views) spatial.bindPositionSlot(light._node!, v.texture, "uLightPos", MAX_LIGHTS * 3, count)
+      }
+      types.push(light.type === "directional" ? 0 : light.type === "spot" ? 1 : 2)
+      let c = linearColor(light.color)
       let k = light.intensity
-      colors.push(c[0] * k, c[1] * k, c[2] * k)
+      colors.push(c[0]! * k, c[1]! * k, c[2]! * k)
+      if (light.type === "spot") {
+        let pen = Math.max(light.penumbra, SPOT_PENUMBRA_MIN)
+        let rad = (light.angle * Math.PI) / 180
+        coneFalloff.push(Math.cos(rad * (1 - pen)), Math.cos(rad), light.distance, light.decay)
+      } else if (light.type === "point") {
+        coneFalloff.push(0, 0, light.distance, light.decay)
+      } else {
+        coneFalloff.push(0, 0, 0, 0)
+      }
       bias.push(light.shadow.bias)
       normalBias.push(light.shadow.normalBias)
+      radius.push(light.shadow.radius)
       count++
     }
     for (let i = count; i < MAX_LIGHTS; i++) {
+      types.push(0)
       colors.push(0, 0, 0)
+      coneFalloff.push(0, 0, 0, 0)
       bias.push(0)
       normalBias.push(0)
+      radius.push(1)
     }
-    // The shadow set rides with the lights. Per directional light i: its
+    // The shadow set rides with the lights. Per casting light i: its
     // map slots as uShadowFirst[i] + uShadowCount[i] (0 = a receiving
     // material draws that light plain) and its biases; per map slot j its
     // tile of the atlas as uShadowRect[j] in atlas UV (the whole map in
@@ -1383,12 +976,14 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let first: number[] = new Array(MAX_LIGHTS).fill(0)
     let counts: number[] = new Array(MAX_LIGHTS).fill(0)
     let rects: number[] = []
-    let atlas = shadowAtlas
-    let maps: Record<string, TextureId> = { uShadowAtlas: atlas !== null ? depthTexture(atlas.texture) : shadowPlaceholder() }
-    forEachShadowSlot((slot, i, shadow, c) => {
+    let atlas = shadowSys.atlas()
+    let maps: Record<string, TextureId> = {
+      uShadowAtlas: atlas !== null ? depthTexture(atlas.texture) : shadowSys.placeholder(),
+      uEnv: environment ?? envPlaceholder,
+    }
+    shadowSys.forEachShadowSlot((slot, i, c, r) => {
       if (c === 0) first[i] = slot
       counts[i] = counts[i]! + 1
-      let r = shadow.rects[c]!
       let a = atlas!
       rects.push(r.x / a.width, r.y / a.height, r.width / a.width, r.height / a.height)
     })
@@ -1397,29 +992,55 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       uHemiSky: sky,
       uHemiGround: ground,
       uLightCount: count,
+      uLightType: types,
       uLightColor: colors,
+      uLightParams: coneFalloff,
       uShadowFirst: first,
       uShadowCount: counts,
       uShadowBias: bias,
       uShadowNormalBias: normalBias,
+      uShadowRadius: radius,
       uShadowRect: rects,
     }
     receivingTargets(t => {
       setTargetParams(t, params)
-      setTargetTextures(t, maps)
+      // A probe never samples its own cube while rendering it (a same-pass
+      // feedback the engine rejects): its faces see a black environment.
+      setTargetTextures(t, ownsEnvironment(t) ? { ...maps, uEnv: envPlaceholder } : maps)
     })
     // A slot change (a light attached, detached or reordered) moves every
     // matrix too: rewrite the whole array once.
-    shadowMatricesDirty = true
+    shadowSys.markMatricesDirty()
   }
   let orderDirty = false
   // The order last handed to the engine: a resort that lands on the same
   // permutation (the common case under a moving camera) issues nothing.
   let lastOrder: DrawId[] = []
-  let background: { entry: DrawId; pipeline: RenderPipelineId; program: ProgramId } | null = null
+  // `skybox`: the entry runs the library's cube-map fragment (its params
+  // and textures are rewritable in place); false = app GLSL.
+  // `sky` is the skybox source (its cube and knobs) for the bake, null
+  // for a GLSL background.
+  // `entries` is the background's draw entry per target that draws it:
+  // the scene's own and every sky view's (a reflection probe), each first
+  // in its list.
+  let background: { pipeline: RenderPipelineId; program: ProgramId; sky: SkyboxOptions | null; entries: Map<TextureId, DrawId> } | null = null
+  // Add the current background to `target` before entry `before` (its
+  // first mesh entry; undefined appends, right for a target with none yet).
+  let attachBackground = (target: TextureId, before: DrawId | undefined) => {
+    if (background === null) return
+    let sky = background.sky
+    let params = sky === null ? null : skyboxParams(sky, "scene.setBackground")
+    let textures = sky === null ? undefined : { uSky: sky.cube }
+    background.entries.set(target, addDraw(target, background.pipeline, params, { vertexCount: 3, before, textures }))
+  }
+  // The environment cube bound as uEnv on every receiving target (the
+  // light rewrite seeds it on new targets); null binds the placeholder,
+  // the scene's own 1x1 black cube.
+  let environment: TextureId | null = null
+  let envPlaceholder = createEnvironmentPlaceholder((opts?.label ?? "scene") + "-env-none")
   let sortEntries = () => {
     orderDirty = false
-    let order = orderEntries(meshes, camera.view, background?.entry)
+    let order = orderEntries(meshes, camera.view, background?.entries.get(texture))
     if (order.length === lastOrder.length && order.every((id, i) => id === lastOrder[i])) return
     lastOrder = order
     setDrawOrder(texture, order)
@@ -1449,6 +1070,45 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   let clip: Vec4 = [0, 0, 0, 0]
   let pickOrigin: Vec3 = [0, 0, 0]
 
+  // The camera ray through a scene pixel, into the pickOrigin/pickDir
+  // scratches. The direction keeps a camera-forward component of 1
+  // (perspective: (cx, cy, -1) in the camera frame; ortho: unit forward),
+  // so origin + w * direction is the world point at camera-forward
+  // distance w - what unproject() banks on. pick()/screenRay()/
+  // unproject() all cast exactly this ray.
+  let pixelRay = (x: number, y: number): void => {
+    ensureCamera(camera, width, height)
+    let v = camera.view
+    let o = camera.ortho
+    if (o === null) {
+      // The camera-frame ray through the pixel, inverting project()'s
+      // mapping: the baked y-down clip flip is why pixel y converts with
+      // no negation there and one here.
+      let f = 1 / Math.tan(((camera.fov * Math.PI) / 180) / 2)
+      let cx = (((x / width) * 2 - 1) * (width / height)) / f
+      let cy = -((y / height) * 2 - 1) / f
+      // The view's upper 3x3 rows are the camera axes, so its transpose
+      // carries the camera-space direction (cx, cy, -1) to world.
+      pickDir[0] = cx * v[0] + cy * v[1] - v[2]
+      pickDir[1] = cx * v[4] + cy * v[5] - v[6]
+      pickDir[2] = cx * v[8] + cy * v[9] - v[10]
+      pickOrigin[0] = camera.eye[0]
+      pickOrigin[1] = camera.eye[1]
+      pickOrigin[2] = camera.eye[2]
+      return
+    }
+    // Orthographic: every ray runs along the camera's forward axis; the
+    // pixel picks where on the camera plane it starts (top row = top).
+    let cx = o.left + (x / width) * (o.right - o.left)
+    let cy = o.top + (y / height) * (o.bottom - o.top)
+    pickOrigin[0] = camera.eye[0] + cx * v[0] + cy * v[1]
+    pickOrigin[1] = camera.eye[1] + cx * v[4] + cy * v[5]
+    pickOrigin[2] = camera.eye[2] + cx * v[8] + cy * v[9]
+    pickDir[0] = -v[2]
+    pickDir[1] = -v[6]
+    pickDir[2] = -v[10]
+  }
+
   // Views (scene.createView): more targets drawing the same meshes from
   // their own cameras. A view holds one entry per mesh in its target,
   // bound as one more draw sink of the mesh's core node, so the flush
@@ -1460,149 +1120,115 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     width: number
     height: number
     override: Material | null
-    /** Which meshes the view draws (null = all): the shadow view's
-     * caster set. Re-evaluated per mesh by _setCast. */
-    filter: ((mesh: Mesh) => boolean) | null
+    /** Non-null marks a SHADOW view and names its caster set (m =>
+     * m.castShadow). Re-evaluated per mesh by _setCast; also picks the
+     * caster's own shadow material variant over the depth override. */
+    shadowFilter: ((mesh: Mesh) => boolean) | null
+    /** Layer mask: the view draws the meshes whose `layers` intersect
+     * it. A shadow view's follows the scene's. */
+    mask: number
+    /** Names the view set itself (view.setParams, the fog option): the
+     * scene's fan-out skips them so a view override survives scene-wide
+     * writes. */
+    ownNames: Set<string>
     camera: Camera
     entries: Map<Mesh, DrawId>
     orderDirty: boolean
     lastOrder: DrawId[]
+    /** A reflection probe's target is a cube draw target of this face
+     * edge, rendered face by face through probe.update(); null for a
+     * 2D view. */
+    cube: number | null
+    /** A probe's public cube: the chain prefiltered from its target, or
+     * the target itself when sharp (null for a 2D view). When it is the
+     * scene's environment, the probe's own faces bind the placeholder. */
+    probeCube: TextureId | null
+    /** Whether the scene's background draws on this target, first in its
+     * list (a probe: the sky behind the meshes); a plain view's backdrop
+     * is its clearColor. */
+    sky: boolean
     disposed: boolean
   }
   let views: ViewRecord[] = []
   // Every name scene.setParams has merged so far, replayed on a new view.
   let sceneParams: ShaderParams = {}
-  // The shadows, one per casting directional light: the internal views
-  // rendering its maps (tiles of the shadow atlas, depth override, casting
-  // meshes only; one for a box light, `shadow.cascades` for a cascaded
-  // one, tightest first) and `rects`, each tile's place in the atlas in
-  // texels. `lastWorld` is the light's world matrix the shadow cameras
-  // were last placed from; `dirty` forces a re-place (options changed).
-  type ShadowRect = { x: number; y: number; width: number; height: number }
-  type Shadow = { light: DirectionalLight; views: ViewRecord[]; lastWorld: Mat4; dirty: boolean; rects: ShadowRect[] }
-  let shadows = new Map<DirectionalLight, Shadow>()
-  // The map slots: every casting light's maps in light order, a light's
-  // cascades consecutive and tightest first. The ONE enumeration the
-  // receiving side is dealt by - rects and first/count in writeLights,
-  // matrices in sync - so uShadowFirst/uShadowCount agree with both.
-  // `i` is the light's directional index (its uShadow*[i] slot).
-  let forEachShadowSlot = (fn: (slot: number, i: number, shadow: Shadow, cascade: number) => void): void => {
-    let slot = 0
-    let i = 0
-    for (let light of lights) {
-      if (light.type !== "directional") continue
-      let shadow = shadows.get(light)
-      if (shadow !== undefined) for (let c = 0; c < shadow.views.length; c++) fn(slot++, i, shadow, c)
-      i++
-    }
-  }
-  // The shadow atlas: ONE depth-texture target every casting light's map
-  // is a tile of, so N maps render as one pass and receivers sample one
-  // sampler through per-map rects (uShadowRect). Created with the first
-  // caster, destroyed with the last. Laid out as a grid of cells the
-  // largest mapSize wide, scaled down uniformly when that would exceed
-  // the device's texture size: tile size follows the budget.
-  let shadowAtlas: { texture: TextureId; width: number; height: number } | null = null
-  let shadowLayout = (count: number, maxSize: number) => {
-    let cols = Math.ceil(Math.sqrt(count))
-    let rows = Math.ceil(count / cols)
-    let scale = Math.min(1, limits.maxTextureSize / (cols * maxSize), limits.maxTextureSize / (rows * maxSize))
-    let cell = Math.max(1, Math.floor(maxSize * scale))
-    return { cols, cell, scale, width: cols * cell, height: rows * cell }
-  }
-  // Place every shadow tile for the current caster set plus `adding` (not
-  // yet in `shadows`; its rects are returned for the view creates), in
-  // light order, a light's cascades consecutive. Sizes the atlas, moves
-  // tiles whose place changed, and drops the atlas when nothing casts.
-  // The rects reach receivers through the next light rewrite.
-  let placeShadows = (adding: DirectionalLight | null): ShadowRect[] | null => {
-    let casters: DirectionalLight[] = []
-    for (let l of lights) if (l.type === "directional" && (shadows.has(l) || l === adding)) casters.push(l)
-    if (adding !== null && !casters.includes(adding)) casters.push(adding)
-    lightsDirty = true
-    if (casters.length === 0) {
-      if (shadowAtlas !== null) {
-        destroyTexture(shadowAtlas.texture)
-        shadowAtlas = null
-      }
-      return null
-    }
-    let maxSize = 1
-    let tiles = 0
-    for (let l of casters) {
-      maxSize = Math.max(maxSize, l.shadow.mapSize)
-      tiles += l.shadow.cascades
-    }
-    let lay = shadowLayout(tiles, maxSize)
-    if (shadowAtlas === null) {
-      shadowAtlas = {
-        texture: createDrawTarget(lay.width, lay.height, null, {
-          depth: "texture",
-          clearColor: [1, 1, 1, 1],
-          label: (opts?.label ?? "scene") + "-shadow-atlas",
-          autoFree: false,
-        }),
-        width: lay.width,
-        height: lay.height,
-      }
-    } else if (shadowAtlas.width !== lay.width || shadowAtlas.height !== lay.height) {
-      setTargetSize(shadowAtlas.texture, lay.width, lay.height)
-      shadowAtlas.width = lay.width
-      shadowAtlas.height = lay.height
-    }
-    let placed: ShadowRect[] | null = null
-    let k = 0
-    for (let l of casters) {
-      let size = Math.max(1, Math.floor(l.shadow.mapSize * lay.scale))
-      let shadow = shadows.get(l)
-      for (let c = 0; c < l.shadow.cascades; c++, k++) {
-        let rect: ShadowRect = { x: (k % lay.cols) * lay.cell, y: Math.floor(k / lay.cols) * lay.cell, width: size, height: size }
-        if (shadow === undefined) {
-          if (placed === null) placed = []
-          placed.push(rect)
-          continue
-        }
-        let r = shadow.rects[c]!
-        if (r.x === rect.x && r.y === rect.y && r.width === rect.width && r.height === rect.height) continue
-        shadow.rects[c] = rect
-        let view = shadow.views[c]!
-        setTargetRect(view.texture, rect)
-        view.width = rect.width
-        view.height = rect.height
-        // A tile's texel size moved: the cascade fit snaps to it.
-        shadow.dirty = true
-      }
-    }
-    return placed
-  }
-  let shadowDir: Vec3 = [0, 0, 0]
-  // uShadowMatrix is one array param (the engine writes whole arrays), so
-  // any shadow camera move rewrites all MAX_SHADOW_MAPS matrices, identity
-  // in the slots that are not dealt.
-  let shadowMatrices: number[] = new Array(MAX_SHADOW_MAPS * 16).fill(0)
-  let shadowMatricesDirty = false
   // Every target a receiving material can draw into: the scene's and each
   // view's but the shadow views (binding a target's own depth into it
   // would be same-pass feedback).
   let receivingTargets = (fn: (target: TextureId) => void) => {
     fn(texture)
-    for (let v of views) if (v.filter === null) fn(v.texture)
+    for (let v of views) if (v.shadowFilter === null) fn(v.texture)
   }
+  // Whether receiving target `t` is the probe whose cube is the scene's
+  // environment (the faces, or the chain prefiltered from them): it
+  // samples the placeholder instead of itself.
+  let ownsEnvironment = (t: TextureId) => environment !== null && views.some(v => v.texture === t && v.probeCube === environment)
+  // The mesh's entry in the scene's OWN target - what mesh._entry is.
+  // Created when the scene mask admits the mesh, dropped when it stops:
+  // the same lifecycle a view entry has, so `_buffers` (not `_entry`) is
+  // the attached-to-the-scene sentinel.
+  let attachScene = (mesh: Mesh) => {
+    if (mesh._entry !== null) return
+    if ((mesh.layers & sceneMask) === 0) return
+    let inst = mesh._instances
+    let bufs = mesh._buffers!
+    // The entry starts switched off: it has no world matrix yet - the walk
+    // in sync() computes one - and _schedule() defers that to a microtask,
+    // so added live it would draw at the seeded identity until then. The
+    // mismatch branch in sync() turns it on in the same pass that writes
+    // uModel.
+    mesh._entry = addDraw(texture, mesh.material.pipeline(mesh.geometry.layout), entrySeed(mesh.material, mesh._params), {
+      buffer: bufs.buffer,
+      indexBuffer: bufs.index,
+      indexFormat: bufs.indexFormat,
+      textures: mesh._textures !== null ? { ...mesh.material.textures, ...mesh._textures } : mesh.material.textures,
+      ...(inst !== null ? instanceBinding(mesh.material, inst) : {}),
+      instanceCount: 0,
+    })
+    // The core turns the entry on (with the world matrix) at the next
+    // flush, and off again whenever the node or an ancestor hides.
+    spatial.bindDraw(mesh._node!, texture, mesh._entry, mesh.material.normalMatrix === true, inst !== null ? inst.count : 1)
+    orderDirty = true
+  }
+  let detachScene = (mesh: Mesh) => {
+    if (mesh._entry === null) return
+    if (mesh._node !== null) spatial.unbindDraw(mesh._node, texture)
+    if (!disposed) removeDraw(texture, mesh._entry)
+    mesh._entry = null
+    orderDirty = true
+  }
+  // The material a view draws a mesh with: a shadow view lets a caster's
+  // material pick its own depth variant (its cull side, cutout, skinning
+  // - or the class's shadowVertex, the instanced placement); any other
+  // override view draws exactly what it was given.
+  let viewMaterial = (v: ViewRecord, mesh: Mesh): Material =>
+    v.override !== null ? (v.shadowFilter !== null ? (mesh.material.shadow ?? v.override) : v.override) : mesh.material
   let attachView = (v: ViewRecord, mesh: Mesh) => {
+    if (v.entries.has(mesh)) return
     let inst = mesh._instances
-    if (v.override !== null && inst !== null) return
-    if (v.filter !== null && !v.filter(mesh)) return
-    // A shadow view (the filtered kind) lets a caster's material pick its
-    // own depth variant (its cull side); any other override view draws
-    // exactly what it was given.
-    let material = v.override !== null ? (v.filter !== null ? (mesh.material.shadow ?? v.override) : v.override) : mesh.material
+    if (v.shadowFilter !== null && !v.shadowFilter(mesh)) return
+    if ((mesh.layers & v.mask) === 0) return
+    let material = viewMaterial(v, mesh)
+    // An override pipeline cannot know a populated mesh's record layout,
+    // so the mesh is skipped - unless the variant chosen above is
+    // instanced itself (a class with shadowVertex, a stock material's
+    // instanced depth pass), whose attributes must fit the records like
+    // the main material's did at add().
+    if (v.override !== null && inst !== null) {
+      if (material.instanceAttributes === undefined) return
+      checkInstancePairing(material, inst, "Shadow material")
+    }
     let bufs = mesh._buffers!
     let entry = addDraw(v.texture, material.pipeline(mesh.geometry.layout), entrySeed(material, v.override !== null ? null : mesh._params), {
       buffer: bufs.buffer,
       indexBuffer: bufs.index,
       indexFormat: bufs.indexFormat,
-      textures: material.textures,
-      instanceBuffer: inst !== null ? inst.buffer : undefined,
+      // The mesh's own bindings ride with its own material and with any
+      // skinned stand-in (a skinned shadow variant declares uBones and
+      // needs the mesh's palette); other override programs may not
+      // declare the names, and per-entry bindings validate strictly.
+      textures: (material === mesh.material || material.skinned === true) && mesh._textures !== null ? { ...material.textures, ...mesh._textures } : material.textures,
+      ...(inst !== null ? instanceBinding(material, inst) : {}),
       instanceCount: 0,
     })
     spatial.bindDraw(mesh._node!, v.texture, entry, material.normalMatrix === true, inst !== null ? inst.count : 1)
@@ -1620,7 +1246,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   let sortView = (v: ViewRecord) => {
     v.orderDirty = false
     if (v.override !== null) return
-    let order = orderEntries(meshes, v.camera.view, undefined, m => v.entries.get(m as Mesh) ?? null)
+    let order = orderEntries(meshes, v.camera.view, background?.entries.get(v.texture), m => v.entries.get(m as Mesh) ?? null)
     if (order.length === v.lastOrder.length && order.every((id, i) => id === v.lastOrder[i])) return
     v.lastOrder = order
     setDrawOrder(v.texture, order)
@@ -1628,158 +1254,140 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   let disposeView = (v: ViewRecord) => {
     if (v.disposed) return
     v.disposed = true
+    background?.entries.delete(v.texture)
     for (let mesh of v.entries.keys()) if (mesh._node !== null) spatial.unbindDraw(mesh._node, v.texture)
     v.entries.clear()
     for (let light of lights) if (light.type === "directional" && light._node !== null) spatial.unbindSlot(light._node, v.texture)
+    spatial.setFrustum(v.texture, null)
     // Drain the zeroed direction slots while the target still exists.
     spatial.flush()
     destroyTexture(v.texture)
     let i = views.indexOf(v)
     if (i >= 0) views.splice(i, 1)
   }
+  // The six face renders of cube target `target` from `position` through
+  // `cam`, a mirrored 90-degree camera (PROBE_FACE_DIRECTION and
+  // PROBE_FACE_UP): each face's camera lands in the target's params,
+  // `perFace` runs (a probe's sort), then the face renders. With `chain`
+  // (a `mipmap: true` target, the prefilter's source) the first five faces
+  // render into level 0 explicitly - an explicit level regenerates nothing
+  // - and only the last face's plain render rebuilds the cube's chain: one
+  // generation per six faces instead of six (a whole-cube generateMipmap
+  // is the expensive step on some drivers).
+  let renderCubeFaces = (target: TextureId, cam: Camera, size: number, position: Vec3, chain: boolean, perFace?: (face: number) => void) => {
+    let last = PROBE_FACE_DIRECTION.length - 1
+    for (let face = 0; face <= last; face++) {
+      let d = PROBE_FACE_DIRECTION[face]!
+      updateCamera(cam, { position, target: [position[0] + d[0], position[1] + d[1], position[2] + d[2]], up: PROBE_FACE_UP[face] })
+      ensureCamera(cam, size, size)
+      cam.pending = false
+      setTargetParams(target, cameraParams(cam))
+      perFace?.(face)
+      if (chain && face < last) renderTarget(target, face, 0)
+      else renderTarget(target, face)
+    }
+  }
   // A view record: the target, seeded with everything the scene target
   // already holds (the light set - rewritten for every target, the simple
   // write - the merged scene params, the shadow map binding), then one
   // entry per mesh the filter admits.
-  let makeView = (vopts: ViewOptions, filter: ((mesh: Mesh) => boolean) | null): ViewRecord => {
+  let makeView = (
+    vopts: ViewOptions,
+    shadowFilter: ((mesh: Mesh) => boolean) | null,
+    cube: number | null = null,
+    mipmap = false,
+    sky = false,
+  ): ViewRecord => {
     let override = vopts.overrideMaterial ?? null
     if (override !== null) {
       for (let mesh of meshes) if (mesh._instances === null) checkLayout(override, mesh.geometry, "View override material")
     }
     let tiled = vopts.into !== undefined
     let v: ViewRecord = {
-      texture: createDrawTarget(vopts.width, vopts.height, null, {
-        depth: tiled ? undefined : (vopts.depth ?? true),
-        clearColor: vopts.clearColor,
-        filter: vopts.filter,
-        wrap: vopts.wrap,
-        samples: vopts.samples,
-        label: vopts.label ?? (opts?.label ?? "scene") + "-view",
-        autoFree: false,
-        into: vopts.into,
-        x: vopts.x,
-        y: vopts.y,
-      }),
+      texture:
+        cube !== null
+          ? createCubeDrawTarget(cube, null, {
+              depth: true,
+              // The prefilter reads the faces at the lod of each sample's
+              // solid angle: a generated chain, refreshed per face render.
+              mipmap,
+              // Linear radiance, HDR where the device renders half float.
+              format: probeFormat(),
+              clearColor: vopts.clearColor,
+              label: vopts.label ?? (opts?.label ?? "scene") + "-probe",
+              autoFree: false,
+            })
+          : createDrawTarget(vopts.width, vopts.height, null, {
+              depth: tiled ? undefined : (vopts.depth ?? true),
+              clearColor: vopts.clearColor,
+              filter: vopts.filter,
+              wrap: vopts.wrap,
+              samples: vopts.samples,
+              label: vopts.label ?? (opts?.label ?? "scene") + "-view",
+              autoFree: false,
+              into: vopts.into,
+              x: vopts.x,
+              y: vopts.y,
+            }),
       width: vopts.width,
       height: vopts.height,
       override,
-      filter,
+      shadowFilter,
+      mask: shadowFilter !== null ? sceneMask : checkMask(vopts.layers ?? 1, "createView"),
+      ownNames: new Set(),
       camera: makeCamera(),
       entries: new Map(),
       orderDirty: true,
       lastOrder: [],
+      cube,
+      probeCube: null,
+      sky,
       disposed: false,
     }
     views.push(v)
+    // The background goes in first (no mesh entry exists yet), where every
+    // later sort keeps it.
+    if (sky) attachBackground(v.texture, undefined)
     // The light rewrite seeds the shadow set (maps, casts, biases,
     // matrices) on the new target too.
     lightsDirty = true
-    setTargetParams(v.texture, sceneParams)
+    // The view's own fog claims its names before the scene-params seed,
+    // so the seed (and every later fan-out) leaves them to the view.
+    let ownFog = vopts.fog !== undefined ? fogParams(vopts.fog) : null
+    if (ownFog !== null) for (let k of Object.keys(ownFog)) v.ownNames.add(k)
+    setTargetParams(v.texture, ownFog === null ? sceneParams : withoutNames(sceneParams, v.ownNames))
+    if (ownFog !== null) setTargetParams(v.texture, ownFog)
     for (let mesh of meshes) attachView(v, mesh)
     hooks._schedule()
     return v
   }
-  // A shadow's views: one square tile of the shadow atlas per map drawing
-  // the casting meshes with the depth override from that map's frustum.
-  // The light rewrite writes the rects in the light's slots on every
-  // receiving target.
-  let createShadow = (light: DirectionalLight) => {
-    let rects = placeShadows(light)
-    if (rects === null || shadowAtlas === null) return
-    let atlas = shadowAtlas
-    let views = rects.map(rect =>
-      makeView(
-        {
-          width: rect.width,
-          height: rect.height,
-          into: atlas.texture,
-          x: rect.x,
-          y: rect.y,
-          overrideMaterial: shadowDepthMaterial(),
-          clearColor: [1, 1, 1, 1],
-          label: (opts?.label ?? "scene") + "-shadow",
-        },
-        m => m.castShadow,
-      ),
-    )
-    shadows.set(light, { light, views, lastWorld: mat4(), dirty: true, rects })
-    lightsDirty = true
-  }
-  let destroyShadow = (light: DirectionalLight) => {
-    let shadow = shadows.get(light)
-    if (shadow === undefined) return
-    shadows.delete(light)
-    for (let v of shadow.views) disposeView(v)
-    placeShadows(null)
-    lightsDirty = true
-    hooks._schedule()
-  }
-  // Place a shadow's cameras from its light's world matrix. A box light:
-  // at its world position, looking along its world direction, the light
-  // frustum as the orthographic extents. Compared against the matrix it
-  // was last placed from, so a scene animating elsewhere rewrites nothing
-  // here. A cascaded light also follows the scene camera (`cameraMoved`).
-  let cascadeScratch = mat4()
-  let cascadeCenter: Vec3 = [0, 0, 0]
-  let placeShadowCamera = (shadow: Shadow, cameraMoved: boolean) => {
-    let light = shadow.light
-    let m = worldInto(worldScratch, light)
-    let cascaded = shadow.views.length > 1
-    if (!shadow.dirty && !(cascaded && cameraMoved) && m.every((x, i) => x === shadow.lastWorld[i])) return
-    shadow.dirty = false
-    copy(shadow.lastWorld, m)
-    transformVector(shadowDir, m, light.direction)
-    let len = Math.hypot(shadowDir[0], shadowDir[1], shadowDir[2]) || 1
-    let d: Vec3 = [shadowDir[0] / len, shadowDir[1] / len, shadowDir[2] / len]
-    // A sun straight down is the common case and the degenerate one for
-    // world up: roll about z then (the map's orientation is invisible).
-    let up: Vec3 = Math.abs(d[1]) > VERTICAL_LIGHT ? [0, 0, 1] : [0, 1, 0]
-    if (!cascaded) {
-      let c = light.shadow.camera
-      updateCamera(shadow.views[0]!.camera, {
-        position: [m[12], m[13], m[14]],
-        target: [m[12] + d[0], m[13] + d[1], m[14] + d[2]],
-        up,
-        ortho: { left: c.left, right: c.right, top: c.top, bottom: c.bottom },
-        near: c.near,
-        far: c.far,
-      })
-      return
-    }
-    // Cascades: the scene camera's range near..far (far capped by
-    // shadow.distance) sliced by cascadeSplit, each slice's bounding
-    // sphere (frustumSliceSphere) as an orthographic box looking along
-    // the light, its centre snapped to the map's texel grid in light
-    // space (snapToGrid) so the shadow edges do not swim as the camera
-    // moves. The box reaches back toward the light by the whole range,
-    // so a caster outside the slice still casts into it.
-    let n = shadow.views.length
-    let near = camera.near
-    let far = Math.min(camera.far, light.shadow.distance ?? Infinity)
-    if (!(far > near)) far = near + 1
-    // The light's rotation only: rows are its right, up and back axes.
-    let basis = lookAtMatrix(cascadeScratch, [0, 0, 0], d, up)
-    let aspect = width / height
-    let zn = near
-    for (let c = 0; c < n; c++) {
-      let zf = cascadeSplit(near, far, c, n, CASCADE_SPLIT_LAMBDA)
-      let radius = frustumSliceSphere(cascadeCenter, camera, aspect, zn, zf)
-      zn = zf
-      let view = shadow.views[c]!
-      // A texel is 2r / mapSize world units.
-      snapToGrid(cascadeCenter, cascadeCenter, basis, (2 * radius) / view.width)
-      let back = radius + far
-      updateCamera(view.camera, {
-        position: [cascadeCenter[0] - d[0] * back, cascadeCenter[1] - d[1] * back, cascadeCenter[2] - d[2] * back],
-        target: cascadeCenter,
-        up,
-        ortho: { left: -radius, right: radius, top: radius, bottom: -radius },
-        near: 0,
-        far: back + radius,
-      })
-    }
-  }
+  // The shadow subsystem: the atlas, the per-caster shadow views (made
+  // through makeView above) and their map cameras. The deps close over
+  // this scene instance; writeLights reads the dealt slots back through
+  // forEachShadowSlot/atlas and sync drives placeCameras/flushMatrices.
+  let shadowSys = makeShadowSystem({
+    lights,
+    camera,
+    targetSize: () => ({ width, height }),
+    label: opts?.label ?? "scene",
+    makeView,
+    disposeView,
+    markLightsDirty: () => {
+      lightsDirty = true
+    },
+    schedule: () => hooks._schedule(),
+  })
 
+  // A camera write is also the target's frustum for the core's culling:
+  // the scene's own, every view's, every shadow tile's - set before the
+  // flush below, which switches the entries outside it off. Cube face
+  // renders (probes) set no frustum: six cameras share one target and the
+  // core would only ever see the last.
+  let frustumScratch = new Float32Array(16)
+  let setFrustum = (target: TextureId, cam: Camera) => {
+    frustumScratch.set(cam.viewProj)
+    spatial.setFrustum(target, frustumScratch)
+  }
   let sync = () => {
     scheduled = false
     if (disposed) return
@@ -1788,35 +1396,39 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     if (camera.pending) {
       camera.pending = false
       setTargetParams(texture, cameraParams(camera))
+      setFrustum(texture, camera)
       if (transparentCount > 1) orderDirty = true
     }
-    for (let shadow of shadows.values()) placeShadowCamera(shadow, cameraMoved)
+    shadowSys.placeCameras(cameraMoved)
     for (let v of views) {
       ensureCamera(v.camera, v.width, v.height)
       if (v.camera.pending) {
         v.camera.pending = false
         setTargetParams(v.texture, cameraParams(v.camera))
+        setFrustum(v.texture, v.camera)
         if (transparentCount > 1) v.orderDirty = true
-        if (v.filter !== null) shadowMatricesDirty = true
+        if (v.shadowFilter !== null) shadowSys.markMatricesDirty()
       }
     }
     // Light bookkeeping first, so a fresh direction-slot bind is seeded
     // by the flush below in the same sync.
     if (lightsDirty) writeLights()
+    // The instanced meshes' style writes since the last sync: one
+    // coalesced buffer write per mesh.
+    if (styleDirty.size > 0) {
+      for (let m of styleDirty) if (m._instances !== null) publishInstanceStyle(m)
+      styleDirty.clear()
+    }
+    // An instanced mesh without explicit bounds is culled by the union of
+    // its instances' boxes: the core's cull group (a skinned part's joint
+    // group, generalized) over the live instance nodes.
+    if (groupDirty.size > 0) {
+      for (let m of groupDirty) if (m._node !== null && m._buffers !== null && m._instances !== null) spatial.setCullGroup(m._node, instanceGroup(m))
+      groupDirty.clear()
+    }
     // The matrices that render the maps are the ones receivers look up
     // with: one array to every receiving target per shadow-camera move.
-    if (shadowMatricesDirty) {
-      shadowMatricesDirty = false
-      let dealt = 0
-      forEachShadowSlot((slot, _i, shadow, c) => {
-        let m = shadow.views[c]!.camera.viewProj
-        for (let k = 0; k < 16; k++) shadowMatrices[slot * 16 + k] = m[k]!
-        dealt = slot + 1
-      })
-      for (let slot = dealt; slot < MAX_SHADOW_MAPS; slot++) for (let k = 0; k < 16; k++) shadowMatrices[slot * 16 + k] = IDENTITY[k]!
-      let params: ShaderParams = { uShadowMatrix: shadowMatrices }
-      receivingTargets(t => setTargetParams(t, params))
-    }
+    shadowSys.flushMatrices(params => receivingTargets(t => setTargetParams(t, params)))
     // The core recomputes the moved subtrees and writes every entry's
     // uModel/uNormal, visibility switch and direction slots.
     spatial.flush()
@@ -1846,49 +1458,39 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     },
     _attachLight(light) {
       if (disposed) return
-      if (light.type === "directional" && lights.filter(l => l.type === "directional").length >= MAX_LIGHTS) {
-        throw new Error("A scene takes at most " + MAX_LIGHTS + " directional lights")
+      if (light.type !== "hemisphere" && lights.filter(l => l.type !== "hemisphere").length >= MAX_LIGHTS) {
+        throw new Error("A scene takes at most " + MAX_LIGHTS + " lights (directional, spot and point together)")
       }
       lights.push(light)
       lightsDirty = true
-      if (light.type === "directional" && light.castShadow) createShadow(light)
+      if (light.type !== "hemisphere" && light.castShadow) shadowSys.createShadow(light)
     },
     _detachLight(light) {
       let i = lights.indexOf(light)
       if (i >= 0) lights.splice(i, 1)
       lightsDirty = true
-      if (light.type === "directional") destroyShadow(light)
+      if (light.type !== "hemisphere") shadowSys.destroyShadow(light)
       hooks._schedule()
     },
     _shadowChanged(light) {
       if (disposed) return
-      let shadow = shadows.get(light)
-      if (shadow !== undefined) {
-        if (!light.castShadow) {
-          destroyShadow(light)
-          return
-        }
-        // A cascade count change is a different view set: rebuild it. A
-        // mapSize change re-places every tile (the grid cell follows the
-        // largest map).
-        if (shadow.views.length !== light.shadow.cascades) {
-          destroyShadow(light)
-          createShadow(light)
-          return
-        }
-        placeShadows(null)
-        shadow.dirty = true
-        lightsDirty = true
-        hooks._schedule()
-      } else if (light.castShadow) {
-        createShadow(light)
-      }
+      shadowSys.shadowChanged(light)
     },
     _setCast(mesh) {
-      if (mesh._entry === null || disposed) return
+      if (mesh._buffers === null || disposed) return
+      for (let v of views) {
+        if (v.shadowFilter === null) continue
+        if (v.shadowFilter(mesh)) attachView(v, mesh)
+        else detachView(v, mesh)
+      }
+      hooks._schedule()
+    },
+    _setLayers(mesh) {
+      if (mesh._buffers === null || disposed) return
+      if ((mesh.layers & sceneMask) !== 0) attachScene(mesh)
+      else detachScene(mesh)
       for (let v of views) {
-        if (v.filter === null) continue
-        if (v.filter(mesh)) attachView(v, mesh)
+        if ((mesh.layers & v.mask) !== 0) attachView(v, mesh)
         else detachView(v, mesh)
       }
       hooks._schedule()
@@ -1907,53 +1509,59 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         if (v.override !== null && mesh._instances === null) checkLayout(v.override, mesh.geometry, "View override material")
       }
       // Instancing pairs the same way layout does: the pipeline's instance
-      // attributes describe the mesh's record buffer, so one without the
+      // attributes describe the mesh's record buffers, so one without the
       // other (or a record stride from a different attribute list) would
       // bind garbage - errors here, at add().
       let inst = mesh._instances
-      let instAttrs = mesh.material.instanceAttributes
-      if (instAttrs !== undefined && inst === null) {
+      if (mesh.material.instanceAttributes !== undefined && inst === null) {
         throw new Error(
-          "Material declares instanceAttributes - create its meshes with createInstancedMesh (records included), not createMesh",
+          "Material declares instanceAttributes - create its meshes with createInstancedMesh or createRecordMesh, not createMesh",
         )
       }
-      if (inst !== null) {
-        if (instAttrs === undefined) {
-          throw new Error("Instanced mesh with a non-instanced material - the material must declare instanceAttributes")
-        }
-        let stride = instanceStride(instAttrs)
-        if (stride !== inst.stride) {
-          throw new Error(
-            "Instanced mesh records are " + inst.stride + " floats but the material's instanceAttributes take " + stride,
-          )
-        }
-      }
+      if (inst !== null) checkInstancePairing(mesh.material, inst, "Mesh material")
       let bufs = acquireGeometryBuffers(mesh.geometry)
       mesh._buffers = bufs
-      // The entry starts switched off: it has no world matrix yet - the walk
-      // in sync() computes one - and _schedule() defers that to a microtask,
-      // so added live it would draw at the seeded identity until then. The
-      // mismatch branch in sync() turns it on in the same pass that writes
-      // uModel.
-      mesh._entry = addDraw(texture, mesh.material.pipeline(mesh.geometry.layout), entrySeed(mesh.material, mesh._params), {
-        buffer: bufs.buffer,
-        indexBuffer: bufs.index,
-        indexFormat: bufs.indexFormat,
-        textures: mesh.material.textures,
-        instanceBuffer: inst !== null ? inst.buffer : undefined,
-        instanceCount: 0,
-      })
-      // The core turns the entry on (with the world matrix) at the next
-      // flush, and off again whenever the node or an ancestor hides.
-      spatial.bindDraw(mesh._node!, texture, mesh._entry, mesh.material.normalMatrix === true, inst !== null ? inst.count : 1)
+      attachScene(mesh)
       for (let v of views) attachView(v, mesh)
+      // The style mirror may have been written while the mesh was out of
+      // a scene (or into a buffer this scene never saw): republish it.
+      if (inst !== null && inst.style !== null) {
+        inst.style.dirty = inst.count > 0 ? [0, inst.count * inst.style.stride] : null
+        if (inst.style.dirty !== null) styleDirty.add(mesh as InstancedMesh)
+      }
       // Picking: the local box puts the node in the core index; an
-      // ordinary mesh also gets its geometry's triangle shape, an
-      // instanced one is box-only (records are opaque, and without
-      // explicit bounds it is not picked at all), as is a sprite (its
-      // triangles lie wherever the camera is, not where the geometry says).
+      // ordinary mesh also gets its geometry's triangle shape, a
+      // populated one is box-only (its instances are the leaves that
+      // pick, each with the shape; a record mesh's records are opaque, so
+      // without explicit bounds it is not picked at all), as is a sprite
+      // (its triangles lie wherever the camera is, not where the geometry
+      // says).
       spatial.setBounds(mesh._node!, localBounds(mesh))
       spatial.setShape(mesh._node!, inst === null && !mesh._sprite ? bufs.shape : null)
+      // A rebuilt entry (setGeometry) re-boxes the live instances to the
+      // new geometry; their record bindings are untouched. On a first
+      // entry none has a core node yet - they enter after the mesh.
+      if (inst !== null && inst.nodes !== null) {
+        for (let n of inst.nodes.slots) {
+          if (n !== null && n._node !== null) {
+            spatial.setBounds(n._node, geometryBounds(mesh.geometry))
+            spatial.setShape(n._node, bufs.shape)
+          }
+        }
+      }
+      // Culling: the gate and margin only when off the defaults, and a
+      // skinned part's joint group (joints entered before it: a model
+      // adds its node tree before its parts).
+      if (!mesh.frustumCulled || mesh.cullMargin !== 0) spatial.setCull(mesh._node!, mesh.frustumCulled, mesh.cullMargin)
+      if (mesh._cullJoints !== null) {
+        let joints: NodeId[] = []
+        for (let j of mesh._cullJoints) if (j._node !== null) joints.push(j._node)
+        spatial.setCullGroup(mesh._node!, joints)
+      }
+      // An instanced mesh without explicit bounds is culled by its
+      // instances' union, the same group over the instance nodes - set
+      // at the sync, once they have entered (they enter after the mesh).
+      if (inst !== null && inst.nodes !== null && inst.bounds === null) groupDirty.add(mesh as InstancedMesh)
       byNode.set(mesh._node!, mesh)
       meshes.push(mesh)
       mesh._transparent = mesh.material.transparent === true
@@ -1962,16 +1570,17 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       this._schedule()
     },
     _detach(mesh) {
-      if (mesh._entry !== null) {
+      if (mesh._buffers !== null) {
+        styleDirty.delete(mesh as InstancedMesh)
+        groupDirty.delete(mesh as InstancedMesh)
         for (let v of views) detachView(v, mesh)
+        detachScene(mesh)
         if (mesh._node !== null) {
           spatial.setShape(mesh._node, null)
           spatial.setBounds(mesh._node, null)
-          spatial.unbindDraw(mesh._node, texture)
           byNode.delete(mesh._node)
         }
-        if (!disposed) removeDraw(texture, mesh._entry)
-        if (mesh._buffers !== null) releaseGeometryBuffers(mesh._buffers)
+        releaseGeometryBuffers(mesh._buffers)
         mesh._buffers = null
         let i = meshes.indexOf(mesh)
         if (i >= 0) meshes.splice(i, 1)
@@ -1980,9 +1589,35 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       }
       mesh._entry = null
     },
+    _attachInstance(instance) {
+      if (disposed) return
+      let mesh = instance.mesh
+      // The mesh entered first (parents enter before children), so its
+      // geometry buffers and core node are live - a mesh masked out of
+      // the scene included, whose instances still pick.
+      if (mesh === null || mesh._buffers === null || mesh._node === null || instance._node === null) return
+      spatial.setBounds(instance._node, geometryBounds(mesh.geometry))
+      spatial.setShape(instance._node, mesh._buffers.shape)
+      // The record is the instance's placement inside the mesh (the mesh
+      // node is the anchor), staged by the core at the next flush.
+      spatial.bindMatrixRecord(instance._node, mesh._instances.buffer, instance._slot, mesh._node)
+      byNode.set(instance._node, instance)
+      if (mesh._instances.bounds === null) groupDirty.add(mesh)
+      this._schedule()
+    },
+    _detachInstance(instance) {
+      // The core node is destroyed right after: its box, shape and record
+      // binding go with it, and the slot hides at the next flush. The
+      // mesh's group loses the member at the sync (a mesh leaving with
+      // its instances is skipped there: its node is gone by then).
+      if (instance._node !== null) byNode.delete(instance._node)
+      let mesh = instance.mesh
+      if (mesh !== null && mesh._instances !== null && mesh._instances.bounds === null) groupDirty.add(mesh)
+      this._schedule()
+    },
     _setParams(mesh, params) {
-      if (mesh._entry === null || disposed) return
-      setDrawParams(texture, mesh._entry, params)
+      if (mesh._buffers === null || disposed) return
+      if (mesh._entry !== null) setDrawParams(texture, mesh._entry, params)
       // A view drawing the mesh's own material carries its params too; an
       // overridden view has none of them.
       for (let v of views) {
@@ -1993,22 +1628,29 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     _setCount(mesh) {
       // The core composes the count with the visibility switch: a hidden
       // entry stays at 0 and the unhide restores the new count.
-      if (mesh._entry !== null && mesh._node !== null && !disposed && mesh._instances !== null) {
+      if (mesh._buffers !== null && mesh._node !== null && !disposed && mesh._instances !== null) {
         spatial.setDrawCount(mesh._node, mesh._instances.count)
       }
     },
     _setBuffer(mesh) {
-      // The entry keeps its range (at most the old capacity, so the larger
-      // buffer always passes the swap's bounds check); the caller destroys
-      // the old buffer after this, which the entry held alive until now.
-      if (mesh._entry !== null && !disposed && mesh._instances !== null) {
-        setDrawBuffers(texture, mesh._entry, { instanceBuffer: mesh._instances.buffer })
+      // The entries keep their range (at most the old capacity, so the
+      // larger buffers always pass the swap's bounds check); the caller
+      // destroys the old buffers after this, which the entries held alive
+      // until now. Each entry swaps the slots its own material binds.
+      let inst = mesh._instances
+      if (mesh._buffers !== null && !disposed && inst !== null) {
+        if (mesh._entry !== null) setDrawBuffers(texture, mesh._entry, instanceBinding(mesh.material, inst))
         for (let v of views) {
           let entry = v.entries.get(mesh)
-          if (entry !== undefined) setDrawBuffers(v.texture, entry, { instanceBuffer: mesh._instances.buffer })
+          if (entry !== undefined) setDrawBuffers(v.texture, entry, instanceBinding(viewMaterial(v, mesh), inst))
         }
       }
     },
+    _setStyle(mesh) {
+      if (disposed || mesh._buffers === null) return
+      styleDirty.add(mesh)
+      this._schedule()
+    },
     _reorder() {
       orderDirty = true
       for (let v of views) v.orderDirty = true
@@ -2032,134 +1674,23 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   lightsDirty = true
   hooks._schedule()
 
-  // --- Pointer event dispatch (behind scene.handlers) ---
-
-  type BubbleName = "onPointerDown" | "onPointerMove" | "onPointerUp"
-  type InternalEvent = ScenePointerEvent & { _stopped: boolean }
-
-  let makeEvent = (e: ElementPointerEvent, mesh: Mesh, x: number, y: number, point: Vec3 | null, distance: number | null): InternalEvent => {
-    let event: InternalEvent = {
-      mesh,
-      currentTarget: mesh,
-      point,
-      distance,
-      x,
-      y,
-      pointerId: e.pointerId,
-      pointerType: e.pointerType,
-      button: e.button,
-      shiftKey: e.shiftKey,
-      ctrlKey: e.ctrlKey,
-      altKey: e.altKey,
-      metaKey: e.metaKey,
-      _stopped: false,
-      stopPropagation() {
-        event._stopped = true
-      },
-    }
-    return event
-  }
-
-  let bubble = (name: BubbleName, event: InternalEvent): void => {
-    for (let n: SceneNode | null = event.mesh; n !== null && !event._stopped; n = n.parent) {
-      let handler = n[name]
-      if (handler) {
-        event.currentTarget = n
-        handler(event)
-      }
-    }
-  }
-
-  // The captured mesh's own hit, if the ray still strikes it.
-  let hitOn = (mesh: Mesh, x: number, y: number): Hit | null => {
-    for (let h of scene.pick(x, y)) if (h.mesh === mesh) return h
-    return null
-  }
-
-  // localX/localY arrive in the leaf's LAYOUT frame (the hit test undoes
-  // every transform above it, design-size fits included), so a leaf laid out at
-  // the target size - the built-in <Scene> leaf, a d-texture at natural
-  // size - is already in scene pixels. Only a leaf deliberately laid out at
-  // a DIFFERENT size (the supersampling pattern) needs the ratio, and only
-  // the app knows that layout: handlersFor takes it.
-  let makeHandlers = (layout: (() => { width: number; height: number }) | null): SceneHandlers => {
-    let eventX = 0
-    let eventY = 0
-    let toScene = (e: ElementPointerEvent): void => {
-      if (layout === null) {
-        eventX = e.localX
-        eventY = e.localY
-        return
-      }
-      let l = layout()
-      eventX = e.localX * (l.width > 0 ? width / l.width : 1)
-      eventY = e.localY * (l.height > 0 ? height / l.height : 1)
-    }
-    return {
-      onPointerDown(e) {
-        toScene(e)
-        let hit = scene.pick(eventX, eventY)[0]
-        if (hit === undefined) return
-        capture.set(e.pointerId, hit.mesh)
-        bubble("onPointerDown", makeEvent(e, hit.mesh, eventX, eventY, hit.point, hit.distance))
-      },
-      onPointerMove(e) {
-        toScene(e)
-        let captured = capture.get(e.pointerId)
-        if (captured !== undefined) {
-          let hit = hitOn(captured, eventX, eventY)
-          bubble("onPointerMove", makeEvent(e, captured, eventX, eventY, hit ? hit.point : null, hit ? hit.distance : null))
-          return
-        }
-        let hit = scene.pick(eventX, eventY)[0]
-        let prev = hover.get(e.pointerId)
-        if (prev !== hit?.mesh) {
-          if (prev !== undefined) {
-            hover.delete(e.pointerId)
-            prev.onPointerLeave?.(makeEvent(e, prev, eventX, eventY, null, null))
-          }
-          if (hit !== undefined) {
-            hover.set(e.pointerId, hit.mesh)
-            hit.mesh.onPointerEnter?.(makeEvent(e, hit.mesh, eventX, eventY, hit.point, hit.distance))
-          }
-        }
-        if (hit !== undefined) {
-          bubble("onPointerMove", makeEvent(e, hit.mesh, eventX, eventY, hit.point, hit.distance))
-        }
-      },
-      onPointerUp(e) {
-        toScene(e)
-        let captured = capture.get(e.pointerId)
-        if (captured !== undefined) {
-          capture.delete(e.pointerId)
-          let hit = hitOn(captured, eventX, eventY)
-          bubble("onPointerUp", makeEvent(e, captured, eventX, eventY, hit ? hit.point : null, hit ? hit.distance : null))
-          return
-        }
-        let hit = scene.pick(eventX, eventY)[0]
-        if (hit !== undefined) {
-          bubble("onPointerUp", makeEvent(e, hit.mesh, eventX, eventY, hit.point, hit.distance))
-        }
-      },
-      onPointerLeave(e) {
-        let prev = hover.get(e.pointerId)
-        if (prev !== undefined) {
-          hover.delete(e.pointerId)
-          toScene(e)
-          prev.onPointerLeave?.(makeEvent(e, prev, eventX, eventY, null, null))
-        }
-      },
-    }
-  }
-  let handlers = makeHandlers(null)
+  // Pointer dispatch (scene.handlers): capture/hover bookkeeping and the
+  // bubble walk live in scene-pointer.ts; all it needs of the scene is
+  // pick() and the target size.
+  let pointer = makePointerInput({
+    pick: (x, y) => scene.pick(x, y),
+    targetSize: () => ({ width, height }),
+  })
 
   let scene: Scene = {
     texture,
+    depthTexture: depthMode === "texture" ? depthTexture(texture) : null,
     root,
     setCamera(update) {
       updateCamera(camera, update)
       hooks._schedule()
     },
+    camera: () => cameraState(camera),
     setSize(w, h) {
       if (disposed || (w === width && h === height)) return
       width = w
@@ -2172,48 +1703,85 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       if (disposed) return
       Object.assign(sceneParams, params)
       setTargetParams(texture, params)
-      for (let v of views) setTargetParams(v.texture, params)
+      for (let v of views) {
+        // A view's own names (view.setParams, its fog) win over the
+        // scene-wide fan-out.
+        let fanned = v.ownNames.size === 0 ? params : withoutNames(params, v.ownNames)
+        if (fanned !== params && Object.keys(fanned).length === 0) continue
+        setTargetParams(v.texture, fanned)
+      }
     },
     setFog(fog) {
-      if (fog === null) {
-        scene.setParams({ uFogInv: 0, uFogDensity: 0, uFogHeightFalloff: 0 })
-        return
-      }
-      let color = [fog.color[0], fog.color[1], fog.color[2]]
-      let height = fog.height ?? 0
-      let falloff = fog.heightFalloff ?? 0
-      if (!Number.isFinite(height) || !Number.isFinite(falloff) || falloff < 0) {
-        throw new Error(`setFog: height must be finite and heightFalloff finite and >= 0, got ${height} / ${falloff}`)
+      scene.setParams(fogParams(fog))
+    },
+    setLayers(mask) {
+      checkMask(mask, "scene.setLayers")
+      if (disposed || sceneMask === mask) return
+      sceneMask = mask
+      for (let mesh of meshes) {
+        if ((mesh.layers & mask) !== 0) attachScene(mesh)
+        else detachScene(mesh)
       }
-      let params: ShaderParams = { uFogColor: color, uFogHeight: height, uFogHeightFalloff: falloff }
-      if ("density" in fog) {
-        let { density } = fog
-        if (!Number.isFinite(density) || density <= 0) {
-          throw new Error(`setFog: density must be finite and > 0, got ${density}`)
+      // Shadow views follow the scene's mask: what the scene cannot see
+      // must not darken it.
+      for (let v of views) {
+        if (v.shadowFilter === null) continue
+        v.mask = mask
+        for (let mesh of meshes) {
+          if ((mesh.layers & mask) !== 0) attachView(v, mesh)
+          else detachView(v, mesh)
         }
-        scene.setParams({ ...params, uFogInv: 0, uFogDensity: density })
-        return
       }
-      let { near, far } = fog
-      if (!(Number.isFinite(near) && Number.isFinite(far)) || far <= near) {
-        throw new Error(`setFog: near/far must be finite with near < far, got ${near}..${far}`)
-      }
-      scene.setParams({ ...params, uFogNear: near, uFogInv: 1 / (far - near), uFogDensity: 0 })
+      hooks._schedule()
     },
     setBackground(source) {
       if (disposed) return
+      // A skybox replacing a skybox keeps its entries: same program, new
+      // params and cube on every target.
+      if (source !== null && typeof source !== "string" && background !== null && background.sky !== null) {
+        let params = skyboxParams(source, "scene.setBackground")
+        for (let [target, entry] of background.entries) {
+          setDrawParams(target, entry, params)
+          setDrawTextures(target, entry, { uSky: source.cube })
+        }
+        background.sky = source
+        return
+      }
+      let sky = source === null || typeof source === "string" ? null : source
+      if (sky !== null) skyboxParams(sky, "scene.setBackground")
       if (background !== null) {
-        removeDraw(texture, background.entry)
+        for (let [target, entry] of background.entries) removeDraw(target, entry)
         destroyRenderPipeline(background.pipeline)
         destroyProgram(background.program)
         background = null
       }
       if (source === null) return
-      let built = backgroundPipeline(source, (opts?.label ?? "scene") + "-background")
-      // First in list order: inserted before the first mesh entry, and every
+      let label = opts?.label ?? "scene"
+      let built = sky === null ? backgroundPipeline(source as string, label + "-background") : backgroundPipeline(SKYBOX_FRAGMENT, label + "-skybox")
+      background = { pipeline: built.pipeline, program: built.program, sky, entries: new Map() }
+      // First in list order on every target that draws it: inserted before
+      // the first mesh ENTRY (a layers-masked mesh has none), and every
       // later sort keeps it there.
-      let entry = addDraw(texture, built.pipeline, null, { vertexCount: 3, before: meshes[0]?._entry ?? undefined })
-      background = { entry, pipeline: built.pipeline, program: built.program }
+      attachBackground(texture, meshes.find(m => m._entry !== null)?._entry ?? undefined)
+      for (let v of views) if (v.sky && !v.disposed) attachBackground(v.texture, v.lastOrder[0] ?? v.entries.values().next().value)
+    },
+    setEnvironment(env) {
+      if (disposed) return
+      let params = environmentParams(env)
+      environment = env === null ? null : env.cube
+      let cube = environment ?? envPlaceholder
+      // A probe's own faces never sample the probe (see writeLights).
+      receivingTargets(t => setTargetTextures(t, { uEnv: ownsEnvironment(t) ? envPlaceholder : cube }))
+      scene.setParams(params)
+    },
+    setToneMapping(mode) {
+      let code = TONE_MAPPING_CODE[mode]
+      if (code === undefined) throw new Error('scene.setToneMapping: expected "none" or "aces", got ' + mode)
+      scene.setParams({ uToneMapping: code })
+    },
+    setExposure(exposure) {
+      if (!Number.isFinite(exposure) || exposure < 0) throw new Error("scene.setExposure: expected a finite number >= 0, got " + exposure)
+      scene.setParams({ uExposure: exposure })
     },
     project(point) {
       ensureCamera(camera, width, height)
@@ -2221,50 +1789,48 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       let w = clip[3]
       if (w < 1e-6) return null
       // perspective() bakes the y-down clip flip, so NDC maps straight to
-      // top-left-origin pixels with no negation here. (An orthographic
-      // camera has w = 1 everywhere: every point projects.)
-      return { x: ((clip[0] / w) * 0.5 + 0.5) * width, y: ((clip[1] / w) * 0.5 + 0.5) * height, w }
+      // top-left-origin pixels with no negation here.
+      let x = ((clip[0] / w) * 0.5 + 0.5) * width
+      let y = ((clip[1] / w) * 0.5 + 0.5) * height
+      if (camera.ortho !== null) {
+        // An orthographic clip w is 1 everywhere (every point projects, the
+        // divides above are no-ops) and carries no depth, so `w` reports
+        // the camera-forward distance off the view row instead - the same
+        // meaning as the perspective clip w, and unproject's exact input.
+        let v = camera.view
+        w = -(v[2] * point[0] + v[6] * point[1] + v[10] * point[2] + v[14])
+      }
+      return { x, y, w }
     },
     viewProj(out) {
       ensureCamera(camera, width, height)
       return copy(out ?? mat4(), camera.viewProj)
     },
     pick(x, y) {
-      ensureCamera(camera, width, height)
-      let v = camera.view
-      let o = camera.ortho
-      if (o === null) {
-        // The camera-frame ray through the pixel, inverting project()'s
-        // mapping: the baked y-down clip flip is why pixel y converts with
-        // no negation there and one here.
-        let f = 1 / Math.tan(((camera.fov * Math.PI) / 180) / 2)
-        let cx = (((x / width) * 2 - 1) * (width / height)) / f
-        let cy = -((y / height) * 2 - 1) / f
-        // The view's upper 3x3 rows are the camera axes, so its transpose
-        // carries the camera-space direction (cx, cy, -1) to world.
-        pickDir[0] = cx * v[0] + cy * v[1] - v[2]
-        pickDir[1] = cx * v[4] + cy * v[5] - v[6]
-        pickDir[2] = cx * v[8] + cy * v[9] - v[10]
-        return scene.raycast(camera.eye, pickDir)
-      }
-      // Orthographic: every ray runs along the camera's forward axis; the
-      // pixel picks where on the camera plane it starts (top row = top).
-      let cx = o.left + (x / width) * (o.right - o.left)
-      let cy = o.top + (y / height) * (o.bottom - o.top)
-      pickOrigin[0] = camera.eye[0] + cx * v[0] + cy * v[1]
-      pickOrigin[1] = camera.eye[1] + cx * v[4] + cy * v[5]
-      pickOrigin[2] = camera.eye[2] + cx * v[8] + cy * v[9]
-      pickDir[0] = -v[2]
-      pickDir[1] = -v[6]
-      pickDir[2] = -v[10]
+      pixelRay(x, y)
       return scene.raycast(pickOrigin, pickDir)
     },
-    raycast(origin, direction) {
+    unproject(x, y, w, out = [0, 0, 0]) {
+      pixelRay(x, y)
+      out[0] = pickOrigin[0] + w * pickDir[0]
+      out[1] = pickOrigin[1] + w * pickDir[1]
+      out[2] = pickOrigin[2] + w * pickDir[2]
+      return out
+    },
+    screenRay(x, y) {
+      pixelRay(x, y)
+      return {
+        origin: [pickOrigin[0], pickOrigin[1], pickOrigin[2]],
+        direction: [pickDir[0], pickDir[1], pickDir[2]],
+      }
+    },
+    raycast(origin, direction, rayOpts) {
       // Flush pending writes: picking sees the tree as the app just wrote
       // it, the same immediacy contract as lookAt()/project(). (The queued
       // microtask still runs and finds nothing dirty - harmless.)
       if (scheduled) sync()
       if (disposed) return []
+      let admit = admitted(rayOpts, "raycast")
       let hits: Hit[] = []
       rayOriginScratch[0] = origin[0]
       rayOriginScratch[1] = origin[1]
@@ -2273,20 +1839,51 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       rayDirScratch[1] = direction[1]
       rayDirScratch[2] = direction[2]
       for (let h of spatial.raycast(rayOriginScratch, rayDirScratch)) {
-        let mesh = byNode.get(h.node)
-        if (mesh === undefined) continue
-        let hit: Hit = { mesh, distance: h.distance, point: h.point }
-        if (h.normal !== undefined) hit.normal = h.normal
+        let leaf = admit(h.node)
+        if (leaf === null) continue
+        let hit: Hit = { mesh: leaf.mesh, distance: h.distance, point: h.point, normal: h.normal }
+        if (leaf.instance !== null) hit.instance = leaf.instance
         if (h.face !== undefined) hit.face = h.face
         if (h.uv !== undefined) hit.uv = h.uv
         hits.push(hit)
       }
       return hits
     },
-    handlers,
-    handlersFor(layout) {
-      return makeHandlers(layout)
+    overlap(volume, qopts) {
+      if (scheduled) sync()
+      if (disposed) return []
+      let admit = admitted(qopts, "overlap")
+      let kind = packVolume(volume, "overlap")
+      let out: Overlap[] = []
+      for (let h of spatial.overlap(kind, kind === "box" ? boxScratch : capsuleScratch)) {
+        let leaf = admit(h.node)
+        if (leaf === null) continue
+        let contact: Overlap = { mesh: leaf.mesh, point: h.point, normal: h.normal, depth: h.depth }
+        if (leaf.instance !== null) contact.instance = leaf.instance
+        out.push(contact)
+      }
+      return out
+    },
+    sweep(volume, motion, qopts) {
+      if (scheduled) sync()
+      if (disposed) return []
+      let admit = admitted(qopts, "sweep")
+      let kind = packVolume(volume, "sweep")
+      motionScratch[0] = motion[0]
+      motionScratch[1] = motion[1]
+      motionScratch[2] = motion[2]
+      let out: Impact[] = []
+      for (let h of spatial.sweep(kind, kind === "box" ? boxScratch : capsuleScratch, motionScratch)) {
+        let leaf = admit(h.node)
+        if (leaf === null) continue
+        let impact: Impact = { mesh: leaf.mesh, time: h.time, point: h.point, normal: h.normal }
+        if (leaf.instance !== null) impact.instance = leaf.instance
+        out.push(impact)
+      }
+      return out
     },
+    handlers: pointer.handlers,
+    handlersFor: pointer.handlersFor,
     createView(vopts) {
       if (disposed) throw new Error("createView: the scene is disposed")
       let v = makeView(vopts, null)
@@ -2297,6 +1894,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
           updateCamera(v.camera, update)
           hooks._schedule()
         },
+        camera: () => cameraState(v.camera),
         setSize(w, h) {
           if (v.disposed || (w === v.width && h === v.height)) return
           v.width = w
@@ -2315,13 +1913,40 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
           hooks._schedule()
         },
         setParams(params) {
-          if (!v.disposed) setTargetParams(v.texture, params)
+          if (v.disposed) return
+          for (let k of Object.keys(params)) v.ownNames.add(k)
+          setTargetParams(v.texture, params)
+        },
+        setLayers(mask) {
+          checkMask(mask, "view.setLayers")
+          if (v.disposed || v.mask === mask) return
+          v.mask = mask
+          for (let mesh of meshes) {
+            if ((mesh.layers & mask) !== 0) attachView(v, mesh)
+            else detachView(v, mesh)
+          }
+          hooks._schedule()
         },
         dispose() {
           disposeView(v)
         },
       }
     },
+    createReflectionProbe(popts) {
+      if (disposed) throw new Error("createReflectionProbe: the scene is disposed")
+      let { cube, setPosition, update, dispose } = makeProbe(popts, checkMask(popts.layers ?? 1, "createReflectionProbe"))
+      return { cube, setPosition, update, dispose }
+    },
+    bakeBackground(size = PROBE_SIZE) {
+      if (disposed) throw new Error("bakeBackground: the scene is disposed")
+      if (background === null) throw new Error("scene.bakeBackground: the scene has no background to bake")
+      if (!Number.isInteger(size) || size < 1) throw new Error("scene.bakeBackground: size must be a positive integer, got " + size)
+      // A probe that sees no mesh (mask 0) draws the background alone: the
+      // same face cameras, linear output and prefilter as any probe.
+      let probe = makeProbe({ position: [0, 0, 0], size, label: (opts?.label ?? "scene") + "-sky" }, 0)
+      probe.update()
+      return probe.finish()
+    },
     dispose() {
       if (disposed) return
       disposed = true
@@ -2335,32 +1960,92 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         spatial.destroyNode(root._node)
         root._node = null
       }
+      spatial.setFrustum(texture, null)
       // Drain the zeroed direction slots the teardown queued while the
       // targets still exist; afterwards their groups are gone.
       spatial.flush()
       destroyTexture(texture)
-      shadows.clear()
       for (let v of views.slice()) disposeView(v)
-      if (shadowAtlas !== null) {
-        destroyTexture(shadowAtlas.texture)
-        shadowAtlas = null
-      }
+      shadowSys.dispose()
+      destroyTexture(envPlaceholder)
       if (background !== null) {
-        // The entry died with the target; the pipeline and program are the
-        // scene's own (unlike shared material pipelines), so they go too.
+        // The entries died with the targets; the pipeline and program are
+        // the scene's own (unlike shared material pipelines), so they go too.
         destroyRenderPipeline(background.pipeline)
         destroyProgram(background.program)
         background = null
       }
     },
   }
+  // A reflection probe over layer mask `mask` (see createReflectionProbe):
+  // the public object plus `finish`, which keeps the prefiltered chain and
+  // drops everything else - the bake's one-shot use.
+  let makeProbe = (popts: ReflectionProbeOptions, mask: number): ReflectionProbe & { finish(): TextureId } => {
+      let size = popts.size ?? PROBE_SIZE
+      if (!Number.isInteger(size) || size < 1) throw new Error("createReflectionProbe: size must be a positive integer, got " + size)
+      let prefilter = popts.prefilter !== false
+      let v = makeView(
+        { width: size, height: size, layers: mask, clearColor: popts.clearColor, label: popts.label },
+        null,
+        size,
+        prefilter,
+        true,
+      )
+      v.camera.mirror = true
+      updateCamera(v.camera, { fov: PROBE_FOV, near: popts.near, far: popts.far })
+      // The faces hold LINEAR radiance, untouched by the scene's output
+      // stage: no sRGB encode, no tone mapping, unit exposure - the
+      // probe's own names, so the scene's fan-out leaves them alone.
+      for (let k of Object.keys(LINEAR_OUTPUT)) v.ownNames.add(k)
+      setTargetParams(v.texture, LINEAR_OUTPUT)
+      let chain = prefilter ? createPrefilter(size, v.texture, probeFormat(), (popts.label ?? (opts?.label ?? "scene") + "-probe") + "-chain") : null
+      v.probeCube = chain?.cube ?? v.texture
+      let position: Vec3 = [popts.position[0], popts.position[1], popts.position[2]]
+      return {
+        cube: v.probeCube,
+        setPosition(p) {
+          position = [p[0], p[1], p[2]]
+        },
+        update() {
+          if (v.disposed) return
+          // The scene's pending state (lights, params, the fan-out to this
+          // target) lands before the faces read it.
+          sync()
+          renderCubeFaces(v.texture, v.camera, size, position, chain !== null, face => {
+            // Opaque order is a hint (front to back); only transparency
+            // needs the per-face sort.
+            if (face === 0 || transparentCount > 1) sortView(v)
+          })
+          chain?.run()
+        },
+        dispose() {
+          chain?.dispose()
+          disposeView(v)
+        },
+        finish() {
+          if (chain === null) throw new Error("finish: a sharp probe has no chain to keep")
+          let cube = chain.finish()
+          disposeView(v)
+          return cube
+        },
+      }
+  }
   // The fog set starts at "none" (uFogInv and uFogDensity 0 are factor 0,
   // uFogHeightFalloff 0 is no attenuation) so every material that declares
   // it has coverage from the first frame; a target tolerates the names
   // when nothing declares them.
   scene.setParams({ uFogColor: [0, 0, 0], uFogNear: 0, uFogInv: 0, uFogDensity: 0, uFogHeight: 0, uFogHeightFalloff: 0 })
+  // Likewise the environment set starts at "none" (uEnvOn 0), so a
+  // reflective material has coverage before setEnvironment.
+  scene.setParams(environmentParams(null))
+  // And the output stage at its defaults (exposure 1, no tone mapping),
+  // which every library fragment declares.
+  scene.setParams({ uExposure: 1, uToneMapping: TONE_MAPPING_CODE.none, uOutputEncode: 1 })
   if (opts?.fog !== undefined) scene.setFog(opts.fog)
+  if (opts?.toneMapping !== undefined) scene.setToneMapping(opts.toneMapping)
+  if (opts?.exposure !== undefined) scene.setExposure(opts.exposure)
   if (opts?.background !== undefined) scene.setBackground(opts.background)
+  if (opts?.environment !== undefined) scene.setEnvironment(opts.environment)
   if (opts?.autoFree !== false && getOwner()) onCleanup(() => scene.dispose())
   return scene
-}
+}