@solidrt/3d 0.0.49 → 0.0.51

package/src/scene.ts

@@ -3,10 +3,12 @@
 // 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
-// camera is the target's SHARED uViewProj + uCamPos - one setTargetParams
-// per camera move, not one write per mesh. uCamPos rides unconditionally:
-// shared params tolerate zero coverage (stored and skipped until a
-// declaring material arrives), so no bookkeeping tracks who reads it.
+// 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
+// coverage (stored and skipped until a declaring material arrives), so no
+// bookkeeping tracks who reads them. scene.setParams merges app-owned
+// names into the same set.
 // Mutations batch to a microtask, so a burst of writes (a whole subtree
 // moved, many effects in one flush) syncs once.
 //
@@ -17,17 +19,20 @@
 // each write lands here, the microtask syncs the affected uModels, and the
 // flush renders once that frame.
 
-import { addDraw, createDrawTarget, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, 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, destroyBuffer, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, setDrawOrder, setDrawParams, setDrawRange, setTargetParams, setTargetSize, writeBuffer } from "@solidrt/core/gpu"
+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, 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, invertAffine, lookAt as lookAtMatrix, mat4, multiply, normalMatrix, perspective, quat, quatFromFrame, transformPoint, transformVector, updateRotation, updateScale } from "./math.ts"
+import type { Mat4, Quat, TransformUpdate, Vec3, Vec4 } from "./math.ts"
+import { geometryBounds } 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 { orderEntries } from "./order.ts"
 import type { Material } from "./material.ts"
 import { createBvh, rayBoxDistance } from "./bvh.ts"
 
@@ -51,6 +56,10 @@ let upScratch: Vec3 = [0, 0, 0]
 let pickInv = mat4()
 let pickOrigin: Vec4 = [0, 0, 0, 0]
 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
@@ -62,6 +71,8 @@ type SceneHooks = {
   _attach(mesh: Mesh): void
   _detach(mesh: Mesh): void
   _setParams(mesh: Mesh, params: ShaderParams): void
+  _setCount(mesh: Mesh): void
+  _reorder(): void
 }
 
 export type SceneNode = {
@@ -97,13 +108,55 @@ 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
   _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. */
+  _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
 }
 
+/** 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; fixed at creation, like every GPU
+   * buffer's byte size. */
+  capacity: number
+  /** 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 }
+
 /** 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. */
@@ -184,6 +237,15 @@ export type Scene = {
   /** Partial camera update; absent keys keep their current value. */
   setCamera(update: CameraUpdate): void
   setSize(width: number, height: number): void
+  /**
+   * Scene-wide uniforms: merge app-owned names into the target's SHARED
+   * params, beside the standard uViewProj/uCamPos/uCamRight/uCamUp the
+   * camera writes. One write per frame however many meshes read the name
+   * (a clock, a sun direction, fog) - the per-mesh channel is
+   * setMeshParams. Merge semantics, no unset; a material that does not
+   * declare a name simply skips it. Frame-rate-safe like setTransform.
+   */
+  setParams(params: ShaderParams): 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
@@ -249,9 +311,10 @@ 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). */
+  /** 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
 }
 
@@ -279,14 +342,149 @@ export function createMesh(geometry: Geometry, material: Material): Mesh {
   let mesh = makeNode("mesh") as Mesh
   mesh.geometry = geometry
   mesh.material = material
+  mesh.renderOrder = 0
   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
   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
+ * geometry's own bounds otherwise. */
+function localBounds(mesh: Mesh): Float32Array | null {
+  return mesh._instances !== null ? mesh._instances.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 - the buffer's
+ * capacity is fixed at creation, like any GPU buffer. `count` limits how
+ * many records draw (default all); grow it later only 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,
+    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. The buffer's capacity is fixed at creation; more records than
+ * capacity throw (make a new mesh for a bigger population). Frame-rate-safe
+ * like setMeshParams.
+ */
+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) {
+    throw new Error(
+      "setInstances: " + written + " records exceed the buffer's capacity of " + inst.capacity + " (fixed at creation)",
+    )
+  }
+  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)
@@ -322,51 +520,52 @@ function leaveScene(node: SceneNode): void {
   for (let c of node.children) leaveScene(c)
 }
 
-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
-}
+export type { TransformUpdate } from "./math.ts"
 
 /**
  * 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) {
+  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
   }
-  let r = update.rotation
-  let q = update.quaternion
-  if (r !== undefined && q !== undefined) {
-    throw new Error("Pass rotation or quaternion to setTransform, not both")
+  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 (r !== undefined) quatFromEuler(node.quaternion, r)
-  else if (q !== undefined) quatNormalize(node.quaternion, q)
-  let s = update.scale
-  if (s !== undefined) {
-    if (typeof s === "number") {
-      node.scale[0] = s
-      node.scale[1] = s
-      node.scale[2] = s
-    } else {
-      node.scale[0] = s[0]
-      node.scale[1] = s[1]
-      node.scale[2] = s[2]
+  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()
 }
@@ -482,8 +681,15 @@ export function setVisible(node: SceneNode, visible: boolean): void {
   node._scene?._schedule()
 }
 
-/** Swap a mesh's geometry: its draw entry is rebuilt (appended last -
- * order is irrelevant while every entry is opaque and depth-tested). */
+/** 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()
+}
+
+/** 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.geometry === geometry) return
   mesh.geometry = geometry
@@ -545,18 +751,41 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   let capture = new Map<number, Mesh>()
   let hover = new Map<number, Mesh>()
 
-  // Live mesh entries in list (draw) order, so a background set after
-  // meshes exist can insert BEFORE the first one. Mesh entries append;
-  // rebuilds re-append; the background entry never joins this list.
-  let entryOrder: DrawId[] = []
+  // Live meshes (those holding a draw entry) in add order; the background
+  // entry never joins this list. Draw order is derived from it by
+  // orderEntries (order.ts) whenever orderDirty. Camera moves and
+  // transparent-mesh moves only dirty the order when two or more transparent
+  // meshes exist - fewer cannot change relative order.
+  let meshes: Mesh[] = []
+  let transparentCount = 0
+  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
+  let sortEntries = () => {
+    orderDirty = false
+    let order = orderEntries(meshes, 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 b = localBounds(mesh)
     let m = mesh._world
+    if (b === null) {
+      // An instanced mesh without explicit bounds: records are opaque, so
+      // there is nothing to build a leaf from - the mesh never picks. Keep
+      // the transparent sort key at the node's own world position.
+      mesh._center[0] = m[12]
+      mesh._center[1] = m[13]
+      mesh._center[2] = m[14]
+      return
+    }
     let cx = (b[0]! + b[3]!) / 2
     let cy = (b[1]! + b[4]!) / 2
     let cz = (b[2]! + b[5]!) / 2
@@ -566,6 +795,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     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
@@ -610,7 +842,16 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       // holds. Entries are untouched - uModel is camera-independent, and
       // uCamPos is stored even when no current material declares it.
       cameraPending = false
-      setTargetParams(texture, { uViewProj: viewProj, uCamPos: eye })
+      // 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]],
+      })
+      if (transparentCount > 1) orderDirty = true
     }
     let walk = (node: SceneNode, parentChanged: boolean, parentVisible: boolean) => {
       let changed = parentChanged
@@ -627,11 +868,13 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         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 })
+            // Mismatch: flip the entry's cheap off switch. An instanced
+            // mesh's "on" is its own record count, not 1.
+            setDrawRange(texture, mesh._entry, { instanceCount: shown ? (mesh._instances !== null ? mesh._instances.count : 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, {
@@ -655,6 +898,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       for (let c of node.children) walk(c, changed, shown)
     }
     walk(root, false, true)
+    if (orderDirty) sortEntries()
   }
 
   let hooks: SceneHooks = {
@@ -676,7 +920,30 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
             "' - a material reading aColor needs withColors() geometry, and colored geometry needs such a material",
         )
       }
-      let bufs = geometryBuffers(mesh.geometry)
+      // 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(
+          "Material declares instanceAttributes - create its meshes with createInstancedMesh (records included), 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,
+          )
+        }
+      }
+      let bufs = acquireGeometryBuffers(mesh.geometry)
+      mesh._buffers = bufs
       // 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().
@@ -693,9 +960,13 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         indexBuffer: bufs.index,
         indexFormat: bufs.indexFormat,
         textures: mesh.material.textures,
+        instanceBuffer: inst !== null ? inst.buffer : undefined,
         instanceCount: 0,
       })
-      entryOrder.push(mesh._entry)
+      meshes.push(mesh)
+      mesh._transparent = mesh.material.transparent === true
+      if (mesh._transparent) transparentCount++
+      orderDirty = true
       mesh._hidden = true
       mesh._fresh = true
       this._schedule()
@@ -703,8 +974,12 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     _detach(mesh) {
       if (mesh._entry !== null) {
         if (!disposed) removeDraw(texture, mesh._entry)
-        let i = entryOrder.indexOf(mesh._entry)
-        if (i >= 0) entryOrder.splice(i, 1)
+        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,
@@ -717,6 +992,16 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     _setParams(mesh, params) {
       if (mesh._entry !== null && !disposed) setDrawParams(texture, mesh._entry, params)
     },
+    _setCount(mesh) {
+      // A hidden entry stays at 0; the unhide write restores the count.
+      if (mesh._entry !== null && !mesh._hidden && !disposed && mesh._instances !== null) {
+        setDrawRange(texture, mesh._entry, { instanceCount: mesh._instances.count })
+      }
+    },
+    _reorder() {
+      orderDirty = true
+      this._schedule()
+    },
   }
 
   let root = makeNode("group")
@@ -864,6 +1149,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       cameraDirty = true
       hooks._schedule()
     },
+    setParams(params) {
+      if (!disposed) setTargetParams(texture, params)
+    },
     setBackground(source) {
       if (disposed) return
       if (background !== null) {
@@ -874,9 +1162,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       }
       if (source === null) return
       let built = backgroundPipeline(source, (opts?.label ?? "scene") + "-background")
-      // First in list order: meshes append behind it forever (rebuilds
-      // re-append too), so pinning happens once, here.
-      let entry = addDraw(texture, built.pipeline, null, { vertexCount: 3, before: entryOrder[0] })
+      // First in list order: inserted before the first mesh entry, 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 }
     },
     project(point) {
@@ -936,7 +1224,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         pickDir[1] = dy
         pickDir[2] = dz
         transformVector(pickDir, pickInv, pickDir)
-        let b = geometryBounds(mesh.geometry)
+        // A boundless instanced mesh has no leaf, so the BVH never visits
+        // it; this read is the bounds the leaf was built from.
+        let b = localBounds(mesh)
+        if (b === null) return
         let t = rayBoxDistance(
           pickOrigin[0], pickOrigin[1], pickOrigin[2],
           pickDir[0], pickDir[1], pickDir[2],
@@ -954,6 +1245,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     dispose() {
       if (disposed) return
       disposed = true
+      // Full mesh-side teardown, not just the target: _detach drops each
+      // entry's geometry-buffer reference and pick leaf and clears _entry,
+      // so a disposed scene leaves no mesh bookkeeping behind.
+      for (let mesh of meshes.slice()) hooks._detach(mesh)
       destroyTexture(texture)
       if (background !== null) {
         // The entry died with the target; the pipeline and program are the