@solidrt/3d 0.0.49 → 0.0.51

package/AGENTS.md

@@ -11,7 +11,7 @@ blendMode and pointer events like any element. Design rationale:
 
 - Two layers. The imperative core is Solid-free: `createScene`,
   `createMesh(geometry, material)`, `add`/`remove`, `setTransform`,
-  `lookAt`, `getRotation`, `setVisible` - plain objects with dirty flags, batched to a
+  `lookAt`, `getRotation`, `setVisible`, `setRenderOrder` - plain objects with dirty flags, batched to a
   microtask,
   one `setDrawParams` (uModel, plus uNormal for materials declaring it)
   per changed mesh and ONE `setTargetParams` (the shared uViewProj +
@@ -39,11 +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), `depth: true` + `cull: "back"`; an instance is
+  (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`, `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, which exits nonzero.
+  Extend the rig when you change the module.
 
 ## Components
 
@@ -52,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
@@ -155,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
@@ -194,7 +222,10 @@ Materials:
   at shaderMaterial() creation. The rest is opt-in by declare-and-use:
   `uniform vec3 uCamPos` (the camera's world position, shared and written
   with uViewProj - the specular/fresnel view vector is
-  `normalize(uCamPos - worldPos)`) and `uniform mat4 uNormal` (the world
+  `normalize(uCamPos - worldPos)`), `uniform vec3 uCamRight` / `uCamUp`
+  (the camera's world-space view axes, shared likewise - a billboard is
+  `center + uCamRight * x + uCamUp * y`; do NOT rebuild them from
+  uViewProj rows, that carries the clip flip) and `uniform mat4 uNormal` (the world
   inverse-transpose, written beside uModel for this material's meshes;
   take `mat3(uNormal)` - correct under non-uniform scale, where
   mat3(uModel) bends normals off the surface). Attributes come from the
@@ -208,6 +239,42 @@ Materials:
   with the `Mesh` `params` prop (same merge semantics - a key that
   disappears from the object keeps its old value; for per-frame values
   prefer `ref` + setMeshParams from onFrame, the setTransform split).
+  Scene-wide values (a clock, a sun direction, fog) go through
+  `scene.setParams({ uTime })` instead - one write for every mesh.
+- `shaderMaterialClass({ vertex, fragment, ...pipeline state })` - the
+  class/instance split for your own GLSL: compiles once, and
+  `cls.instance({ params?, textures? })` returns a Material sharing that
+  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
@@ -245,14 +312,46 @@ 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.
-- Alpha does not blend in v1: pipelines are opaque (`blend: "none"`), a
-  translucent color overwrites. Transparency waits on blend factors +
-  sorting (research note, staging step 4).
+- 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
+  `blend: "alpha"` and `depthWrite: false` (depth test stays on, so it hides
+  behind opaques without occluding other translucents). The one inference:
+  a `shaderMaterial` with any `blend` but "none" is transparent unless told
+  `transparent: false` - every blended draw belongs after the opaques, and
+  back-to-front is harmless for add/multiply. The scene owns the
+  order: background, opaque meshes by `renderOrder` then add order,
+  transparent meshes by `renderOrder` then back-to-front by the CENTER of
+  the mesh's world bounds in view space (not the origin: off-origin geometry
+  sorts by where it is; not the nearest bounds point: a big translucent
+  ground plane would cover the small translucents on it) - one `setDrawOrder` from sync() whenever the list changed, a
+  renderOrder changed, or (with two or more transparent meshes) the camera
+  or a transparent mesh moved, and skipped when the resort lands on the
+  permutation already issued. Per-mesh sort only: one non-convex translucent
+  mesh still overlaps itself in vertex order, and two large interpenetrating
+  translucents can sort wrong (center distance, not per-pixel) - that is the
+  engine contract, no OIT. A `shaderMaterial({ transparent: true })`
+  fragment must write PREMULTIPLIED output (`vec4(rgb * a, a)`).
 - Rotation is stored as a QUATERNION (`node.quaternion`, `[x, y, z, w]`,
   always unit). There is exactly one rotation field: no `node.rotation`
   shadowing it, because a second field is a second thing to go stale (an
@@ -329,9 +428,36 @@ system.
   camera writes (uEye-style per-mesh params are exactly the O(scene) cost
   the shared channel removed). Scene scale honestly: hundreds to a
   few thousand objects, bounded by the interpreter, not the GPU.
+- SCENE-WIDE uniforms go through that same shared channel via
+  `scene.setParams({ uTime })`, and this is the single highest-leverage
+  pattern in the library. It merges an app-owned name in beside
+  uViewProj/uCamPos/uCamRight/uCamUp - names merge, a target tolerates
+  zero coverage, neither side clobbers the other. One write per frame
+  however many meshes read it, with the motion itself in vertex shaders
+  off that one clock. `params`/`setMeshParams` is the PER-MESH answer and
+  is O(meshes) per frame; reach for it only when the value genuinely
+  differs per mesh. (`scene.texture` IS the draw target id, so
+  `setTargetParams(scene.texture, ...)` is the same write - setParams is
+  the sanctioned spelling.)
+- Vec3/Quat arguments are COPIED IN everywhere (`setTransform`, `lookAt`,
+  `setCamera`, params), so ONE scratch array reused every frame is safe -
+  allocating three arrays per node per frame is pure waste. The node's own
+  `position`/`quaternion`/`scale` are the live arrays: read them, do not
+  hand them out and do not mutate them (that write does not sync).
+- `setTransform` early-outs on an unchanged value (rotation compared AFTER
+  euler conversion), so driving every node unconditionally from `onFrame`
+  costs only the compare for nodes that did not move. Compares are exact,
+  like `setVisible`.
+- Per-generator conventions - orientation, UV mapping, which axis a solid
+  stands on, what a cap looks like - live on each generator's doc comment,
+  not here. They are consistent (`plane`/`circle`/`ring` face +z, `torus`
+  lies flat with the hole on y, discs and cylinder caps get a PLANAR disc
+  map inscribed in the unit square) but the doc comment is the source.
 - Entry rebuild order: `setGeometry`/`setMaterial` re-add the entry at the
-  list END. Irrelevant while everything is opaque + depth-tested; revisit
-  when transparency lands.
+  list END and dirty the order, so the next sync() re-sorts and the mesh
+  keeps its place. `_transparent` on the mesh is the flag AS ATTACHED
+  (setMaterial swaps `mesh.material` before the rebuild, so _detach must
+  not read the new material's flag).
 - `lathe` takes a CLOSED profile (a cross-section with thickness, or run
   to the axis at x = 0) - it is a solid of revolution, NOT Three's open
   polyline shell. An "open" outline must be closed by the author;
@@ -342,7 +468,14 @@ system.
   compile twice - no dedupe by source value (deliberate; hidden
   content-keyed caches are the anti-pattern the GPU layer avoids). Create
   one per look at app scope, share across meshes, `dispose()` when done
-  for good.
+  for good. Looks that differ only in params/textures are ONE
+  `shaderMaterialClass` and many `instance()`s - the app-owned split, not
+  a cache. A class instance has no `dispose` of its own; disposing the
+  class invalidates every instance.
+- A parameterised class whose variants (mapped/unmapped, ...) are SEPARATE
+  classes must have every variant reference every shared uniform it is
+  seeded with: a declared-but-unused per-entry name compiles out and
+  throws at add(). Open item: `okf/backlog/gpu-inactive-uniform-two-tier.md`.
 - The standard-set contract is checked TEXTUALLY at shaderMaterial()
   creation (uModel and uViewProj must appear in the vertex source) and
   strictly at add() for the per-entry names: a uModel or uNormal that is
@@ -380,9 +513,8 @@ system.
   Geometry instead.
 - The background covers the whole target with depth off, drawn first: it
   REPLACES the clearColor visually (the clear still runs; you just never
-  see it), and a translucent mesh does not blend over it in-pass (blend
-  is none|add today - the fade-over-backdrop look still needs the
-  two-layer composition until blend factors land).
+  see it), and a `transparent: true` mesh blends over it in-pass since the
+  background is always entry zero.
 - The background pipeline/program are SCENE-OWNED (unlike shared
   material pipelines): setBackground(null), replacement, and dispose()
   destroy them. Do not hand the background's pipeline to anything else.

package/README.md

@@ -62,9 +62,16 @@ bounding-box accurate in v1. A scene also takes a `background` - fragment
 GLSL drawn inside its own pass behind the meshes, replacing the stacked
 backdrop-texture pattern.
 Custom materials get a standard uniform set - per-mesh `uModel`/`uNormal`,
-shared `uViewProj`/`uCamPos`, each written once per change - plus your own
-uniforms per mesh, declaratively via the `params` prop on `<Mesh>` or
-imperatively via `setMeshParams` - and
+shared `uViewProj`/`uCamPos`/`uCamRight`/`uCamUp`, each written once per
+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 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.
@@ -74,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.49",
+  "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.49"
+    "@solidrt/core": "0.0.51"
   }
 }

package/src/bvh.ts

@@ -12,8 +12,8 @@
 // pays nothing. Storage is flat parallel arrays indexed by node id (no
 // per-node objects, no allocation at steady state past tree growth).
 //
-// Pure module by design: no engine imports, so the differential check rig
-// (checks/pick-check.ts) runs it under plain bun against a linear oracle.
+// Pure module by design: no GUI imports, so the differential check rig
+// (checks/pick-check.ts) runs it headless on flux against a linear oracle.
 
 /** Fat-margin fraction of a leaf's largest extent. Bigger = fewer
  * re-inserts while moving, worse query pruning; 5% is the usual trade. */

package/src/components.tsx

@@ -11,17 +11,22 @@ import type { Element, ParentComponent, TextureId, VoidComponent } from "@solidr
 import {
   add,
   createGroup,
+  createInstancedMesh,
   createMesh,
   createScene,
+  disposeInstances,
   remove,
   setGeometry,
+  setInstanceCount,
+  setInstances,
   setMaterial,
   setMeshParams,
+  setRenderOrder,
   setTransform,
   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"
@@ -179,6 +184,8 @@ export type MeshProps = TransformProps & PointerEventProps & {
    * changing every frame prefer `ref` + setMeshParams from onFrame, the
    * same split as setTransform. */
   params?: ShaderParams
+  /** Explicit draw-order key (setRenderOrder as a prop); default 0. */
+  renderOrder?: number
   ref?: (mesh: MeshNode) => void
 }
 
@@ -203,12 +210,84 @@ export let Mesh: VoidComponent<MeshProps> = props => {
       if (p !== undefined) setMeshParams(mesh, p)
     },
   )
+  createEffect(
+    () => props.renderOrder,
+    o => setRenderOrder(mesh, o ?? 0),
+  )
   syncNode(mesh, props)
   untrack(() => props.ref)?.(mesh)
   onCleanup(() => remove(mesh))
   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)
+}