@solidrt/3d 0.0.50 → 0.0.51

package/AGENTS.md

@@ -39,17 +39,19 @@ blendMode and pointer events like any element. Design rationale:
   Indices are uint16 or uint32 - the `Geometry.indices` array type picks
   the draw's index format, so hand-built geometry past 64k vertices just
   uses a Uint32Array (generators emit uint16). Geometry GPU buffers are
-  lazy, shared, and app-lifetime (owner-scoped free would break sharing);
-  `disposeGeometry` frees them.
+  lazy, shared, and reference-counted by draw entries: removing the last
+  entry frees them at the end of the microtask (a same-tick rebuild keeps
+  the upload), so swapping `<Mesh geometry>` reactively never accumulates
+  old generations. `disposeGeometry` is the immediate explicit free.
 - Materials dedupe hard: one program + one pipeline per material CLASS
   (unlit color, unlit map, each opaque or transparent), `depth: true` +
   `cull: "back"`; an instance is
   just per-entry uniforms (`uColor`) and bindings (`uMap`).
-- The pure pieces (`math.ts`, `bvh.ts`, `order.ts`) have check rigs in
+- The pure pieces (`math.ts`, `bvh.ts`, `order.ts`, `geometry.ts`) have check rigs in
   `checks/`, run headless on flux from the repo root:
   `bunx srt bundle -f --stdout packages/3d/checks/<name>-check.ts | target/release/flux - [seed]`.
-  They print PASS or FAIL lines and throw on failure (the flux binary exits
-  0 either way - read the output). Extend the rig when you change the module.
+  They print PASS or FAIL lines and throw on failure, which exits nonzero.
+  Extend the rig when you change the module.
 
 ## Components
 
@@ -58,6 +60,7 @@ blendMode and pointer events like any element. Design rationale:
 | `Scene` | `width`, `height` (target pixels), `clearColor?`, `background?` (fragment GLSL), `label?`, `ref?(scene)`, `output?(texture)`, `events?` (mesh pointer events, default on) |
 | `Group` | `position?`, `rotation?` (Euler radians, XYZ order), `quaternion?` (either, not both), `scale?` (number = uniform), `visible?`, pointer events (below), `ref?(node)` |
 | `Mesh` | `geometry`, `material`, transforms as Group, `params?` (per-mesh uniforms, merge semantics - no unset), pointer events (below), `ref?(mesh)` |
+| `InstancedMesh` | as Mesh, plus `records` (interleaved per-instance floats; buffer capacity fixed by the first value), `count?` (records drawn, default all), `bounds?` (local [minX..maxZ] over the population - without it the mesh never picks); the record buffer is component-owned and freed on unmount |
 | `PerspectiveCamera` | `fov?` (vertical DEGREES, default 60), `near?`, `far?`, `position?`, `lookAt?`, `up?` |
 
 Output composition: without `output`, `Scene` emits a minimal
@@ -161,6 +164,25 @@ hands the baker world-space vertices. `fill` indexes relative to
 `first`. It trusts the buffer's layout (no tag to check); withColors is
 the checked path.
 
+Geometry as data: `transformGeometry(geometry, { position?, rotation?,
+quaternion?, scale? }, label?)` bakes a placement into a copy (the
+setTransform shape: Euler XYZ radians or a quaternion, number = uniform
+scale), positions through the matrix and normals through its
+inverse-transpose, renormalized - correct under non-uniform scale; uvs,
+colors, indices and layout copy through. `mergeGeometries(parts, label?)`
+concatenates parts into one geometry with offset indices (uint32 past 64k
+vertices); parts must share one layout, a mixed list throws. Together
+they collapse a static scene to one mesh per material - transform each
+part into place, merge, draw once - so only what actually moves keeps a
+node, a draw entry and a per-frame `uModel` write of its own. Both are
+pure array math (Three's `applyMatrix4` + `mergeGeometries`), no GPU
+call, and the source geometries are untouched. `geometryBounds(geometry)`
+returns the cached local AABB `[minX, minY, minZ, maxX, maxY, maxZ]`, and
+`rayBoxDistance(ox, oy, oz, dx, dy, dz, minX, .., maxZ)` is the picking
+slab test (entry t >= 0 in units of the direction's length, 0 from
+inside, -1 for a miss) - for ray-testing boxes you keep yourself
+(triggers, collision volumes) without meshes you do not want to draw.
+
 Profile kit (2D outlines to solids, real texture UVs): a `Profile` is a
 closed XY polygon, bare `[x, y]` points crease, `{ p, smooth }` points
 share an averaged normal - `fillet(points, radius, segs?)` and
@@ -225,6 +247,34 @@ Materials:
   pipeline with its own values. `dispose()` lives on the class alone.
   `shaderMaterial(opts)` is exactly a class with one instance (its
   `dispose` forwards to the class).
+- `instanceAttributes: [{ name, format }]` on either shader-material form
+  makes an INSTANCED material: the vertex stage reads them as `in`
+  variables beside the layout's own, and each drawn instance gets one
+  record of the mesh's instance buffer. Its meshes come from
+  `createInstancedMesh` (below); a `createMesh` mesh is rejected at add().
+
+Instancing - one draw entry covering a population:
+`createInstancedMesh(geometry, material, records, count?, { bounds?,
+label? })` returns an ordinary Mesh whose entry draws the geometry once
+per record. `records` is the interleaved per-instance data (stride = the
+material's instanceAttributes summed, a mismatch throws), uploaded to a
+mesh-owned buffer whose CAPACITY is fixed at creation. `count` picks how
+many records draw (default all). Everything mesh works unchanged:
+setTransform moves the whole population through one uModel, setVisible
+zeroes the drawn count and restores the record count on unhide,
+renderOrder/params/geometry/material swaps apply. `setInstances(mesh,
+records, count?)` rewrites records from the start (count defaults to the
+records written; more than capacity throws - make a new mesh to grow),
+`setInstanceCount(mesh, n)` is the population dial (clamped to capacity;
+frame-rate-safe), and `disposeInstances(mesh)` detaches and frees the
+record buffer - the one explicit free, geometry-buffer rule. Records are
+opaque data (position/yaw/tint/whatever your shader reads), NOT matrices:
+a per-instance mat4 would be four vec4 columns reassembled in the shader,
+but most fleets want a few floats. Picking: the library cannot know where
+records place instances, so an instanced mesh has NO picking leaf unless
+you pass `bounds` (local, covering the population) - then it picks and
+transparent-sorts conservatively as one box. `examples/instanced.tsx` is
+the live proof.
 
 Background: `scene.setBackground(source | null)`, the `background` option
 on createScene, and the reactive `Scene` prop. Fragment GLSL drawn as the
@@ -262,11 +312,26 @@ system.
   "fix" the negated row of `perspective()` - both would mirror the winding
   and show mesh interiors.
 - `visible: false` keeps the entry, drawn with `instanceCount: 0` (a
-  cheap off switch). Hidden meshes skip uModel writes; the fresh matrix is
+  cheap off switch); unhiding writes 1, or the mesh's own record count
+  when it is instanced - never a bare 1 into an instanced entry. Hidden
+  meshes skip uModel writes; the fresh matrix is
   written on unhide. A freshly attached entry starts off the same way and
   sync() turns it on when it writes uModel - never add one live: it has no
   world matrix yet, and drawn before the sync microtask it flashes at the
   world origin for a frame.
+- Instancing pairs strictly at add(), like layout: an instanced material
+  needs a createInstancedMesh mesh (records included) and vice versa, and
+  the record stride must match the material's attributes - each mismatch
+  throws there. The instance buffer is MESH-owned (unlike shared geometry
+  buffers): `disposeInstances` is its one free, and the mesh cannot be
+  re-added afterwards. Capacity is fixed at creation - `setInstances` with
+  more records than capacity throws rather than growing (growing is a new
+  mesh; buffers do not resize).
+- An instanced mesh without explicit `bounds` has no BVH leaf: it never
+  picks, pointer events never target it, and its transparent sort key
+  falls back to the node's world position. That is deliberate - records
+  are opaque to the library, so any inferred box would be a guess. Supply
+  `bounds` for anything pickable or transparent.
 - Transparency is an EXPLICIT material flag, Three's rule: `unlit({ color:
   [r, g, b, 0.5] })` still draws opaque; `unlit({ ..., transparent: true })`
   (or `shaderMaterial({ transparent: true })`) builds the pipeline with

package/README.md

@@ -67,7 +67,11 @@ change - plus your own uniforms: scene-wide via `scene.setParams` (one write
 however many meshes read it), or per mesh, declaratively via the `params`
 prop on `<Mesh>` or imperatively via `setMeshParams`. `shaderMaterialClass`
 compiles one program and hands out `instance()` materials that differ only
-in params/textures. And
+in params/textures - and with `instanceAttributes` it makes an instanced
+material: `<InstancedMesh records>` (or `createInstancedMesh`) then draws
+the geometry once per interleaved record as ONE draw entry, the shape for
+forests, particles, and every fleet whose per-copy data is a few floats
+(`examples/instanced.tsx`). And
 `@solidrt/3d/glsl` exports the lighting pieces (hemisphere, lambert,
 blinn, fresnel, a standard vertex stage) to compose your own lit looks
 from plain template literals.
@@ -77,7 +81,9 @@ GLSL as a first-class material), geometry generators (box, plane, circle,
 ring, sphere, cylinder, cone, torus, torus knot), a profile kit for custom
 solids (`extrude` with bevels, `lathe`, polyline `sweep`/`tube` with
 mitred joints, flat `shape`, with `fillet`/`roundRect`/`triangulate`
-helpers), a per-vertex data channel
+helpers), geometry as data (`transformGeometry` bakes a placement into
+vertices and `mergeGeometries` concatenates parts, so a static scene is
+one mesh per material), a per-vertex data channel
 (`withColors` adds an `aColor` vec4 - tint, baked AO, any four scalars -
 to any geometry, for materials that read it), one perspective camera
 with an orbit control (`createOrbitCamera`: drag, pinch/wheel zoom, auto-orbit),

package/examples/README.md

@@ -23,3 +23,8 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   scene's own pass (`<Scene background>`): one target, no stacked
   backdrop texture, no resize plumbing; the source is shader-target
   compatible verbatim.
+- `instanced.tsx` - instanced meshes: one material class declaring
+  `instanceAttributes`, two `<InstancedMesh>` fleets (400 scattered
+  rocks, a ring of pines) each ONE draw entry and ONE uModel, a spinning
+  group moving both with two matrix writes, and `setInstanceCount` from
+  onFrame breathing the pine population.

package/examples/instanced.tsx

@@ -0,0 +1,158 @@
+// Instanced meshes: one draw entry covering a whole population. A material
+// class declares `instanceAttributes`, createInstancedMesh (here via the
+// <InstancedMesh> component) supplies one interleaved record per instance,
+// and the vertex stage reads each record through the matching `in`
+// variables. Two meshes share the one class: 400 scattered "rocks" and a
+// breathing ring of "pines" - each is ONE entry and ONE uModel however
+// many instances it draws, so the spinning group below moves both fleets
+// with two matrix writes per frame.
+//
+// setInstanceCount is the population dial (the pines breathe); records are
+// data, not matrices - position/scale/tint here, whatever your shader
+// wants in general. The explicit `bounds` cover the scatter so picking
+// still works (one conservative box around the population; omit bounds and
+// the mesh simply never picks).
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { glsl } from "@solidrt/core/gpu"
+import {
+  box,
+  cone,
+  Group,
+  InstancedMesh,
+  Mesh,
+  PerspectiveCamera,
+  plane,
+  Scene,
+  setInstanceCount,
+  shaderMaterialClass,
+  unlit,
+} from "@solidrt/3d"
+import type { InstancedMeshNode } from "@solidrt/3d"
+import { HEMISPHERE } from "@solidrt/3d/glsl"
+
+const SIZE = 720
+
+const INSTANCE_VERTEX = glsl`
+  in vec3 aPos;
+  in vec3 aNormal;
+  in vec3 iPos;
+  in float iScale;
+  in vec3 iTint;
+  out vec3 vNormal;
+  out vec3 vTint;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+
+  void main() {
+    vec3 p = aPos * iScale + iPos;
+    gl_Position = uViewProj * uModel * vec4(p, 1.0);
+    vNormal = mat3(uModel) * aNormal;
+    vTint = iTint;
+  }
+`
+
+const INSTANCE_FRAGMENT = glsl`
+  in vec3 vNormal;
+  in vec3 vTint;
+  ${HEMISPHERE}
+
+  void main() {
+    vec3 c = vTint * hemisphere(normalize(vNormal), vec3(1.05, 1.0, 0.95), vec3(0.35, 0.32, 0.3));
+    fragColor = vec4(c, 1.0);
+  }
+`
+
+// One record per instance, interleaved in attribute order: 7 floats.
+const STRIDE = 7
+
+// A deterministic scatter (no per-run surprises when eyeballing).
+function rocks(count: number): Float32Array {
+  let records = new Float32Array(count * STRIDE)
+  let a = 0
+  for (let i = 0; i < count; i++) {
+    a += 2.399963 // golden angle: an even spiral scatter
+    let r = 0.35 + 3.4 * Math.sqrt((i + 0.5) / count)
+    let s = 0.05 + 0.11 * ((i * 7) % 10) / 10
+    let o = i * STRIDE
+    records[o] = Math.cos(a) * r
+    records[o + 1] = s / 2
+    records[o + 2] = Math.sin(a) * r
+    records[o + 3] = s
+    records[o + 4] = 0.55 + 0.3 * ((i * 3) % 5) / 5
+    records[o + 5] = 0.5 + 0.2 * ((i * 11) % 7) / 7
+    records[o + 6] = 0.45
+  }
+  return records
+}
+
+function pines(count: number): Float32Array {
+  let records = new Float32Array(count * STRIDE)
+  for (let i = 0; i < count; i++) {
+    let a = (i / count) * Math.PI * 2
+    let s = 0.5 + 0.25 * ((i * 5) % 8) / 8
+    let o = i * STRIDE
+    records[o] = Math.cos(a) * 2.4
+    records[o + 1] = s / 2
+    records[o + 2] = Math.sin(a) * 2.4
+    records[o + 3] = s
+    records[o + 4] = 0.15
+    records[o + 5] = 0.4 + 0.25 * ((i * 3) % 6) / 6
+    records[o + 6] = 0.2
+  }
+  return records
+}
+
+const PINE_COUNT = 48
+
+function App() {
+  let [spin, setSpin] = createSignal(0)
+  let pinesMesh!: InstancedMeshNode
+  onFrame(tick => {
+    setSpin(tick / 6000)
+    // The population dial: draw the first N records. The buffer holds the
+    // full ring; only the draw range moves, one setDrawRange per change.
+    let n = Math.round(PINE_COUNT * (0.5 + 0.5 * Math.sin(tick / 900)))
+    if (pinesMesh) setInstanceCount(pinesMesh, n)
+  })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.08, 0.1, 1]} label="instanced">
+          <PerspectiveCamera fov={55} position={[0, 3.2, 5.4]} lookAt={[0, 0.2, 0]} />
+          <Mesh geometry={plane(9, 9, "meadow")} material={unlit({ color: [0.16, 0.18, 0.16] })} rotation={[-Math.PI / 2, 0, 0]} />
+          <Group rotation={[0, spin(), 0]}>
+            <InstancedMesh
+              geometry={box(1, 1, 1, "rock")}
+              material={instancedLook.instance()}
+              records={rocks(400)}
+              bounds={[-3.9, 0, -3.9, 3.9, 0.2, 3.9]}
+            />
+            <InstancedMesh
+              geometry={cone(0.3, 1, 10, "pine")}
+              material={instancedLook.instance()}
+              records={pines(PINE_COUNT)}
+              bounds={[-2.8, 0, -2.8, 2.8, 0.8, 2.8]}
+              ref={m => (pinesMesh = m)}
+            />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+// One class, one compiled pipeline; each mesh gets its own instance() so
+// per-mesh uniforms stay independent (none are used here).
+let instancedLook = shaderMaterialClass({
+  vertex: INSTANCE_VERTEX,
+  fragment: INSTANCE_FRAGMENT,
+  instanceAttributes: [
+    { name: "iPos", format: "vec3" },
+    { name: "iScale", format: "f32" },
+    { name: "iTint", format: "vec3" },
+  ],
+  label: "instanced-look",
+})
+
+render(() => <App />)

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.50",
+  "version": "0.0.51",
   "license": "MIT",
+  "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
   "type": "module",
   "main": "src/index.ts",
@@ -17,6 +18,6 @@
   ],
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.0",
-    "@solidrt/core": "0.0.50"
+    "@solidrt/core": "0.0.51"
   }
 }

package/src/components.tsx

@@ -11,10 +11,14 @@ import type { Element, ParentComponent, TextureId, VoidComponent } from "@solidr
 import {
   add,
   createGroup,
+  createInstancedMesh,
   createMesh,
   createScene,
+  disposeInstances,
   remove,
   setGeometry,
+  setInstanceCount,
+  setInstances,
   setMaterial,
   setMeshParams,
   setRenderOrder,
@@ -22,7 +26,7 @@ import {
   setVisible,
 } from "./scene.ts"
 import type { ShaderParams } from "@solidrt/core/gpu"
-import type { Mesh as MeshNode, Scene as SceneHandle, SceneNode, ScenePointerEvent } from "./scene.ts"
+import type { InstancedMesh as InstancedMeshNode, Mesh as MeshNode, Scene as SceneHandle, SceneNode, ScenePointerEvent } from "./scene.ts"
 import type { Geometry } from "./geometry.ts"
 import type { Material } from "./material.ts"
 import type { Quat, Vec3 } from "./math.ts"
@@ -216,6 +220,74 @@ export let Mesh: VoidComponent<MeshProps> = props => {
   return null
 }
 
+export type InstancedMeshProps = TransformProps & PointerEventProps & {
+  geometry: Geometry
+  /** Must declare instanceAttributes (shaderMaterialClass). */
+  material: Material
+  /** Interleaved per-instance records (stride = the material's instance
+   * attributes summed). Reactive, but the buffer's CAPACITY is fixed by the
+   * first value - a later array may hold at most that many records. */
+  records: Float32Array
+  /** How many records draw; default all of the latest `records`. */
+  count?: number
+  /** LOCAL bounds covering every instance ([minX..maxZ]), fixed at
+   * creation. Without them the mesh has no picking leaf, so pointer events
+   * never target it. */
+  bounds?: ArrayLike<number>
+  /** Per-mesh uniforms, merge semantics - as on Mesh. */
+  params?: ShaderParams
+  /** Explicit draw-order key (setRenderOrder as a prop); default 0. */
+  renderOrder?: number
+  ref?: (mesh: InstancedMeshNode) => void
+}
+
+/** One draw entry covering N instances: geometry repeated per record of
+ * `records` (createInstancedMesh as a component). The record buffer is
+ * component-owned and freed on unmount. */
+export let InstancedMesh: VoidComponent<InstancedMeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() =>
+    createInstancedMesh(props.geometry, props.material, props.records, props.count, { bounds: props.bounds }),
+  )
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.records,
+    r => setInstances(mesh, r, untrack(() => props.count)),
+    { defer: true },
+  )
+  createEffect(
+    () => props.count,
+    c => {
+      if (c !== undefined) setInstanceCount(mesh, c)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => props.geometry,
+    g => setGeometry(mesh, g),
+    { defer: true },
+  )
+  createEffect(
+    () => props.material,
+    m => setMaterial(mesh, m),
+    { defer: true },
+  )
+  createEffect(
+    () => props.params,
+    p => {
+      if (p !== undefined) setMeshParams(mesh, p)
+    },
+  )
+  createEffect(
+    () => props.renderOrder,
+    o => setRenderOrder(mesh, o ?? 0),
+  )
+  syncNode(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => disposeInstances(mesh))
+  return null
+}
+
 export type PerspectiveCameraProps = {
   /** Vertical field of view in DEGREES (default 60). */
   fov?: number

package/src/geometry-gpu.ts

@@ -0,0 +1,86 @@
+// Geometry on the GPU: the lazy buffer step for geometry.ts's data. Buffers
+// are created on first acquire and shared by every mesh and scene drawing
+// the geometry; each draw entry holds one reference, and the buffers are
+// freed when the last reference is released - deferred to a microtask, so
+// a same-tick entry rebuild (a material swap, a geometry that comes right
+// back) keeps its upload. The handles and the reference count live in a
+// map private to this module, keeping Geometry itself plain data.
+// disposeGeometry frees immediately, the explicit override; either way the
+// geometry stays usable - fresh buffers are created on next acquire.
+
+import { createBuffer, destroyBuffer } from "@solidrt/core/gpu"
+import type { BufferId, IndexFormat } from "@solidrt/core/gpu"
+import type { Geometry } from "./geometry.ts"
+
+/** An acquired reference to a geometry's GPU buffers: what a draw entry
+ * binds, and the token releaseGeometryBuffers takes - releasing the exact
+ * acquisition keeps the pairing correct however the caller's geometry
+ * fields have moved since. */
+export type GeometryBuffers = {
+  buffer: BufferId
+  index: BufferId
+  indexFormat: IndexFormat
+}
+
+type GpuEntry = GeometryBuffers & { geometry: Geometry; refs: number }
+
+let entries = new WeakMap<Geometry, GpuEntry>()
+
+/** The geometry's GPU buffers, created on first use, plus the index format
+ * the draw entry must bind them with. Takes a reference - pair every
+ * acquire with a releaseGeometryBuffers of the returned token when the
+ * entry built from it goes. */
+export function acquireGeometryBuffers(geometry: Geometry): GeometryBuffers {
+  let entry = entries.get(geometry)
+  if (entry === undefined) {
+    entry = {
+      geometry,
+      buffer: createBuffer(geometry.vertices, {
+        autoFree: false,
+        label: geometry.label ? geometry.label + "-verts" : undefined,
+      }),
+      index: createBuffer(geometry.indices, {
+        autoFree: false,
+        label: geometry.label ? geometry.label + "-indices" : undefined,
+      }),
+      indexFormat: geometry.indices instanceof Uint32Array ? "uint32" : "uint16",
+      refs: 0,
+    }
+    entries.set(geometry, entry)
+  }
+  entry.refs++
+  return entry
+}
+
+/** Release one acquire. At zero references the buffers are freed at the
+ * end of the microtask; an acquire before then keeps them, so a detach and
+ * re-attach in one tick never re-uploads. A token orphaned by an explicit
+ * disposeGeometry releases against the orphan, never against a successor's
+ * fresh buffers. */
+export function releaseGeometryBuffers(acquired: GeometryBuffers): void {
+  let entry = acquired as GpuEntry
+  if (entry.refs === 0) return
+  entry.refs--
+  if (entry.refs > 0) return
+  queueMicrotask(() => {
+    if (entries.get(entry.geometry) !== entry || entry.refs > 0) return
+    entries.delete(entry.geometry)
+    destroyBuffer(entry.buffer)
+    destroyBuffer(entry.index)
+  })
+}
+
+/**
+ * Free the geometry's GPU buffers now, held references or not - the
+ * explicit override for geometry an app is done with for good. Draw
+ * entries created from them hold their own reference, so destruction order
+ * is safe; the geometry can be used again afterwards (fresh buffers are
+ * created on next use).
+ */
+export function disposeGeometry(geometry: Geometry): void {
+  let entry = entries.get(geometry)
+  if (entry === undefined) return
+  entries.delete(geometry)
+  destroyBuffer(entry.buffer)
+  destroyBuffer(entry.index)
+}

package/src/geometry.ts

@@ -12,16 +12,13 @@
 // unused by the unlit materials so the layout is ready for lights without
 // a geometry change (inactive attributes are skipped but keep the stride).
 //
-// GPU buffers are created lazily on first use and shared by every mesh and
-// scene drawing the geometry. They are app-lifetime by design - one
-// geometry commonly outlives the component that first drew it, so
-// owner-scoped auto-free would free a buffer other scenes still draw from.
-// disposeGeometry frees them when an app is done with a geometry for good.
+// Pure module by design - geometry is data, and every function here is
+// array math (the check rig checks/geometry-check.ts runs it headless on
+// flux). The GPU buffer step lives in geometry-gpu.ts.
 
-import { createBuffer, destroyBuffer } from "@solidrt/core/gpu"
-import type { BufferId, IndexFormat, VertexAttribute } from "@solidrt/core/gpu"
-import { add, cross, normalize, sub } from "./math.ts"
-import type { Vec2, Vec3, Vec4 } from "./math.ts"
+import type { VertexAttribute } from "@solidrt/core/gpu"
+import { add, compose, cross, mat4, normalize, normalMatrix, sub, updateRotation, updateScale } from "./math.ts"
+import type { Quat, TransformUpdate, Vec2, Vec3, Vec4 } from "./math.ts"
 
 export type VertexLayout = "standard" | "colored"
 
@@ -61,8 +58,6 @@ export type Geometry = {
   layout?: VertexLayout
   /** Debug name for the lazily-created GPU buffers. */
   label?: string
-  _buffer?: BufferId
-  _index?: BufferId
   _bounds?: Float32Array
 }
 
@@ -94,42 +89,6 @@ export function geometryBounds(geometry: Geometry): Float32Array {
   return bounds
 }
 
-/** The geometry's GPU buffers, created on first use and cached on it,
- * plus the index format the draw entry must bind them with. */
-export function geometryBuffers(geometry: Geometry): {
-  buffer: BufferId
-  index: BufferId
-  indexFormat: IndexFormat
-} {
-  let buffer = geometry._buffer
-  let index = geometry._index
-  if (buffer === undefined || index === undefined) {
-    buffer = createBuffer(geometry.vertices, {
-      autoFree: false,
-      label: geometry.label ? geometry.label + "-verts" : undefined,
-    })
-    index = createBuffer(geometry.indices, {
-      autoFree: false,
-      label: geometry.label ? geometry.label + "-indices" : undefined,
-    })
-    geometry._buffer = buffer
-    geometry._index = index
-  }
-  return { buffer, index, indexFormat: geometry.indices instanceof Uint32Array ? "uint32" : "uint16" }
-}
-
-/**
- * Free the geometry's GPU buffers. Draw entries created from them hold
- * their own reference, so destruction order is safe; the geometry can be
- * used again afterwards (fresh buffers are created on next use).
- */
-export function disposeGeometry(geometry: Geometry): void {
-  if (geometry._buffer !== undefined) destroyBuffer(geometry._buffer)
-  if (geometry._index !== undefined) destroyBuffer(geometry._index)
-  geometry._buffer = undefined
-  geometry._index = undefined
-}
-
 /** Per-vertex aColor values for withColors/fillColors: a flat 4-per-vertex
  * array, or a callback deriving each vertex's vec4 from the vertex data. */
 export type ColorFill = ArrayLike<number> | ((index: number, pos: Vec3, normal: Vec3, uv: Vec2) => Vec4)
@@ -210,6 +169,94 @@ export function fillColors(vertices: Float32Array, fill: ColorFill, first = 0, c
   return vertices
 }
 
+/**
+ * Bake a placement (the setTransform shape: Euler XYZ radians or a
+ * quaternion, not both; number = uniform scale; absent = identity) into a
+ * geometry: a new geometry (the source is
+ * untouched, its GPU buffers stay independent) whose positions are moved
+ * by the transform and whose normals follow through the inverse-transpose,
+ * renormalized - correct under non-uniform scale. UVs, colors, indices and
+ * layout copy through. This is Three's `geometry.applyMatrix4`, the first
+ * half of authoring a static scene as data: transform each part into place,
+ * mergeGeometries the parts, draw one mesh.
+ */
+export function transformGeometry(geometry: Geometry, transform: TransformUpdate, label?: string): Geometry {
+  let rot: Quat = [0, 0, 0, 1]
+  updateRotation(rot, transform, "transformGeometry")
+  let scl: Vec3 = [1, 1, 1]
+  if (transform.scale !== undefined) updateScale(scl, transform.scale)
+  let m = compose(mat4(), transform.position ?? [0, 0, 0], rot, scl)
+  let n = normalMatrix(mat4(), m)
+  let stride = geometry.layout === "colored" ? COLORED_FLOATS : FLOATS_PER_VERTEX
+  let src = geometry.vertices
+  if (src.length % stride !== 0) {
+    throw new Error("transformGeometry: vertex data is not a whole number of " + (geometry.layout ?? "standard") + "-layout vertices")
+  }
+  let out = new Float32Array(src)
+  for (let i = 0; i < out.length; i += stride) {
+    let x = src[i]!, y = src[i + 1]!, z = src[i + 2]!
+    out[i] = m[0] * x + m[4] * y + m[8] * z + m[12]
+    out[i + 1] = m[1] * x + m[5] * y + m[9] * z + m[13]
+    out[i + 2] = m[2] * x + m[6] * y + m[10] * z + m[14]
+    let nx = src[i + 3]!, ny = src[i + 4]!, nz = src[i + 5]!
+    let tx = n[0] * nx + n[4] * ny + n[8] * nz
+    let ty = n[1] * nx + n[5] * ny + n[9] * nz
+    let tz = n[2] * nx + n[6] * ny + n[10] * nz
+    let len = Math.hypot(tx, ty, tz) || 1
+    out[i + 3] = tx / len
+    out[i + 4] = ty / len
+    out[i + 5] = tz / len
+  }
+  return {
+    vertices: out,
+    indices: geometry.indices,
+    layout: geometry.layout,
+    label: label ?? (geometry.label ? geometry.label + "-transformed" : undefined),
+  }
+}
+
+/**
+ * Concatenate geometries into one: vertices appended in order, indices
+ * offset to match, uint32 indices past 64k vertices. Every part must share
+ * one layout - a mixed list throws, because the strides differ and a merge
+ * that picked one would draw garbage, not a mesh missing a channel. The
+ * second half of authoring a static scene as data (Three's
+ * `BufferGeometryUtils.mergeGeometries`): the result is one draw entry and
+ * one uModel write however many parts went in, so only what actually moves
+ * keeps a node of its own.
+ */
+export function mergeGeometries(parts: Geometry[], label?: string): Geometry {
+  if (parts.length === 0) throw new Error("mergeGeometries: no parts")
+  let layout = parts[0]!.layout ?? "standard"
+  let stride = layout === "colored" ? COLORED_FLOATS : FLOATS_PER_VERTEX
+  let floats = 0
+  let indexCount = 0
+  for (let part of parts) {
+    if ((part.layout ?? "standard") !== layout) {
+      throw new Error("mergeGeometries: mixed layouts (" + layout + " and " + (part.layout ?? "standard") + ")")
+    }
+    if (part.vertices.length % stride !== 0) {
+      throw new Error("mergeGeometries: a part's vertex data is not a whole number of " + layout + "-layout vertices")
+    }
+    floats += part.vertices.length
+    indexCount += part.indices.length
+  }
+  let vertexCount = floats / stride
+  let vertices = new Float32Array(floats)
+  let indices = vertexCount > 65535 ? new Uint32Array(indexCount) : new Uint16Array(indexCount)
+  let vOffset = 0
+  let iOffset = 0
+  for (let part of parts) {
+    vertices.set(part.vertices, vOffset)
+    let base = vOffset / stride
+    let src = part.indices
+    for (let i = 0; i < src.length; i++) indices[iOffset + i] = src[i]! + base
+    vOffset += part.vertices.length
+    iOffset += src.length
+  }
+  return { vertices, indices, layout: parts[0]!.layout, label }
+}
+
 // Indices for a row-major (cellRows + 1) x (cellCols + 1) vertex grid: two
 // CCW triangles per cell, split across the row0col0-row1col1 diagonal -
 // the one quad pattern every grid generator here shares (rows run along

package/src/index.ts

@@ -5,18 +5,20 @@
 // without Solid components) and the component face (Scene/Mesh/Group/
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
-export { add, createGroup, createMesh, createScene, getRotation, lookAt, remove, setGeometry, setMaterial, setMeshParams, setRenderOrder, setTransform, setVisible, worldPosition } from "./scene.ts"
-export type { CameraUpdate, Hit, Mesh as MeshNode, Scene as SceneHandle, SceneHandlers, SceneNode, SceneOptions, ScenePointerEvent, TransformUpdate } from "./scene.ts"
-export { box, circle, cone, cylinder, disposeGeometry, fillColors, plane, ring, sphere, torus, torusKnot, withColors, FLOATS_PER_VERTEX, VERTEX_LAYOUTS } from "./geometry.ts"
+export { add, createGroup, createInstancedMesh, createMesh, createScene, disposeInstances, getRotation, lookAt, remove, setGeometry, setInstanceCount, setInstances, setMaterial, setMeshParams, setRenderOrder, setTransform, setVisible, worldPosition } from "./scene.ts"
+export type { CameraUpdate, Hit, InstancedMesh as InstancedMeshNode, InstancedMeshOptions, Mesh as MeshNode, MeshInstances, Scene as SceneHandle, SceneHandlers, SceneNode, SceneOptions, ScenePointerEvent, TransformUpdate } from "./scene.ts"
+export { disposeGeometry } from "./geometry-gpu.ts"
+export { box, circle, cone, cylinder, fillColors, geometryBounds, mergeGeometries, plane, ring, sphere, torus, torusKnot, transformGeometry, withColors, FLOATS_PER_VERTEX, VERTEX_LAYOUTS } from "./geometry.ts"
 export type { ColorFill, Geometry, VertexLayout } from "./geometry.ts"
+export { rayBoxDistance } from "./bvh.ts"
 export { fillet, roundRect, shape, triangulate } from "./profile.ts"
 export type { Profile, ProfilePoint } from "./profile.ts"
 export { extrude, lathe, pathFrames, sweep, tube } from "./sweep.ts"
 export type { PathFrames, PathPoint, SweepPath } from "./sweep.ts"
 export { shaderMaterial, shaderMaterialClass, unlit } from "./material.ts"
 export type { Material, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, UnlitOptions } from "./material.ts"
-export { Group, Mesh, PerspectiveCamera, Scene, useScene } from "./components.tsx"
-export type { MeshProps, PerspectiveCameraProps, PointerEventProps, SceneProps, TransformProps } from "./components.tsx"
+export { Group, InstancedMesh, Mesh, PerspectiveCamera, Scene, useScene } from "./components.tsx"
+export type { InstancedMeshProps, MeshProps, PerspectiveCameraProps, PointerEventProps, SceneProps, TransformProps } from "./components.tsx"
 export { createOrbitCamera } from "./orbit.ts"
 export type { OrbitCamera, OrbitCameraOptions, OrbitPose } from "./orbit.ts"
 // math's lookAt (the camera view matrix) stays on the /math subpath: the

package/src/material.ts

@@ -35,6 +35,7 @@ import type {
   ShaderStageId,
   TextureId,
   Topology,
+  VertexAttribute,
 } from "@solidrt/core/gpu"
 import { VERTEX_LAYOUTS } from "./geometry.ts"
 import type { VertexLayout } from "./geometry.ts"
@@ -59,6 +60,11 @@ export type Material = {
    * the scene draws this material's meshes after every opaque one, sorted
    * back-to-front by mesh origin, and re-sorts them when the camera moves. */
   transparent?: boolean
+  /** Per-instance attributes, when the material's pipeline declares them
+   * (shaderMaterialClass's `instanceAttributes`). Such a material draws
+   * instanced meshes only - createInstancedMesh supplies the record buffer,
+   * and createMesh meshes are rejected at add(). */
+  instanceAttributes?: VertexAttribute[]
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
@@ -226,6 +232,17 @@ export type ShaderMaterialClassOptions = {
    */
   vertex: string
   fragment: string
+  /**
+   * Per-instance attributes: the vertex stage reads these as `in` variables
+   * beside the layout's own, and each drawn instance gets one record from
+   * the mesh's instance buffer (interleaved floats in this order). A class
+   * with instance attributes makes INSTANCED materials: attach their meshes
+   * with createInstancedMesh, which carries the records - a createMesh mesh
+   * is rejected at add(). A per-instance transform is data, not a matrix:
+   * a position/yaw/scale record beats four vec4 columns for most fleets,
+   * and the composed uModel still places the whole population.
+   */
+  instanceAttributes?: VertexAttribute[]
   /** Blend over what is behind, with the scene sorting this material's
    * meshes back-to-front after the opaque ones (see Material.transparent).
    * Sets the pipeline defaults blend "alpha" and depthWrite false; the
@@ -298,6 +315,9 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   let normalMatrix = /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment)
   let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none")
   let depth = opts.depth ?? true
+  // An empty list declares nothing - same as absent (the engine requires an
+  // instance buffer exactly when attributes are declared).
+  let instanceAttributes = opts.instanceAttributes?.length ? opts.instanceAttributes.map(a => ({ ...a })) : undefined
   let pipelineFor = (): RenderPipelineId => {
     if (pipeline === undefined) {
       let vs = compileShader("vertex", opts.vertex, { header: needsHeader(opts.vertex) })
@@ -307,6 +327,7 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
       destroyShader(fs)
       pipeline = createRenderPipeline(program, {
         attributes: VERTEX_LAYOUTS[layout],
+        instanceAttributes,
         depth,
         // depthWrite needs a depth buffer, so the transparent default
         // only applies when there is one.
@@ -321,7 +342,7 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   }
   return {
     instance(inst = {}) {
-      return { normalMatrix, layout, transparent, pipeline: pipelineFor, params: inst.params ?? {}, textures: inst.textures }
+      return { normalMatrix, layout, transparent, instanceAttributes, pipeline: pipelineFor, params: inst.params ?? {}, textures: inst.textures }
     },
     dispose() {
       if (pipeline !== undefined) {

package/src/math.ts

@@ -213,6 +213,51 @@ export function quatNormalize(out: Quat, q: Quat): Quat {
   return out
 }
 
+/**
+ * A transform update - the shape setTransform writes and transformGeometry
+ * bakes. Absent keys mean "keep" (nodes) or identity (geometry).
+ */
+export type TransformUpdate = {
+  position?: Vec3
+  /** Euler radians in XYZ order (x first), Three's `Euler` default -
+   * converted to a quaternion on use. */
+  rotation?: Vec3
+  /** The rotation itself. Normalized on use, 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
+}
+
+/**
+ * Resolve an update's rotation into `out`: euler converted, quaternion
+ * normalized. Returns false (out untouched) when the update carries
+ * neither; throws when it carries both. `caller` names the verb in the
+ * error.
+ */
+export function updateRotation(out: Quat, update: TransformUpdate, caller: string): boolean {
+  let r = update.rotation
+  let q = update.quaternion
+  if (r !== undefined && q !== undefined) {
+    throw new Error("Pass rotation or quaternion to " + caller + ", not both")
+  }
+  if (r !== undefined) quatFromEuler(out, r)
+  else if (q !== undefined) quatNormalize(out, q)
+  else return false
+  return true
+}
+
+/** Expand an update's scale (number = uniform) into `out`. */
+export function updateScale(out: Vec3, scale: Vec3 | number): Vec3 {
+  if (typeof scale === "number") {
+    out[0] = scale; out[1] = scale; out[2] = scale
+  } else {
+    out[0] = scale[0]; out[1] = scale[1]; out[2] = scale[2]
+  }
+  return out
+}
+
 /**
  * Euler radians to a quaternion, in XYZ order: x applied first, then y,
  * then z (R = Rx * Ry * Rz on column vectors), Three's `Euler` default - a

package/src/scene.ts

@@ -19,15 +19,17 @@
 // each write lands here, the microtask syncs the affected uModels, and the
 // flush renders once that frame.
 
-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, 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, 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, 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"
@@ -57,6 +59,7 @@ 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
@@ -68,6 +71,7 @@ type SceneHooks = {
   _attach(mesh: Mesh): void
   _detach(mesh: Mesh): void
   _setParams(mesh: Mesh, params: ShaderParams): void
+  _setCount(mesh: Mesh): void
   _reorder(): void
 }
 
@@ -109,6 +113,10 @@ export type Mesh = SceneNode & {
    * 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). */
@@ -120,8 +128,35 @@ export type Mesh = SceneNode & {
   _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. */
@@ -276,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
 }
 
@@ -308,15 +344,147 @@ export function createMesh(geometry: Geometry, material: Material): Mesh {
   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)
@@ -352,18 +520,7 @@ 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).
@@ -377,11 +534,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 +546,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,15 +556,12 @@ 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
     }
   }
@@ -628,8 +775,17 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   // 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
@@ -712,8 +868,9 @@ 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
           }
@@ -763,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().
@@ -780,6 +960,7 @@ 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,
       })
       meshes.push(mesh)
@@ -793,6 +974,8 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     _detach(mesh) {
       if (mesh._entry !== null) {
         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--
@@ -809,6 +992,12 @@ 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()
@@ -1035,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],
@@ -1053,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