@solidrt/3d 0.0.49 → 0.0.51

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, 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, unlit } from "./material.ts"
-export type { Material, 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 { shaderMaterial, shaderMaterialClass, unlit } from "./material.ts"
+export type { Material, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, UnlitOptions } from "./material.ts"
+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

@@ -7,15 +7,15 @@
 //
 // Colors are straight [r, g, b, a?] 0..1 at the API and premultiplied here
 // once, at the boundary (the engine's pixel contract). An alpha below 1
-// does NOT blend yet: v1 pipelines draw opaque (blend "none"), so a
-// translucent color overwrites what is behind it. Transparency arrives
-// with the blend-factor vocabulary and back-to-front sorting (see
-// okf/research/scene-graph-3d.md, staging step 4).
+// blends only on a `transparent: true` material (Three's rule: the flag is
+// explicit, alpha alone still draws opaque). Transparent materials build
+// their pipeline with blend "alpha" and depthWrite off, and the scene draws
+// their meshes after the opaque ones, sorted back-to-front per mesh.
 //
-// Custom looks need no material system: the raw layer (compileShader /
-// createRenderPipeline in @solidrt/core/gpu) is first-class, and a scene
-// draws into an ordinary draw target - a custom-shaded mesh is a future
-// material class here, or the app's own addDraw beside the scene's.
+// Custom looks get the same split through shaderMaterialClass (one
+// program, instance() per parameterisation); shaderMaterial is a class with
+// a single instance. The raw layer (compileShader / createRenderPipeline in
+// @solidrt/core/gpu) stays first-class beneath both.
 
 import {
   compileShader,
@@ -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"
@@ -55,6 +56,15 @@ export type Material = {
    * mesh whose geometry layout differs is rejected at add() - the strides
    * disagree, so a mismatch would render garbage, not just miss a channel. */
   layout?: VertexLayout
+  /** True when the pipeline blends over (blend "alpha", depthWrite off):
+   * 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
 }
@@ -96,23 +106,30 @@ const FRAGMENT_MAP_SRC = glsl`
 `
 
 let sharedVertex: ShaderStageId | undefined
-let pipelines: { color?: RenderPipelineId; map?: RenderPipelineId } = {}
+let pipelines: Partial<Record<UnlitClass, RenderPipelineId>> = {}
 
-function pipelineFor(kind: "color" | "map"): RenderPipelineId {
-  let existing = pipelines[kind]
+// One pipeline per unlit CLASS: fragment kind x transparency, since blend
+// state is pipeline state.
+type UnlitClass = "color" | "map" | "color-transparent" | "map-transparent"
+
+function pipelineFor(cls: UnlitClass): RenderPipelineId {
+  let existing = pipelines[cls]
   if (existing !== undefined) return existing
   if (sharedVertex === undefined) sharedVertex = compileShader("vertex", VERTEX_SRC, { header: true })
-  let fragment = compileShader("fragment", kind === "color" ? FRAGMENT_COLOR_SRC : FRAGMENT_MAP_SRC, {
+  let transparent = cls.endsWith("-transparent")
+  let fragment = compileShader("fragment", cls.startsWith("color") ? FRAGMENT_COLOR_SRC : FRAGMENT_MAP_SRC, {
     header: true,
   })
-  let program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + kind })
+  let program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + cls })
   let pipeline = createRenderPipeline(program, {
     attributes: VERTEX_LAYOUTS.standard,
     depth: true,
+    depthWrite: transparent ? false : undefined,
+    blend: transparent ? "alpha" : undefined,
     cull: "back",
-    label: "scene-unlit-" + kind,
+    label: "scene-unlit-" + cls,
   })
-  pipelines[kind] = pipeline
+  pipelines[cls] = pipeline
   return pipeline
 }
 
@@ -121,6 +138,9 @@ export type UnlitOptions = {
   color?: [number, number, number] | [number, number, number, number]
   /** A texture id to sample (tinted by `color` when both are given). */
   map?: TextureId
+  /** Blend over what is behind (color alpha and map alpha both count).
+   * Without it an alpha below 1 still draws opaque. See Material.transparent. */
+  transparent?: boolean
 }
 
 /**
@@ -132,10 +152,16 @@ export function unlit(opts: UnlitOptions = {}): Material {
   let color = opts.color ?? [1, 1, 1]
   let a = color.length === 4 ? color[3] : 1
   let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
+  let transparent = opts.transparent === true
   if (opts.map !== undefined) {
-    return { pipeline: () => pipelineFor("map"), params: { uColor }, textures: { uMap: opts.map } }
+    return {
+      pipeline: () => pipelineFor(transparent ? "map-transparent" : "map"),
+      params: { uColor },
+      textures: { uMap: opts.map },
+      transparent,
+    }
   }
-  return { pipeline: () => pipelineFor("color"), params: { uColor } }
+  return { pipeline: () => pipelineFor(transparent ? "color-transparent" : "color"), params: { uColor }, transparent }
 }
 
 // Mirrors the engine's own preamble rule: a source carrying its own
@@ -181,7 +207,9 @@ export function backgroundPipeline(fragment: string, label: string): { pipeline:
   return { pipeline, program }
 }
 
-export type ShaderMaterialOptions = {
+/** The class half of a shader material: sources and pipeline state, the
+ * things one compiled program fixes. */
+export type ShaderMaterialClassOptions = {
   /**
    * Vertex stage GLSL. MUST declare and use `uniform mat4 uModel` (the
    * mesh's world matrix, written per entry whenever the mesh moves) and
@@ -204,11 +232,27 @@ export type ShaderMaterialOptions = {
    */
   vertex: string
   fragment: string
-  /** Uniform seeds beyond the standard set; update per mesh later with
-   * setMeshParams. */
-  params?: ShaderParams
-  textures?: Record<string, TextureId>
-  /** Pipeline state; defaults match unlit: depth: true, cull: "back". */
+  /**
+   * 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
+   * fragment must write premultiplied output (`vec4(rgb * a, a)`). Defaults
+   * to true whenever `blend` is set to anything but "none": every blended
+   * draw belongs after the opaques so it depth-tests against them, and
+   * back-to-front is harmless for the order-independent modes. */
+  transparent?: boolean
+  /** Pipeline state; defaults match unlit: depth: true, cull: "back",
+   * and for transparent materials blend "alpha", depthWrite: false. */
   depth?: boolean
   depthWrite?: boolean
   blend?: BlendMode
@@ -217,18 +261,41 @@ export type ShaderMaterialOptions = {
   label?: string
 }
 
+/** The instance half of a shader material: uniform seeds and sampler
+ * bindings for one parameterisation of a class's program. */
+export type ShaderMaterialInstanceOptions = {
+  /** Uniform seeds beyond the standard set; update per mesh later with
+   * setMeshParams. */
+  params?: ShaderParams
+  textures?: Record<string, TextureId>
+}
+
+export type ShaderMaterialOptions = ShaderMaterialClassOptions & ShaderMaterialInstanceOptions
+
 /**
- * A material from your own GLSL: the custom-look escape hatch, first-class
- * next to unlit. Sources without a `#version` line get the standard
- * pipeline preamble (`fragColor`, `iResolution`).
- *
- * The INSTANCE is the pipeline handle: two calls with identical sources
- * compile two pipelines - there is no dedupe by source value (a hidden
- * cache keyed by content is the anti-pattern the GPU layer avoids
- * throughout). Create one per look at app scope, share it across meshes,
- * and `dispose()` it if the app is done with the look for good.
+ * One program and pipeline, many parameterisations: the class/instance
+ * split unlit has internally, for your own GLSL. `instance()` returns a
+ * Material sharing the class's pipeline with its own params/textures - the
+ * class compiles once, and dispose() is on the class alone (instances hold
+ * nothing of their own).
  */
-export function shaderMaterial(opts: ShaderMaterialOptions): Material {
+export type ShaderMaterialClass = {
+  instance(opts?: ShaderMaterialInstanceOptions): Material
+  /** Destroy the shared program and pipeline. Instances still in use draw
+   * nothing valid afterwards. */
+  dispose(): void
+}
+
+/**
+ * A material class from your own GLSL: sources without a `#version` line
+ * get the standard pipeline preamble (`fragColor`, `iResolution`). Two
+ * calls with identical sources compile two programs - there is no dedupe by
+ * source value (a hidden cache keyed by content is the anti-pattern the GPU
+ * layer avoids throughout); the class IS the app-owned split. Create one
+ * per program at app scope, `instance()` per look, and `dispose()` the class
+ * when the app is done with the look for good.
+ */
+export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMaterialClass {
   // The standard-set contract, checked where the mistake is made: a vertex
   // stage that never mentions the matrices cannot place meshes, and with
   // shared params skipping undeclared names the omission would otherwise
@@ -245,30 +312,38 @@ export function shaderMaterial(opts: ShaderMaterialOptions): Material {
   // Attributes live in the vertex stage only, so unlike the uNormal scan
   // there is nothing to look for in the fragment source.
   let layout: VertexLayout = /\baColor\b/.test(opts.vertex) ? "colored" : "standard"
+  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) })
+      let fs = compileShader("fragment", opts.fragment, { header: needsHeader(opts.fragment) })
+      program = linkProgram(vs, fs, { label: opts.label })
+      destroyShader(vs)
+      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.
+        depthWrite: opts.depthWrite ?? (transparent && depth ? false : undefined),
+        blend: opts.blend ?? (transparent ? "alpha" : undefined),
+        cull: opts.cull ?? "back",
+        topology: opts.topology,
+        label: opts.label,
+      })
+    }
+    return pipeline
+  }
   return {
-    normalMatrix: /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment),
-    layout,
-    pipeline() {
-      if (pipeline === undefined) {
-        let vs = compileShader("vertex", opts.vertex, { header: needsHeader(opts.vertex) })
-        let fs = compileShader("fragment", opts.fragment, { header: needsHeader(opts.fragment) })
-        program = linkProgram(vs, fs, { label: opts.label })
-        destroyShader(vs)
-        destroyShader(fs)
-        pipeline = createRenderPipeline(program, {
-          attributes: VERTEX_LAYOUTS[layout],
-          depth: opts.depth ?? true,
-          depthWrite: opts.depthWrite,
-          blend: opts.blend,
-          cull: opts.cull ?? "back",
-          topology: opts.topology,
-          label: opts.label,
-        })
-      }
-      return pipeline
+    instance(inst = {}) {
+      return { normalMatrix, layout, transparent, instanceAttributes, pipeline: pipelineFor, params: inst.params ?? {}, textures: inst.textures }
     },
-    params: opts.params ?? {},
-    textures: opts.textures,
     dispose() {
       if (pipeline !== undefined) {
         destroyRenderPipeline(pipeline)
@@ -281,3 +356,20 @@ export function shaderMaterial(opts: ShaderMaterialOptions): Material {
     },
   }
 }
+
+/**
+ * A material from your own GLSL: the custom-look escape hatch, first-class
+ * next to unlit. A class with a single instance - `shaderMaterialClass()`
+ * is the form for one program with many parameterisations.
+ *
+ * The INSTANCE is the pipeline handle: two calls with identical sources
+ * compile two pipelines - there is no dedupe by source value. Create one
+ * per look at app scope, share it across meshes, and `dispose()` it if the
+ * app is done with the look for good.
+ */
+export function shaderMaterial(opts: ShaderMaterialOptions): Material {
+  let cls = shaderMaterialClass(opts)
+  let material = cls.instance(opts)
+  material.dispose = cls.dispose
+  return material
+}

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/order.ts

@@ -0,0 +1,51 @@
+// Draw-list ordering for a scene: a pure function of the live meshes and the
+// camera's view matrix, with no GUI import, so the check rig
+// (checks/order-check.ts) runs it headless on flux against a linear oracle.
+// The scene calls it whenever the order is dirty and hands the result to
+// setDrawOrder.
+
+import type { Mat4, Vec3 } from "./math.ts"
+
+/** The slice of a Mesh the sort reads (field names match Mesh so the
+ * scene passes its meshes straight through). */
+export type Orderable<T> = {
+  _entry: T | null
+  _transparent: boolean
+  renderOrder: number
+  _center: Vec3
+}
+
+/**
+ * Draw order: `first` (the background entry, if any), then opaque meshes by
+ * renderOrder with add order within a key, then transparent meshes by
+ * renderOrder then back-to-front by the view-space depth of the world-bounds
+ * center. The center, not the origin (Three's key), so geometry built
+ * off-origin sorts by where it is; and not the nearest bounds point, which
+ * would draw a large translucent ground plane over the small translucents
+ * resting on it. Per-mesh only: no per-triangle sort, no OIT.
+ */
+export function orderEntries<T>(meshes: readonly Orderable<T>[], view: Mat4, first?: T): T[] {
+  let opaque: Orderable<T>[] = []
+  let transparent: Orderable<T>[] = []
+  for (let m of meshes) {
+    if (m._entry === null) continue
+    ;(m._transparent ? transparent : opaque).push(m)
+  }
+  // Array sort is stable, so equal keys keep add order.
+  opaque.sort((a, b) => a.renderOrder - b.renderOrder)
+  if (transparent.length > 1) {
+    // The camera looks down -z in view space, so farther is more negative
+    // and ascending depth is back-to-front.
+    let depth = new Map<Orderable<T>, number>()
+    for (let m of transparent) {
+      let c = m._center
+      depth.set(m, view[2] * c[0] + view[6] * c[1] + view[10] * c[2] + view[14])
+    }
+    transparent.sort((a, b) => a.renderOrder - b.renderOrder || depth.get(a)! - depth.get(b)!)
+  }
+  let order: T[] = []
+  if (first !== undefined) order.push(first)
+  for (let m of opaque) order.push(m._entry!)
+  for (let m of transparent) order.push(m._entry!)
+  return order
+}