@solidrt/3d 0.0.50 → 0.0.52

package/src/scene.ts

@@ -1,8 +1,12 @@
-// The retained scene: plain objects and dirty flags, no signals - the hot
-// path (a moved node) is flat imperative code, and reactivity stays at the
-// component boundary (components.tsx). A scene compiles to one draw
-// target: every mesh is one draw entry whose uModel (and, for materials
-// declaring it, uNormal) this module keeps in step with the tree, and the
+// The retained scene: plain objects, no signals - the hot path (a moved
+// node) is flat imperative code, and reactivity stays at the component
+// boundary (components.tsx). The transform hierarchy itself lives in the
+// spatial core (flux:spatial): every node in a scene has a core node, JS
+// keeps the LOCAL transform as the readable source of truth and forwards
+// each write, and the core's flush recomputes only the moved subtrees and
+// writes each mesh entry's uModel (and, for materials declaring it,
+// uNormal) - so a move costs its subtree, never the scene. A scene
+// compiles to one draw target: every mesh is one draw entry, and the
 // camera is the target's SHARED uViewProj + uCamPos + uCamRight/uCamUp -
 // one setTargetParams per camera move, not one write per mesh. The
 // non-matrix names ride unconditionally: shared params tolerate zero
@@ -16,47 +20,81 @@
 // `render: "auto"` draw target that re-renders when its entries change, so
 // a static scene costs zero passes and this module registers no frame
 // loop. Continuous animation is the app's onFrame writing transforms -
-// each write lands here, the microtask syncs the affected uModels, and the
-// flush renders once that frame.
+// each write lands in the core, the microtask flushes it, and the frame
+// renders once.
+//
+// Still in JS this stage (see okf/backlog/spatial-core.md): the picking
+// 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, createDrawTarget, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, setDrawOrder, setDrawParams, setDrawRange, setTargetParams, setTargetSize } from "@solidrt/core/gpu"
-import type { DrawId, FilterMode, ProgramId, RenderPipelineId, ShaderParams, TextureId, WrapMode } from "@solidrt/core/gpu"
+import { addDraw, createBuffer, createDrawTarget, createTexture, depthTexture, destroyBuffer, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, setDrawBuffers, setDrawOrder, setDrawParams, setTargetParams, setTargetSize, setTargetTextures, writeBuffer } 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 { 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 { compose, copy, eulerFromQuat, identity, invertAffine, lookAt as lookAtMatrix, mat4, multiply, normalMatrix, perspective, quat, quatFromEuler, quatFromFrame, quatNormalize, transformPoint, transformVector } from "./math.ts"
-import type { Mat4, Quat, Vec3, Vec4 } from "./math.ts"
-import { geometryBounds, geometryBuffers } from "./geometry.ts"
+import { compose, copy, eulerFromQuat, identity, lookAt as lookAtMatrix, mat4, multiply, orthographic, perspective, quat, quatFromFrame, transformPoint, transformVector, updateRotation, updateScale } from "./math.ts"
+import type { Mat4, Quat, TransformUpdate, Vec3, Vec4 } from "./math.ts"
+import { MAX_LIGHTS } 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 type { Geometry } from "./geometry.ts"
-import { backgroundPipeline } from "./material.ts"
+import { backgroundPipeline, missingAttributes, shadowDepthMaterial } from "./material.ts"
 import { orderEntries } from "./order.ts"
 import type { Material } from "./material.ts"
-import { createBvh, rayBoxDistance } from "./bvh.ts"
 
 const IDENTITY = mat4()
 const RESOLVED = Promise.resolve()
 // 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]
-// Param values are snapshotted at the FFI boundary (addDraw shares
-// IDENTITY the same way), so one scratch serves every uNormal write.
-let normalScratch = mat4()
-// lookAt()/worldPosition() scratch: the ancestor walk recomputes worlds
-// without touching node state, so nothing here outlives a single call.
+// 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()
+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 declare(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)
+    }
+  })
+}
 let aimScratch: Vec3 = [0, 0, 0]
 let upScratch: Vec3 = [0, 0, 0]
-// Picking narrowphase scratch: one candidate is tested at a time, so one
-// set serves every raycast.
-let pickInv = mat4()
-let pickOrigin: Vec4 = [0, 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
@@ -67,12 +105,24 @@ 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"
+  kind: "group" | "mesh" | "light"
   parent: SceneNode | null
   children: SceneNode[]
   /** Read freely; write through setTransform/setVisible so changes sync. */
@@ -94,12 +144,70 @@ export type SceneNode = {
   onPointerUp?: (event: ScenePointerEvent) => void
   onPointerEnter?: (event: ScenePointerEvent) => void
   onPointerLeave?: (event: ScenePointerEvent) => void
-  _localDirty: boolean
-  _local: Mat4
-  _world: Mat4
+  /** 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. */
+  camera?: Partial<ShadowCamera>
+}
+
+/** 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 }
+}
+
+/** 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
@@ -108,27 +216,77 @@ export type Mesh = SceneNode & {
    * 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 geometry bounds, kept by the sync walk
-   * beside the picking leaf: the transparent sort key. */
+  /** World-space center of the local bounds, refreshed at sort time: the
+   * transparent sort key. */
   _center: Vec3
-  _hidden: boolean
-  _fresh: boolean
   _params: ShaderParams | null
-  _pickLeaf: number | 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
 }
 
-/** One picking intersection: the mesh, the camera-ray distance in world
- * units, and the world-space point - Three's intersect result minus the
- * triangle fields (`face`, `uv`), which cannot exist at the volume tier. */
+/** 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 }
+
+/** 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. */
 export type Hit = {
   mesh: Mesh
   distance: number
   point: Vec3
+  normal?: Vec3
+  face?: number
+  uv?: [number, number]
+}
+
+/** The settled component of a node transition. */
+export type TransitionEndEvent = {
+  component: "position" | "rotation" | "scale"
 }
 
 /**
@@ -172,6 +330,10 @@ 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
@@ -180,6 +342,11 @@ export type CameraUpdate = {
   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
 }
 
 export type SceneOptions = {
@@ -192,6 +359,49 @@ export type SceneOptions = {
   autoFree?: boolean
   filter?: FilterMode
   wrap?: WrapMode
+  /** Multisample count of the target (1, 2, 4 or 8; default 1). Storage-only
+   * anti-aliasing of mesh edges; see createDrawTarget. */
+  samples?: 1 | 2 | 4 | 8
+}
+
+export type ViewOptions = {
+  width: number
+  height: number
+  /**
+   * Every mesh draws with this material instead of its own (Three's
+   * `scene.overrideMaterial`, scoped to the view): a depth pass, a normal
+   * or id visualizer. The view then carries none of the meshes' own
+   * bindings or params, and instanced meshes are skipped (the override's
+   * vertex stage cannot know their record layout). An overridden view
+   * draws in add order (no renderOrder or transparent sort).
+   */
+  overrideMaterial?: Material
+  /** The view target's depth storage: true (default) for a buffer,
+   * "texture" for a sampleable one exposed as `view.depthTexture`. */
+  depth?: true | "texture"
+  clearColor?: [number, number, number, number]
+  samples?: 1 | 2 | 4 | 8
+  filter?: FilterMode
+  wrap?: WrapMode
+  label?: string
+}
+
+/** A second rendering of a scene from its own camera; see Scene.createView. */
+export type View = {
+  /** The view's output, an ordinary texture id. */
+  texture: TextureId
+  /** The view target's depth as a sampler-only texture id when created
+   * with `depth: "texture"` (the shadow-map input), else null. */
+  depthTexture: TextureId | null
+  /** Partial camera update, exactly scene.setCamera. */
+  setCamera(update: CameraUpdate): void
+  setSize(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). */
+  setParams(params: ShaderParams): void
+  /** Destroy the view's target (its entries die with it). Idempotent;
+   * views also die with their scene. */
+  dispose(): void
 }
 
 export type Scene = {
@@ -266,7 +476,7 @@ export type Scene = {
    *
    * Coordinates assume the leaf is LAID OUT at the target size - true for
    * the built-in leaf and a d-texture at natural size, under any ancestor
-   * transforms or viewBox fits (the hit test undoes them). A leaf laid out
+   * transforms or design-size fits (the hit test undoes them). A leaf laid out
    * at a different size needs handlersFor instead.
    */
   handlers: SceneHandlers
@@ -276,13 +486,135 @@ export type Scene = {
    * layout just works: `scene.handlersFor(() => ({ width: w(), height:
    * h() }))`. */
   handlersFor(layout: () => { width: number; height: number }): SceneHandlers
-  /** Destroy the target (entries die with it). Idempotent. Geometry
-   * buffers and material pipelines are shared and survive - they are
-   * app-lifetime (see geometry.ts / material.ts). */
+  /**
+   * A second rendering of this scene: its own draw target and camera,
+   * the same meshes and lights. Each mesh gets one entry in the view's
+   * target, bound as one more draw sink of the mesh's core node, so a
+   * move feeds every target from the one flush and the app writes
+   * 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.
+   */
+  createView(opts: ViewOptions): View
+  /** 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
+   * entry (see geometry-gpu.ts). */
   dispose(): void
 }
 
-function makeNode(kind: "group" | "mesh"): SceneNode {
+// 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
+// strict entry path. Extra channels are fine.
+function checkLayout(material: Material, geometry: Geometry, what: string): void {
+  let missing = missingAttributes(material, geometry.layout)
+  if (missing.length > 0) {
+    throw new Error(
+      what + " reads attributes the geometry layout (" + layoutKey(geometry.layout) + ") lacks: " +
+        missing.map(a => a.name + " " + a.format).join(", ") +
+        " - add the channel with withAttribute()/withColors(), or use a material that does not read it",
+    )
+  }
+}
+
+// An entry's initial params. The uNormal seed keys off the material flag
+// because entry params validate strictly - and a material declaring
+// uNormal without using it therefore throws right here, at add().
+function entrySeed(material: Material, params: ShaderParams | null): ShaderParams {
+  return material.normalMatrix
+    ? { uModel: IDENTITY, uNormal: IDENTITY, ...material.params, ...params }
+    : { uModel: IDENTITY, ...material.params, ...params }
+}
+
+// The uShadowMap<i> binding of a light slot that does not cast: 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,
@@ -291,10 +623,10 @@ function makeNode(kind: "group" | "mesh"): SceneNode {
     quaternion: [0, 0, 0, 1],
     scale: [1, 1, 1],
     visible: true,
-    _localDirty: true,
-    _local: mat4(),
-    _world: mat4(),
+    _node: null,
+    _moved: false,
     _scene: null,
+    _transition: null,
   }
 }
 
@@ -302,27 +634,255 @@ 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: shadow slot i is light i's, so the
+ * cap is MAX_LIGHTS (each map is a sampler unit and a full extra pass). */
+export const MAX_SHADOWS = MAX_LIGHTS
+
+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)
+}
+
+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 } }
+  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._hidden = false
-  mesh._fresh = false
   mesh._params = null
-  mesh._pickLeaf = 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)
-  child._localDirty = true
   if (parent._scene) enterScene(child, parent._scene)
 }
 
@@ -339,8 +899,16 @@ export function remove(child: SceneNode): void {
 
 function enterScene(node: SceneNode, scene: SceneHooks): void {
   node._scene = scene
-  node._localDirty = true
+  node._node = spatial.createNode(fillTransform(node), node.visible)
+  if (node._transition !== null) {
+    spatial.setTransition(node._node, node._transition)
+    declare(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()
 }
@@ -348,21 +916,58 @@ function enterScene(node: SceneNode, scene: SceneHooks): void {
 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
+  }
 }
 
-export type TransformUpdate = {
-  position?: Vec3
-  /** Euler radians in XYZ order (x first), Three's `Euler` default -
-   * converted to the node's quaternion on write. */
-  rotation?: Vec3
-  /** The rotation itself. Normalized on write, so a hand-built or
-   * drifted quaternion cannot silently scale the geometry. Passing this
-   * together with `rotation` is an error, not a precedence question. */
-  quaternion?: Quat
-  /** A number is uniform scale. */
-  scale?: Vec3 | number
+/** 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 declare(node._node, node)
+  }
 }
 
 /**
@@ -377,11 +982,6 @@ export type TransformUpdate = {
  * equal to the node's current quaternion is also a no-op.
  */
 export function setTransform(node: SceneNode, update: TransformUpdate): void {
-  let r = update.rotation
-  let q = update.quaternion
-  if (r !== undefined && q !== undefined) {
-    throw new Error("Pass rotation or quaternion to setTransform, not both")
-  }
   // 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
@@ -394,9 +994,7 @@ export function setTransform(node: SceneNode, update: TransformUpdate): void {
     node.position[2] = p[2]
     changed = true
   }
-  if (r !== undefined) quatFromEuler(rotScratch, r)
-  else if (q !== undefined) quatNormalize(rotScratch, q)
-  if (r !== undefined || q !== undefined) {
+  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]
@@ -406,21 +1004,17 @@ export function setTransform(node: SceneNode, update: TransformUpdate): void {
       changed = true
     }
   }
-  let s = update.scale
-  if (s !== undefined) {
-    let sx = typeof s === "number" ? s : s[0]
-    let sy = typeof s === "number" ? s : s[1]
-    let sz = typeof s === "number" ? s : s[2]
-    if (sx !== node.scale[0] || sy !== node.scale[1] || sz !== node.scale[2]) {
-      node.scale[0] = sx
-      node.scale[1] = sy
-      node.scale[2] = sz
+  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
-  node._localDirty = true
-  node._scene?._schedule()
+  pushTransform(node)
 }
 
 /**
@@ -467,8 +1061,7 @@ export function lookAt(node: SceneNode, target: Vec3, up: Vec3 = WORLD_UP): void
     unrotate(upScratch, world, up)
     quatFromFrame(node.quaternion, aimScratch, upScratch)
   }
-  node._localDirty = true
-  node._scene?._schedule()
+  pushTransform(node)
 }
 
 /**
@@ -497,18 +1090,22 @@ export function worldPosition(node: SceneNode, out: Vec3 = [0, 0, 0]): Vec3 {
 }
 
 /**
- * `out` = node's world matrix, composing any dirty locals up the chain
- * WITHOUT clearing their flags: the pending sync still has to see them to
- * write uModel. One shared local scratch serves any depth - each frame
- * uses it only after its recursive call has returned.
+ * `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)
-  let local = node._localDirty
-    ? compose(localScratch, node.position, node.quaternion, node.scale)
-    : node._local
-  return multiply(out, out, local)
+  return multiply(out, out, compose(localScratch, node.position, node.quaternion, node.scale))
 }
 
 /**
@@ -531,7 +1128,10 @@ function unrotate(out: Vec3, m: Mat4, v: Vec3): Vec3 {
 export function setVisible(node: SceneNode, visible: boolean): void {
   if (node.visible === visible) return
   node.visible = visible
-  node._scene?._schedule()
+  if (node._node !== null) {
+    spatial.setVisible(node._node, visible)
+    node._scene?._schedule()
+  }
 }
 
 /** Set a mesh's explicit draw-order key (see Mesh.renderOrder). */
@@ -541,9 +1141,17 @@ export function setRenderOrder(mesh: Mesh, order: number): void {
   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)
@@ -591,16 +1199,21 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     clearColor: opts?.clearColor,
     filter: opts?.filter,
     wrap: opts?.wrap,
+    samples: opts?.samples,
     label: opts?.label ?? "scene",
     autoFree: false,
   })
   let disposed = false
   let scheduled = false
 
-  // Picking state: the broadphase tree over world boxes, kept current by
-  // the sync walk (the meshes it touches are exactly the leaves to move),
-  // and the pointer bookkeeping behind scene.handlers.
-  let bvh = createBvh<Mesh>()
+  // 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>()
+  // 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>()
 
@@ -611,6 +1224,85 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   // meshes exist - fewer cannot change relative order.
   let meshes: Mesh[] = []
   let transparentCount = 0
+  // Attached lights in attach order (= light index); any change to the
+  // set, a light's fields, or a light's world matrix rewrites the shared
+  // 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.
+  // 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.
+  let vecScratch = new Float32Array(3)
+  let writeLights = () => {
+    lightsDirty = false
+    let sky: Vec3 = [0, 0, 0]
+    let ground: Vec3 = [0, 0, 0]
+    let colors: 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]
+        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
+      let k = light.intensity
+      colors.push(c[0] * k, c[1] * k, c[2] * k)
+      count++
+    }
+    for (let i = count; i < MAX_LIGHTS; i++) colors.push(0, 0, 0)
+    // The shadow set rides with the lights, slot i = directional light i:
+    // whether it casts (0 = a receiving material draws that light plain),
+    // its biases, and its map bound as uShadowMap<i> - the light's depth
+    // id when it casts, else the white placeholder, so every receiving
+    // target always has all MAX_LIGHTS samplers bound.
+    let cast: number[] = []
+    let bias: number[] = []
+    let normalBias: number[] = []
+    let maps: Record<string, TextureId> = {}
+    let i = 0
+    for (let light of lights) {
+      if (light.type !== "directional") continue
+      let shadow = shadows.get(light)
+      cast.push(shadow !== undefined ? 1 : 0)
+      bias.push(light.shadow.bias)
+      normalBias.push(light.shadow.normalBias)
+      maps["uShadowMap" + i] = shadow !== undefined ? depthTexture(shadow.view.texture) : shadowPlaceholder()
+      i++
+    }
+    for (; i < MAX_LIGHTS; i++) {
+      cast.push(0)
+      bias.push(0)
+      normalBias.push(0)
+      maps["uShadowMap" + i] = shadowPlaceholder()
+    }
+    let params: ShaderParams = {
+      uHemiSky: sky,
+      uHemiGround: ground,
+      uLightCount: count,
+      uLightColor: colors,
+      uShadowCast: cast,
+      uShadowBias: bias,
+      uShadowNormalBias: normalBias,
+    }
+    receivingTargets(t => {
+      setTargetParams(t, params)
+      setTargetTextures(t, maps)
+    })
+    // A slot change (a light attached, detached or reordered) moves every
+    // matrix too: rewrite the whole array once.
+    shadowMatricesDirty = true
+  }
   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.
@@ -618,130 +1310,272 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   let background: { entry: DrawId; pipeline: RenderPipelineId; program: ProgramId } | null = null
   let sortEntries = () => {
     orderDirty = false
-    let order = orderEntries(meshes, view, background?.entry)
+    let order = orderEntries(meshes, camera.view, background?.entry)
     if (order.length === lastOrder.length && order.every((id, i) => id === lastOrder[i])) return
     lastOrder = order
     setDrawOrder(texture, order)
   }
 
-  // Reinsert or refit a mesh's broadphase leaf from its fresh world matrix:
-  // the local box's center/extents carried through the absolute matrix (the
-  // standard tight-AABB-of-a-transformed-AABB construction).
-  let updateLeaf = (mesh: Mesh): void => {
-    let b = geometryBounds(mesh.geometry)
-    let m = mesh._world
-    let cx = (b[0]! + b[3]!) / 2
-    let cy = (b[1]! + b[4]!) / 2
-    let cz = (b[2]! + b[5]!) / 2
-    let ex = (b[3]! - b[0]!) / 2
-    let ey = (b[4]! - b[1]!) / 2
-    let ez = (b[5]! - b[2]!) / 2
-    let wx = m[0] * cx + m[4] * cy + m[8] * cz + m[12]
-    let wy = m[1] * cx + m[5] * cy + m[9] * cz + m[13]
-    let wz = m[2] * cx + m[6] * cy + m[10] * cz + m[14]
-    mesh._center[0] = wx
-    mesh._center[1] = wy
-    mesh._center[2] = wz
-    let rx = Math.abs(m[0]) * ex + Math.abs(m[4]) * ey + Math.abs(m[8]) * ez
-    let ry = Math.abs(m[1]) * ex + Math.abs(m[5]) * ey + Math.abs(m[9]) * ez
-    let rz = Math.abs(m[2]) * ex + Math.abs(m[6]) * ey + Math.abs(m[10]) * ez
-    if (mesh._pickLeaf === null) {
-      mesh._pickLeaf = bvh.insert(mesh, wx - rx, wy - ry, wz - rz, wx + rx, wy + ry, wz + rz)
-    } else {
-      bvh.update(mesh._pickLeaf, wx - rx, wy - ry, wz - rz, wx + rx, wy + ry, wz + rz)
+  // The transparent sort keys: each transparent mesh's local-bounds
+  // center carried through its world matrix (read from the core), at
+  // sort time only - opaque meshes never need one.
+  let refreshCenters = () => {
+    if (transparentCount < 2) return
+    for (let mesh of meshes) {
+      if (!mesh._transparent || mesh._node === null) continue
+      let b = localBounds(mesh)
+      let m = worldInto(worldScratch, mesh)
+      let cx = 0, cy = 0, cz = 0
+      if (b !== null) {
+        cx = (b[0]! + b[3]!) / 2
+        cy = (b[1]! + b[4]!) / 2
+        cz = (b[2]! + b[5]!) / 2
+      }
+      mesh._center[0] = m[0] * cx + m[4] * cy + m[8] * cz + m[12]
+      mesh._center[1] = m[1] * cx + m[5] * cy + m[9] * cz + m[13]
+      mesh._center[2] = m[2] * cx + m[6] * cy + m[10] * cz + m[14]
     }
   }
-
-  let fov = 60
-  let near = 0.1
-  let far = 100
-  let eye: Vec3 = [0, 0, 3]
-  let target: Vec3 = [0, 0, 0]
-  let up: Vec3 = [0, 1, 0]
-  let cameraDirty = true
-  let cameraPending = false
-  let proj = mat4()
-  let view = mat4()
-  let viewProj = mat4()
+  let camera = makeCamera()
   let clip: Vec4 = [0, 0, 0, 0]
+  let pickOrigin: Vec3 = [0, 0, 0]
 
-  // Matrix recompute, split from sync so project()/viewProj() see a fresh
-  // matrix right after setCamera, before the microtask runs. cameraPending
-  // keeps the GPU write owed to the next sync.
-  let ensureCamera = () => {
-    if (!cameraDirty) return
-    cameraDirty = false
-    cameraPending = true
-    perspective(proj, (fov * Math.PI) / 180, width / height, near, far)
-    lookAtMatrix(view, eye, target, up)
-    multiply(viewProj, proj, view)
+  // 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
+  // that writes the scene's entry writes the view's too. Sorted like the
+  // scene (view-space keys from the view's own camera); an overridden
+  // view is not sorted at all.
+  type ViewRecord = {
+    texture: TextureId
+    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
+    camera: Camera
+    entries: Map<Mesh, DrawId>
+    orderDirty: boolean
+    lastOrder: DrawId[]
+    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 view
+  // rendering its map (depth texture, depth override, casting meshes
+  // only). `lastWorld` is the light's world matrix the shadow camera was
+  // last placed from; `dirty` forces a re-place (options changed).
+  type Shadow = { light: DirectionalLight; view: ViewRecord; lastWorld: Mat4; dirty: boolean }
+  let shadows = new Map<DirectionalLight, Shadow>()
+  let shadowDir: Vec3 = [0, 0, 0]
+  // uShadowMatrix is one array param (the engine writes whole arrays), so
+  // any shadow camera move rewrites all MAX_LIGHTS matrices, identity in
+  // the slots that do not cast.
+  let shadowMatrices: number[] = new Array(MAX_LIGHTS * 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)
+  }
+  let attachView = (v: ViewRecord, mesh: Mesh) => {
+    let inst = mesh._instances
+    if (v.override !== null && inst !== null) return
+    if (v.filter !== null && !v.filter(mesh)) return
+    let material = v.override ?? mesh.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,
+      instanceCount: 0,
+    })
+    spatial.bindDraw(mesh._node!, v.texture, entry, material.normalMatrix === true, inst !== null ? inst.count : 1)
+    v.entries.set(mesh, entry)
+    v.orderDirty = true
+  }
+  let detachView = (v: ViewRecord, mesh: Mesh) => {
+    let entry = v.entries.get(mesh)
+    if (entry === undefined) return
+    v.entries.delete(mesh)
+    if (mesh._node !== null) spatial.unbindDraw(mesh._node, v.texture)
+    if (!v.disposed) removeDraw(v.texture, entry)
+    v.orderDirty = true
+  }
+  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)
+    if (order.length === v.lastOrder.length && order.every((id, i) => id === v.lastOrder[i])) return
+    v.lastOrder = order
+    setDrawOrder(v.texture, order)
+  }
+  let disposeView = (v: ViewRecord) => {
+    if (v.disposed) return
+    v.disposed = true
+    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)
+    // 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)
+  }
+  // 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 override = vopts.overrideMaterial ?? null
+    if (override !== null) {
+      for (let mesh of meshes) if (mesh._instances === null) checkLayout(override, mesh.geometry, "View override material")
+    }
+    let v: ViewRecord = {
+      texture: createDrawTarget(vopts.width, vopts.height, null, {
+        depth: vopts.depth ?? true,
+        clearColor: vopts.clearColor,
+        filter: vopts.filter,
+        wrap: vopts.wrap,
+        samples: vopts.samples,
+        label: vopts.label ?? (opts?.label ?? "scene") + "-view",
+        autoFree: false,
+      }),
+      width: vopts.width,
+      height: vopts.height,
+      override,
+      filter,
+      camera: makeCamera(),
+      entries: new Map(),
+      orderDirty: true,
+      lastOrder: [],
+      disposed: false,
+    }
+    views.push(v)
+    // The light rewrite seeds the shadow set (maps, casts, biases,
+    // matrices) on the new target too.
+    lightsDirty = true
+    setTargetParams(v.texture, sceneParams)
+    for (let mesh of meshes) attachView(v, mesh)
+    hooks._schedule()
+    return v
+  }
+  // A shadow view: a square depth-texture target drawing the casting
+  // meshes with the depth override from the light's frustum. The light
+  // rewrite binds its map in the light's slot on every receiving target.
+  let createShadow = (light: DirectionalLight) => {
+    let size = light.shadow.mapSize
+    let view = makeView(
+      {
+        width: size,
+        height: size,
+        depth: "texture",
+        overrideMaterial: shadowDepthMaterial(),
+        clearColor: [1, 1, 1, 1],
+        label: (opts?.label ?? "scene") + "-shadow",
+      },
+      m => m.castShadow,
+    )
+    shadows.set(light, { light, view, lastWorld: mat4(), dirty: true })
+    lightsDirty = true
+  }
+  let destroyShadow = (light: DirectionalLight) => {
+    let shadow = shadows.get(light)
+    if (shadow === undefined) return
+    shadows.delete(light)
+    disposeView(shadow.view)
+    lightsDirty = true
+    hooks._schedule()
+  }
+  // Place a shadow camera from its light's world matrix: 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.
+  let placeShadowCamera = (shadow: Shadow) => {
+    let light = shadow.light
+    let m = worldInto(worldScratch, light)
+    if (!shadow.dirty && 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]
+    let c = light.shadow.camera
+    updateCamera(shadow.view.camera, {
+      position: [m[12], m[13], m[14]],
+      target: [m[12] + d[0], m[13] + d[1], m[14] + d[2]],
+      // 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).
+      up: Math.abs(d[1]) > 0.99 ? [0, 0, 1] : [0, 1, 0],
+      ortho: { left: c.left, right: c.right, top: c.top, bottom: c.bottom },
+      near: c.near,
+      far: c.far,
+    })
   }
 
   let sync = () => {
     scheduled = false
     if (disposed) return
-    ensureCamera()
-    if (cameraPending) {
-      // The camera is target state: one shared write, whatever the scene
-      // holds. Entries are untouched - uModel is camera-independent, and
-      // uCamPos is stored even when no current material declares it.
-      cameraPending = false
-      // 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.
-      setTargetParams(texture, {
-        uViewProj: viewProj,
-        uCamPos: eye,
-        uCamRight: [view[0], view[4], view[8]],
-        uCamUp: [view[1], view[5], view[9]],
-      })
+    ensureCamera(camera, width, height)
+    if (camera.pending) {
+      camera.pending = false
+      setTargetParams(texture, cameraParams(camera))
       if (transparentCount > 1) orderDirty = true
     }
-    let walk = (node: SceneNode, parentChanged: boolean, parentVisible: boolean) => {
-      let changed = parentChanged
-      if (node._localDirty) {
-        compose(node._local, node.position, node.quaternion, node.scale)
-        node._localDirty = false
-        changed = true
+    for (let shadow of shadows.values()) placeShadowCamera(shadow)
+    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))
+        if (transparentCount > 1) v.orderDirty = true
+        if (v.filter !== null) shadowMatricesDirty = true
       }
-      if (changed) {
-        multiply(node._world, node.parent ? node.parent._world : IDENTITY, node._local)
+    }
+    // Light bookkeeping first, so a fresh direction-slot bind is seeded
+    // by the flush below in the same sync.
+    if (lightsDirty) writeLights()
+    // 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 i = 0
+      for (let light of lights) {
+        if (light.type !== "directional") continue
+        let shadow = shadows.get(light)
+        let m = shadow !== undefined ? shadow.view.camera.viewProj : IDENTITY
+        for (let k = 0; k < 16; k++) shadowMatrices[i * 16 + k] = m[k]!
+        i++
       }
-      let shown = parentVisible && node.visible
-      if (node.kind === "mesh") {
-        let mesh = node as Mesh
-        if (mesh._entry !== null) {
-          if (mesh._hidden === shown) {
-            // Mismatch: flip the entry's cheap off switch.
-            setDrawRange(texture, mesh._entry, { instanceCount: shown ? 1 : 0 })
-            mesh._hidden = !shown
-            if (shown) mesh._fresh = true
-          }
-          if (changed && mesh._transparent && transparentCount > 1) orderDirty = true
-          if (!mesh._hidden && (changed || mesh._fresh)) {
-            if (mesh.material.normalMatrix) {
-              setDrawParams(texture, mesh._entry, {
-                uModel: mesh._world,
-                uNormal: normalMatrix(normalScratch, mesh._world),
-              })
-            } else {
-              setDrawParams(texture, mesh._entry, { uModel: mesh._world })
-            }
-            mesh._fresh = false
-          } else if (changed) {
-            // Moved while hidden: write the fresh matrix on unhide.
-            mesh._fresh = true
-          }
-          // The broadphase leaf follows the world matrix - hidden meshes
-          // included (they stay in the tree and are skipped at query time,
-          // so unhiding never picks against a stale box).
-          if (changed || mesh._pickLeaf === null) updateLeaf(mesh)
-        }
+      for (; i < MAX_LIGHTS; i++) for (let k = 0; k < 16; k++) shadowMatrices[i * 16 + k] = IDENTITY[k]!
+      let params: ShaderParams = { uShadowMatrix: shadowMatrices }
+      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()
+    if (moved.length > 0) {
+      // Which meshes moved is the core's knowledge now, so any move with
+      // two or more transparent meshes re-sorts (sortEntries issues nothing
+      // when the permutation is unchanged).
+      if (transparentCount > 1) {
+        orderDirty = true
+        for (let v of views) v.orderDirty = true
       }
-      for (let c of node.children) walk(c, changed, shown)
+      for (let n of moved) n._moved = false
+      moved.length = 0
     }
-    walk(root, false, true)
+    // The sort keys are world-space and camera-independent: refreshed once
+    // for every sort this sync.
+    if (orderDirty || views.some(v => v.orderDirty)) refreshCenters()
     if (orderDirty) sortEntries()
+    for (let v of views) if (v.orderDirty) sortView(v)
   }
 
   let hooks: SceneHooks = {
@@ -750,73 +1584,190 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       scheduled = true
       RESOLVED.then(sync)
     },
+    _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")
+      }
+      lights.push(light)
+      lightsDirty = true
+      if (light.type === "directional" && light.castShadow) createShadow(light)
+    },
+    _detachLight(light) {
+      let i = lights.indexOf(light)
+      if (i >= 0) lights.splice(i, 1)
+      lightsDirty = true
+      if (light.type === "directional") destroyShadow(light)
+      hooks._schedule()
+    },
+    _shadowChanged(light) {
+      if (disposed) return
+      let shadow = shadows.get(light)
+      if (shadow !== undefined) {
+        if (!light.castShadow) {
+          destroyShadow(light)
+          return
+        }
+        let size = light.shadow.mapSize
+        if (size !== shadow.view.width) {
+          shadow.view.width = size
+          shadow.view.height = size
+          setTargetSize(shadow.view.texture, size, size)
+        }
+        shadow.dirty = true
+        lightsDirty = true
+        hooks._schedule()
+      } else if (light.castShadow) {
+        createShadow(light)
+      }
+    },
+    _setCast(mesh) {
+      if (mesh._entry === null || disposed) return
+      for (let v of views) {
+        if (v.filter === null) continue
+        if (v.filter(mesh)) attachView(v, mesh)
+        else detachView(v, mesh)
+      }
+      hooks._schedule()
+    },
+    _lightChanged() {
+      lightsDirty = true
+      hooks._schedule()
+    },
     _attach(mesh) {
       if (disposed) return
-      // Layout is stride: a mismatched pair would not miss a channel, it
-      // would read garbage - so it is an error here, like the rest of the
-      // strict entry path.
-      let geoLayout = mesh.geometry.layout ?? "standard"
-      let matLayout = mesh.material.layout ?? "standard"
-      if (geoLayout !== matLayout) {
+      validateGeometry(mesh.geometry)
+      checkLayout(mesh.material, mesh.geometry, "Mesh material")
+      // Every check before any mutation, so a rejected mesh is attached
+      // nowhere - the views' override materials included.
+      for (let v of views) {
+        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
+      // 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) {
         throw new Error(
-          "Mesh geometry layout '" + geoLayout + "' does not match its material's '" + matLayout +
-            "' - a material reading aColor needs withColors() geometry, and colored geometry needs such a material",
+          "Material declares instanceAttributes - create its meshes with createInstancedMesh (records included), not createMesh",
         )
       }
-      let bufs = geometryBuffers(mesh.geometry)
-      // The uNormal seed keys off the material flag because entry params
-      // validate strictly - and a material declaring uNormal without using
-      // it therefore throws right here, at add().
-      let seed: ShaderParams = mesh.material.normalMatrix
-        ? { uModel: IDENTITY, uNormal: IDENTITY, ...mesh.material.params, ...mesh._params }
-        : { uModel: IDENTITY, ...mesh.material.params, ...mesh._params }
+      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,
+          )
+        }
+      }
+      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(), seed, {
+      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)
+      for (let v of views) attachView(v, mesh)
+      // 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).
+      spatial.setBounds(mesh._node!, localBounds(mesh))
+      spatial.setShape(mesh._node!, inst === null && !mesh._sprite ? bufs.shape : null)
+      byNode.set(mesh._node!, mesh)
       meshes.push(mesh)
       mesh._transparent = mesh.material.transparent === true
       if (mesh._transparent) transparentCount++
       orderDirty = true
-      mesh._hidden = true
-      mesh._fresh = true
       this._schedule()
     },
     _detach(mesh) {
       if (mesh._entry !== null) {
+        for (let v of views) detachView(v, 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)
+        mesh._buffers = null
         let i = meshes.indexOf(mesh)
         if (i >= 0) meshes.splice(i, 1)
         if (mesh._transparent) transparentCount--
         orderDirty = true
       }
       mesh._entry = null
-      // The leaf goes with the entry: a geometry swap rebuilds the entry,
-      // and re-inserting is what picks up the new local bounds.
-      if (mesh._pickLeaf !== null) {
-        bvh.remove(mesh._pickLeaf)
-        mesh._pickLeaf = null
-      }
     },
     _setParams(mesh, params) {
-      if (mesh._entry !== null && !disposed) setDrawParams(texture, mesh._entry, params)
+      if (mesh._entry === null || disposed) return
+      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) {
+        let entry = v.entries.get(mesh)
+        if (entry !== undefined && v.override === null) setDrawParams(v.texture, entry, params)
+      }
+    },
+    _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) {
+        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 })
+        for (let v of views) {
+          let entry = v.entries.get(mesh)
+          if (entry !== undefined) setDrawBuffers(v.texture, entry, { instanceBuffer: mesh._instances.buffer })
+        }
+      }
     },
     _reorder() {
       orderDirty = true
+      for (let v of views) v.orderDirty = true
+      this._schedule()
+    },
+    _moved(node) {
+      if (!node._moved) {
+        node._moved = true
+        moved.push(node)
+      }
       this._schedule()
     },
   }
 
   let root = makeNode("group")
   root._scene = hooks
+  root._node = spatial.createNode(fillTransform(root), true)
+  // The first light rewrite seeds the (empty) light set and the shadow
+  // slots - placeholders, no casts - so receivers draw plain from the
+  // first frame.
+  lightsDirty = true
+  hooks._schedule()
 
   // --- Pointer event dispatch (behind scene.handlers) ---
 
@@ -863,7 +1814,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   }
 
   // localX/localY arrive in the leaf's LAYOUT frame (the hit test undoes
-  // every transform above it, viewBox fits included), so a leaf laid out at
+  // 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
@@ -943,13 +1894,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     texture,
     root,
     setCamera(update) {
-      if (update.fov !== undefined) fov = update.fov
-      if (update.near !== undefined) near = update.near
-      if (update.far !== undefined) far = update.far
-      if (update.position) eye = [update.position[0], update.position[1], update.position[2]]
-      if (update.target) target = [update.target[0], update.target[1], update.target[2]]
-      if (update.up) up = [update.up[0], update.up[1], update.up[2]]
-      cameraDirty = true
+      updateCamera(camera, update)
       hooks._schedule()
     },
     setSize(w, h) {
@@ -957,11 +1902,14 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       width = w
       height = h
       setTargetSize(texture, w, h)
-      cameraDirty = true
+      camera.dirty = true
       hooks._schedule()
     },
     setParams(params) {
-      if (!disposed) setTargetParams(texture, params)
+      if (disposed) return
+      Object.assign(sceneParams, params)
+      setTargetParams(texture, params)
+      for (let v of views) setTargetParams(v.texture, params)
     },
     setBackground(source) {
       if (disposed) return
@@ -979,81 +1927,122 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       background = { entry, pipeline: built.pipeline, program: built.program }
     },
     project(point) {
-      ensureCamera()
-      transformPoint(clip, viewProj, point)
+      ensureCamera(camera, width, height)
+      transformPoint(clip, camera.viewProj, point)
       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.
+      // 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 }
     },
     viewProj(out) {
-      ensureCamera()
-      return copy(out ?? mat4(), viewProj)
+      ensureCamera(camera, width, height)
+      return copy(out ?? mat4(), camera.viewProj)
     },
     pick(x, y) {
-      ensureCamera()
-      // 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(((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 * view[0] + cy * view[1] - view[2]
-      pickDir[1] = cx * view[4] + cy * view[5] - view[6]
-      pickDir[2] = cx * view[8] + cy * view[9] - view[10]
-      return scene.raycast(eye, pickDir)
+      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]
+      return scene.raycast(pickOrigin, pickDir)
     },
     raycast(origin, direction) {
       // 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()
-      let dx = direction[0]
-      let dy = direction[1]
-      let dz = direction[2]
-      let len = Math.hypot(dx, dy, dz)
-      if (len === 0 || disposed) return []
-      dx /= len
-      dy /= len
-      dz /= len
-      let ox = origin[0]
-      let oy = origin[1]
-      let oz = origin[2]
+      if (disposed) return []
       let hits: Hit[] = []
-      bvh.raycast(ox, oy, oz, dx, dy, dz, mesh => {
-        if (mesh._hidden || mesh._entry === null) return
-        // Narrowphase: the ray in the mesh's local frame against its tight
-        // local box - exact under any affine world transform. The local
-        // direction stays unnormalized on purpose: an affine map preserves
-        // the ray parameter, so t is world units as-is.
-        invertAffine(pickInv, mesh._world)
-        transformPoint(pickOrigin, pickInv, origin)
-        pickDir[0] = dx
-        pickDir[1] = dy
-        pickDir[2] = dz
-        transformVector(pickDir, pickInv, pickDir)
-        let b = geometryBounds(mesh.geometry)
-        let t = rayBoxDistance(
-          pickOrigin[0], pickOrigin[1], pickOrigin[2],
-          pickDir[0], pickDir[1], pickDir[2],
-          b[0]!, b[1]!, b[2]!, b[3]!, b[4]!, b[5]!,
-        )
-        if (t >= 0) hits.push({ mesh, distance: t, point: [ox + dx * t, oy + dy * t, oz + dz * t] })
-      })
-      hits.sort((a, b) => a.distance - b.distance)
+      rayOriginScratch[0] = origin[0]
+      rayOriginScratch[1] = origin[1]
+      rayOriginScratch[2] = origin[2]
+      rayDirScratch[0] = direction[0]
+      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
+        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)
     },
+    createView(vopts) {
+      if (disposed) throw new Error("createView: the scene is disposed")
+      let v = makeView(vopts, null)
+      return {
+        texture: v.texture,
+        depthTexture: vopts.depth === "texture" ? depthTexture(v.texture) : null,
+        setCamera(update) {
+          updateCamera(v.camera, update)
+          hooks._schedule()
+        },
+        setSize(w, h) {
+          if (v.disposed || (w === v.width && h === v.height)) return
+          v.width = w
+          v.height = h
+          setTargetSize(v.texture, w, h)
+          v.camera.dirty = true
+          hooks._schedule()
+        },
+        setParams(params) {
+          if (!v.disposed) setTargetParams(v.texture, params)
+        },
+        dispose() {
+          disposeView(v)
+        },
+      }
+    },
     dispose() {
       if (disposed) return
       disposed = true
+      // Full tree-side teardown, not just the target: every node leaves
+      // the scene (entries' geometry-buffer references and pick leaves
+      // dropped, core nodes freed), so a disposed scene leaves no
+      // bookkeeping behind and the JS tree survives as plain data.
+      for (let c of root.children.slice()) leaveScene(c)
+      root._scene = null
+      if (root._node !== null) {
+        spatial.destroyNode(root._node)
+        root._node = 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 (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.