@solidrt/3d 0.0.49 → 0.0.50

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 +
@@ -42,8 +42,14 @@ blendMode and pointer events like any element. Design rationale:
   lazy, shared, and app-lifetime (owner-scoped free would break sharing);
   `disposeGeometry` frees them.
 - 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`) 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.
 
 ## Components
 
@@ -194,7 +200,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 +217,14 @@ 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).
 
 Background: `scene.setBackground(source | null)`, the `background` option
 on createScene, and the reactive `Scene` prop. Fragment GLSL drawn as the
@@ -250,9 +267,26 @@ system.
   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).
+- 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 +363,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 +403,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 +448,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,12 @@ 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
 `@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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -17,6 +17,6 @@
   ],
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.0",
-    "@solidrt/core": "0.0.49"
+    "@solidrt/core": "0.0.50"
   }
 }

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

@@ -17,6 +17,7 @@ import {
   setGeometry,
   setMaterial,
   setMeshParams,
+  setRenderOrder,
   setTransform,
   setVisible,
 } from "./scene.ts"
@@ -179,6 +180,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,6 +206,10 @@ 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))

package/src/index.ts

@@ -5,7 +5,7 @@
 // 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 { 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 type { ColorFill, Geometry, VertexLayout } from "./geometry.ts"
@@ -13,8 +13,8 @@ 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 { 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 { createOrbitCamera } from "./orbit.ts"

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,
@@ -55,6 +55,10 @@ 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
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
@@ -96,23 +100,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 +132,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 +146,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 +201,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 +226,16 @@ 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". */
+  /** 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 +244,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 +295,34 @@ 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
+  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],
+        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, pipeline: pipelineFor, params: inst.params ?? {}, textures: inst.textures }
     },
-    params: opts.params ?? {},
-    textures: opts.textures,
     dispose() {
       if (pipeline !== undefined) {
         destroyRenderPipeline(pipeline)
@@ -281,3 +335,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/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
+}

package/src/scene.ts

@@ -3,10 +3,12 @@
 // component boundary (components.tsx). A scene compiles to one draw
 // target: every mesh is one draw entry whose uModel (and, for materials
 // declaring it, uNormal) this module keeps in step with the tree, and the
-// camera is the target's SHARED uViewProj + uCamPos - one setTargetParams
-// per camera move, not one write per mesh. uCamPos rides unconditionally:
-// shared params tolerate zero coverage (stored and skipped until a
-// declaring material arrives), so no bookkeeping tracks who reads it.
+// camera is the target's SHARED uViewProj + uCamPos + uCamRight/uCamUp -
+// one setTargetParams per camera move, not one write per mesh. The
+// non-matrix names ride unconditionally: shared params tolerate zero
+// coverage (stored and skipped until a declaring material arrives), so no
+// bookkeeping tracks who reads them. scene.setParams merges app-owned
+// names into the same set.
 // Mutations batch to a microtask, so a burst of writes (a whole subtree
 // moved, many effects in one flush) syncs once.
 //
@@ -17,17 +19,18 @@
 // each write lands here, the microtask syncs the affected uModels, and the
 // flush renders once that frame.
 
-import { addDraw, createDrawTarget, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, setDrawParams, setDrawRange, setTargetParams, setTargetSize } from "@solidrt/core/gpu"
+import { 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 { getOwner, onCleanup } from "@solidrt/core"
 import type { PointerEvent as ElementPointerEvent } from "@solidrt/core"
 // The scene's lookAt() aims a node; math's builds a camera's view matrix -
 // the same pairing (and the same name) as Three's Object3D/Matrix4.
-import { compose, copy, eulerFromQuat, identity, invertAffine, lookAt as lookAtMatrix, mat4, multiply, normalMatrix, perspective, quatFromEuler, quatFromFrame, quatNormalize, transformPoint, transformVector } from "./math.ts"
+import { 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 type { Geometry } from "./geometry.ts"
 import { backgroundPipeline } from "./material.ts"
+import { orderEntries } from "./order.ts"
 import type { Material } from "./material.ts"
 import { createBvh, rayBoxDistance } from "./bvh.ts"
 
@@ -51,6 +54,9 @@ let upScratch: Vec3 = [0, 0, 0]
 let pickInv = mat4()
 let pickOrigin: Vec4 = [0, 0, 0, 0]
 let pickDir: Vec3 = [0, 0, 0]
+// setTransform's rotation compare happens AFTER conversion, so an euler and
+// the quaternion it produces are the same write. Nothing outlives the call.
+let rotScratch = quat()
 
 // The scene half a node needs to reach: attach/detach entries and schedule
 // a sync. Kept separate from the public Scene type so internals stay off
@@ -62,6 +68,7 @@ type SceneHooks = {
   _attach(mesh: Mesh): void
   _detach(mesh: Mesh): void
   _setParams(mesh: Mesh, params: ShaderParams): void
+  _reorder(): void
 }
 
 export type SceneNode = {
@@ -97,7 +104,18 @@ export type Mesh = SceneNode & {
   kind: "mesh"
   geometry: Geometry
   material: Material
+  /** Explicit draw-order key (default 0), Three's name: lower draws first.
+   * Sorts within the opaque group and within the transparent group; the
+   * transparent group always follows the opaque one. Set with setRenderOrder. */
+  renderOrder: number
   _entry: DrawId | null
+  /** material.transparent as of the last attach - the entry's actual
+   * pipeline state, and what _detach counts against (setMaterial swaps
+   * mesh.material before the rebuild). */
+  _transparent: boolean
+  /** World-space center of the geometry bounds, kept by the sync walk
+   * beside the picking leaf: the transparent sort key. */
+  _center: Vec3
   _hidden: boolean
   _fresh: boolean
   _params: ShaderParams | null
@@ -184,6 +202,15 @@ export type Scene = {
   /** Partial camera update; absent keys keep their current value. */
   setCamera(update: CameraUpdate): void
   setSize(width: number, height: number): void
+  /**
+   * Scene-wide uniforms: merge app-owned names into the target's SHARED
+   * params, beside the standard uViewProj/uCamPos/uCamRight/uCamUp the
+   * camera writes. One write per frame however many meshes read the name
+   * (a clock, a sun direction, fog) - the per-mesh channel is
+   * setMeshParams. Merge semantics, no unset; a material that does not
+   * declare a name simply skips it. Frame-rate-safe like setTransform.
+   */
+  setParams(params: ShaderParams): void
   /**
    * Set, replace, or remove (null) the scene's background: fragment GLSL
    * drawn as the FIRST entry of the scene's own pass - one target, no
@@ -279,7 +306,10 @@ export function createMesh(geometry: Geometry, material: Material): Mesh {
   let mesh = makeNode("mesh") as Mesh
   mesh.geometry = geometry
   mesh.material = material
+  mesh.renderOrder = 0
   mesh._entry = null
+  mesh._transparent = false
+  mesh._center = [0, 0, 0]
   mesh._hidden = false
   mesh._fresh = false
   mesh._params = null
@@ -340,33 +370,55 @@ export type TransformUpdate = {
  * Values are copied in; absent keys keep their current value. This is also
  * the frame-rate escape hatch: call it from onFrame on a node grabbed via
  * `ref`, bypassing signals entirely.
+ *
+ * A write that changes nothing schedules nothing, so driving every node
+ * unconditionally from onFrame costs only the compare for the nodes that
+ * did not move. Rotation is compared after conversion, so passing an euler
+ * equal to the node's current quaternion is also a no-op.
  */
 export function setTransform(node: SceneNode, update: TransformUpdate): void {
+  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
+  // same value, and an epsilon would need a scale-dependent one anyway.
+  let changed = false
   let p = update.position
-  if (p) {
+  if (p && (p[0] !== node.position[0] || p[1] !== node.position[1] || p[2] !== node.position[2])) {
     node.position[0] = p[0]
     node.position[1] = p[1]
     node.position[2] = p[2]
+    changed = true
   }
-  let r = update.rotation
-  let q = update.quaternion
-  if (r !== undefined && q !== undefined) {
-    throw new Error("Pass rotation or quaternion to setTransform, not both")
+  if (r !== undefined) quatFromEuler(rotScratch, r)
+  else if (q !== undefined) quatNormalize(rotScratch, q)
+  if (r !== undefined || q !== undefined) {
+    let n = node.quaternion
+    if (rotScratch[0] !== n[0] || rotScratch[1] !== n[1] || rotScratch[2] !== n[2] || rotScratch[3] !== n[3]) {
+      n[0] = rotScratch[0]
+      n[1] = rotScratch[1]
+      n[2] = rotScratch[2]
+      n[3] = rotScratch[3]
+      changed = true
+    }
   }
-  if (r !== undefined) quatFromEuler(node.quaternion, r)
-  else if (q !== undefined) quatNormalize(node.quaternion, q)
   let s = update.scale
   if (s !== undefined) {
-    if (typeof s === "number") {
-      node.scale[0] = s
-      node.scale[1] = s
-      node.scale[2] = s
-    } else {
-      node.scale[0] = s[0]
-      node.scale[1] = s[1]
-      node.scale[2] = s[2]
+    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
+      changed = true
     }
   }
+  if (!changed) return
   node._localDirty = true
   node._scene?._schedule()
 }
@@ -482,8 +534,15 @@ export function setVisible(node: SceneNode, visible: boolean): void {
   node._scene?._schedule()
 }
 
-/** Swap a mesh's geometry: its draw entry is rebuilt (appended last -
- * order is irrelevant while every entry is opaque and depth-tested). */
+/** Set a mesh's explicit draw-order key (see Mesh.renderOrder). */
+export function setRenderOrder(mesh: Mesh, order: number): void {
+  if (mesh.renderOrder === order) return
+  mesh.renderOrder = order
+  mesh._scene?._reorder()
+}
+
+/** Swap a mesh's geometry: its draw entry is rebuilt (the scene re-sorts
+ * the list, so the mesh keeps its place). */
 export function setGeometry(mesh: Mesh, geometry: Geometry): void {
   if (mesh.geometry === geometry) return
   mesh.geometry = geometry
@@ -545,11 +604,25 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   let capture = new Map<number, Mesh>()
   let hover = new Map<number, Mesh>()
 
-  // Live mesh entries in list (draw) order, so a background set after
-  // meshes exist can insert BEFORE the first one. Mesh entries append;
-  // rebuilds re-append; the background entry never joins this list.
-  let entryOrder: DrawId[] = []
+  // Live meshes (those holding a draw entry) in add order; the background
+  // entry never joins this list. Draw order is derived from it by
+  // orderEntries (order.ts) whenever orderDirty. Camera moves and
+  // transparent-mesh moves only dirty the order when two or more transparent
+  // meshes exist - fewer cannot change relative order.
+  let meshes: Mesh[] = []
+  let transparentCount = 0
+  let orderDirty = false
+  // The order last handed to the engine: a resort that lands on the same
+  // permutation (the common case under a moving camera) issues nothing.
+  let lastOrder: DrawId[] = []
   let background: { entry: DrawId; pipeline: RenderPipelineId; program: ProgramId } | null = null
+  let sortEntries = () => {
+    orderDirty = false
+    let order = orderEntries(meshes, view, background?.entry)
+    if (order.length === lastOrder.length && order.every((id, i) => id === lastOrder[i])) return
+    lastOrder = order
+    setDrawOrder(texture, order)
+  }
 
   // Reinsert or refit a mesh's broadphase leaf from its fresh world matrix:
   // the local box's center/extents carried through the absolute matrix (the
@@ -566,6 +639,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let wx = m[0] * cx + m[4] * cy + m[8] * cz + m[12]
     let wy = m[1] * cx + m[5] * cy + m[9] * cz + m[13]
     let wz = m[2] * cx + m[6] * cy + m[10] * cz + m[14]
+    mesh._center[0] = wx
+    mesh._center[1] = wy
+    mesh._center[2] = wz
     let rx = Math.abs(m[0]) * ex + Math.abs(m[4]) * ey + Math.abs(m[8]) * ez
     let ry = Math.abs(m[1]) * ex + Math.abs(m[5]) * ey + Math.abs(m[9]) * ez
     let rz = Math.abs(m[2]) * ex + Math.abs(m[6]) * ey + Math.abs(m[10]) * ez
@@ -610,7 +686,16 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       // holds. Entries are untouched - uModel is camera-independent, and
       // uCamPos is stored even when no current material declares it.
       cameraPending = false
-      setTargetParams(texture, { uViewProj: viewProj, uCamPos: eye })
+      // The camera basis rides along: the view matrix's first two rows are
+      // the camera's world-space right and up (no clip flip - that lives in
+      // the projection), so a billboard needs no reconstruction from uViewProj.
+      setTargetParams(texture, {
+        uViewProj: viewProj,
+        uCamPos: eye,
+        uCamRight: [view[0], view[4], view[8]],
+        uCamUp: [view[1], view[5], view[9]],
+      })
+      if (transparentCount > 1) orderDirty = true
     }
     let walk = (node: SceneNode, parentChanged: boolean, parentVisible: boolean) => {
       let changed = parentChanged
@@ -632,6 +717,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
             mesh._hidden = !shown
             if (shown) mesh._fresh = true
           }
+          if (changed && mesh._transparent && transparentCount > 1) orderDirty = true
           if (!mesh._hidden && (changed || mesh._fresh)) {
             if (mesh.material.normalMatrix) {
               setDrawParams(texture, mesh._entry, {
@@ -655,6 +741,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       for (let c of node.children) walk(c, changed, shown)
     }
     walk(root, false, true)
+    if (orderDirty) sortEntries()
   }
 
   let hooks: SceneHooks = {
@@ -695,7 +782,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         textures: mesh.material.textures,
         instanceCount: 0,
       })
-      entryOrder.push(mesh._entry)
+      meshes.push(mesh)
+      mesh._transparent = mesh.material.transparent === true
+      if (mesh._transparent) transparentCount++
+      orderDirty = true
       mesh._hidden = true
       mesh._fresh = true
       this._schedule()
@@ -703,8 +793,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     _detach(mesh) {
       if (mesh._entry !== null) {
         if (!disposed) removeDraw(texture, mesh._entry)
-        let i = entryOrder.indexOf(mesh._entry)
-        if (i >= 0) entryOrder.splice(i, 1)
+        let i = meshes.indexOf(mesh)
+        if (i >= 0) meshes.splice(i, 1)
+        if (mesh._transparent) transparentCount--
+        orderDirty = true
       }
       mesh._entry = null
       // The leaf goes with the entry: a geometry swap rebuilds the entry,
@@ -717,6 +809,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     _setParams(mesh, params) {
       if (mesh._entry !== null && !disposed) setDrawParams(texture, mesh._entry, params)
     },
+    _reorder() {
+      orderDirty = true
+      this._schedule()
+    },
   }
 
   let root = makeNode("group")
@@ -864,6 +960,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       cameraDirty = true
       hooks._schedule()
     },
+    setParams(params) {
+      if (!disposed) setTargetParams(texture, params)
+    },
     setBackground(source) {
       if (disposed) return
       if (background !== null) {
@@ -874,9 +973,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       }
       if (source === null) return
       let built = backgroundPipeline(source, (opts?.label ?? "scene") + "-background")
-      // First in list order: meshes append behind it forever (rebuilds
-      // re-append too), so pinning happens once, here.
-      let entry = addDraw(texture, built.pipeline, null, { vertexCount: 3, before: entryOrder[0] })
+      // First in list order: inserted before the first mesh entry, and every
+      // later sort keeps it there.
+      let entry = addDraw(texture, built.pipeline, null, { vertexCount: 3, before: meshes[0]?._entry ?? undefined })
       background = { entry, pipeline: built.pipeline, program: built.program }
     },
     project(point) {