@aardworx/wombat.rendering 0.19.10 → 0.19.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aardworx/wombat.rendering",
-  "version": "0.19.10",
+  "version": "0.19.12",
   "description": "WebGPU rendering layer for the Wombat TypeScript stack — RenderObject/RenderTask/runtime + window glue, port of Aardvark.Rendering's lower layers on top of WebGPU and wombat.shader.",
   "license": "MIT",
   "author": "krauthaufen",

package/src/core/renderObject.ts

@@ -102,4 +102,13 @@ export interface RenderObject {
     readonly depthWrite?:     import("../runtime/derivedModes/rule.js").DerivedModeRule<"depthWrite">;
     readonly alphaToCoverage?: import("../runtime/derivedModes/rule.js").DerivedModeRule<"alphaToCoverage">;
   };
+  /**
+   * GPU transform propagation: this RO's `Model` as an ancestor trafo CHAIN
+   * (root→leaf order, constant runs folded) instead of a single composed
+   * `ModelTrafo` aval. The scene-graph emits this so a shared root trafo over
+   * N objects never fans out to N composed CPU avals — the heap composes each
+   * RO's Model on the GPU. Heap-path only (the legacy path composes on CPU).
+   * See docs/gpu-transform-propagation.md.
+   */
+  readonly modelChain?: readonly aval<import("@aardworx/wombat.base").Trafo3d>[];
 }

package/src/resources/preparedRenderObject.ts

@@ -35,6 +35,7 @@ import type { Type } from "@aardworx/wombat.shader/ir";
 import { isDerivedRule } from "../runtime/derivedUniforms/rule.js";
 import { STANDARD_DERIVED_RULES, STANDARD_TRAFO_LEAVES } from "../runtime/derivedUniforms/recipes.js";
 import { interpretExpr } from "../runtime/derivedUniforms/cpuEval.js";
+import { evaluateModeRule } from "../runtime/derivedModes/cpuEval.js";
 import { prepareAdaptiveBuffer } from "./adaptiveBuffer.js";
 import { prepareAdaptiveTexture } from "./adaptiveTexture.js";
 import { prepareAdaptiveSampler } from "./adaptiveSampler.js";
@@ -369,6 +370,8 @@ export class PreparedRenderObject {
     pipelineCtx: PipelineBuildContext,
     pipelineState: import("../core/index.js").PipelineState,
     private readonly active: aval<boolean> | undefined = undefined,
+    private readonly modeRules: import("../core/renderObject.js").RenderObject["modeRules"] = undefined,
+    private readonly modeUniformReader: ((name: string, token: AdaptiveToken) => unknown) | undefined = undefined,
   ) {
     this.groups = groups;
     this._pipelineCtx = pipelineCtx;
@@ -381,6 +384,28 @@ export class PreparedRenderObject {
   /** Internal — exposed for tests. The PipelineState the RO is reading. */
   get pipelineState(): import("../core/index.js").PipelineState { return this._pipelineState; }
 
+  /**
+   * Override pipeline-axis values with CPU-evaluated derived-mode rules.
+   * Each rule reads per-RO uniforms + the SG-declared default; evaluating
+   * under `token` registers the dependency so a uniform/declared change
+   * re-keys the pipeline (recompile via the snapshot cache). The heap path
+   * does this on a GPU partition kernel — this is the legacy per-RO answer.
+   */
+  private applyModeRules(snap: PipelineSnap, token: AdaptiveToken): PipelineSnap {
+    const mr = this.modeRules;
+    const ru = this.modeUniformReader;
+    if (mr === undefined || ru === undefined) return snap;
+    const read = (name: string): unknown => ru(name, token);
+    const ov: Record<string, unknown> = {};
+    if (mr.cull            !== undefined) ov.cullMode        = evaluateModeRule(mr.cull, read, token);
+    if (mr.frontFace       !== undefined) ov.frontFace       = evaluateModeRule(mr.frontFace, read, token);
+    if (mr.topology        !== undefined) ov.topology        = evaluateModeRule(mr.topology, read, token);
+    if (mr.depthWrite      !== undefined) ov.depthWrite      = evaluateModeRule(mr.depthWrite, read, token);
+    if (mr.depthCompare    !== undefined) ov.depthCompare    = evaluateModeRule(mr.depthCompare, read, token);
+    if (mr.alphaToCoverage !== undefined) ov.alphaToCoverage = evaluateModeRule(mr.alphaToCoverage, read, token);
+    return { ...snap, ...ov };
+  }
+
   acquire(): void {
     for (const r of this.vertexBuffers.values()) r.acquire();
     if (this.indexBuffer !== undefined) this.indexBuffer.acquire();
@@ -399,7 +424,7 @@ export class PreparedRenderObject {
    * surrounding sort / record path can read it without forcing.
    */
   update(token: AdaptiveToken): void {
-    const snap = snapshotPipeline(this._pipelineState, token);
+    const snap = this.applyModeRules(snapshotPipeline(this._pipelineState, token), token);
     const key = pipelineKeyOf(snap);
     let pipeline = this._pipelineCache.get(key);
     if (pipeline === undefined) {
@@ -751,6 +776,20 @@ export function prepareRenderObject(
     ...(opts.effectId !== undefined ? { effectId: opts.effectId } : {}),
   };
 
+  // Derived-mode rules (cull/frontFace/… as a function of per-RO uniforms)
+  // are evaluated CPU-side in the legacy path. Build a uniform reader over
+  // the RO's provider (resolving nested derived-uniform rules too).
+  let modeUniformReader: ((name: string, token: AdaptiveToken) => unknown) | undefined;
+  if (obj.modeRules !== undefined) {
+    const uniProv = asUniformProvider(obj.uniforms);
+    modeUniformReader = (name: string, token: AdaptiveToken): unknown => {
+      const v = uniProv.tryGet(name);
+      if (v === undefined) return undefined;
+      if (isDerivedRule(v)) return interpretExpr(v.ir, (n) => readLeaf(n, uniProv, effect.avalBindings, token));
+      return (v as aval<unknown>).getValue(token);
+    };
+  }
+
   return new PreparedRenderObject(
     device,
     vertexBindings, vertexBuffers, vertexViews,
@@ -760,6 +799,8 @@ export function prepareRenderObject(
     pipelineCtx,
     obj.pipelineState,
     obj.active,
+    obj.modeRules,
+    modeUniformReader,
   );
 }
 

package/src/runtime/derivedModes/axisEnum.ts

@@ -0,0 +1,65 @@
+// Canonical per-axis enum tables + value mapping for derived modes.
+//
+// Used by the legacy CPU-eval path (derivedModes/cpuEval). heapScene's
+// GPU-routing path keeps a parallel inline copy of this table + helpers
+// (heapScene.ts ~AXIS_ENUM_TABLE / resolveAxisValue / resolveDeclaredU32);
+// they must stay in sync — fold both onto this module when convenient.
+// The index↔value mapping is the WebGPU enum order; a rule body returns a
+// u32 index and the renderer maps it to the concrete mode value here.
+
+import type { aval, AdaptiveToken } from "@aardworx/wombat.adaptive";
+import type { DerivedModeRule, ModeAxis } from "./rule.js";
+
+/** u32 index → mode value, per axis. `blend` has no canonical table —
+ *  blend rules return object literals directly (see resolveAxisValue). */
+export const AXIS_ENUM_TABLE: { readonly [A in ModeAxis]: ReadonlyArray<unknown> } = {
+  cull:            ["none", "front", "back"],
+  frontFace:       ["ccw", "cw"],
+  topology:        ["point-list", "line-list", "line-strip", "triangle-list", "triangle-strip"],
+  depthCompare:    ["never", "less", "equal", "less-equal", "greater", "not-equal", "greater-equal", "always"],
+  depthWrite:      [false, true],
+  alphaToCoverage: [false, true],
+  blend:           [],
+};
+
+/**
+ * Map a rule's resolved output to its axis-shape value:
+ *  - object → already the full axis value (e.g. a blend AttachmentBlend).
+ *  - number → enum-table lookup for enum axes; pass-through otherwise.
+ */
+export function resolveAxisValue<A extends ModeAxis>(rule: DerivedModeRule<A>, value: unknown): unknown {
+  if (typeof value === "object" && value !== null) return value;
+  if (typeof value === "number") {
+    const table = AXIS_ENUM_TABLE[rule.axis];
+    if (table.length > 0) {
+      const v = table[value];
+      if (v !== undefined) return v;
+    }
+    return value;
+  }
+  return value;
+}
+
+/**
+ * Resolve a rule's `declared` SG-context value to its u32 index:
+ *  - omitted → 0 (axis canonical zero).
+ *  - number  → passed through.
+ *  - aval / string / boolean → looked up in the canonical enum table.
+ */
+export function declaredToU32<A extends ModeAxis>(rule: DerivedModeRule<A>, tok: AdaptiveToken): number {
+  const d = rule.declared;
+  if (d === undefined) return 0;
+  const v = (typeof d === "object" && d !== null && "getValue" in (d as object))
+    ? (d as aval<unknown>).getValue(tok)
+    : d;
+  if (typeof v === "number") return v >>> 0;
+  const table = AXIS_ENUM_TABLE[rule.axis];
+  if (table.length === 0) {
+    throw new Error(`derivedModes: axis '${rule.axis}' has no canonical enum table; pass \`declared\` as a u32 index or omit it`);
+  }
+  const i = table.indexOf(v);
+  if (i < 0) {
+    throw new Error(`derivedModes: declared value '${String(v)}' for axis '${rule.axis}' not in canonical enum table ${JSON.stringify(table)}`);
+  }
+  return i;
+}

package/src/runtime/derivedModes/cpuEval.ts

@@ -0,0 +1,104 @@
+// CPU evaluation of a derived-MODE rule for the legacy per-RO path.
+//
+// A `derivedMode(...)` rule is a RuleExpr whose body computes a pipeline-axis
+// value (cull / frontFace / …) from per-RO uniforms (e.g. determinant of the
+// model matrix) and the SG-declared default. The heap path lowers this to a
+// GPU partition kernel; the legacy per-RO path has no kernel, so we evaluate
+// the rule body on the CPU here — the "v1 evaluates rules CPU-side" design in
+// core/renderObject.ts.
+//
+// Reuses the matrix-aware expression interpreter (derivedUniforms/cpuEval) and
+// adds a small Stmt walker (locals + control flow) plus user-function `Call`
+// resolution against the rule's own Module (helpers like `flipCull` are NOT
+// inlined — they're separate Function items in template.values).
+
+import type { Expr, Stmt, ValueDef } from "@aardworx/wombat.shader/ir";
+import type { AdaptiveToken } from "@aardworx/wombat.adaptive";
+import { interpretExpr, type EvalValue } from "../derivedUniforms/cpuEval.js";
+import type { DerivedModeRule, ModeAxis, ModeValue } from "./rule.js";
+import { declaredToU32, resolveAxisValue } from "./axisEnum.js";
+
+const NO_RETURN = Symbol("no-return");
+type RunResult = EvalValue | typeof NO_RETURN;
+
+interface FnDef { readonly params: readonly string[]; readonly body: Stmt; }
+
+function truthy(v: EvalValue): boolean {
+  return typeof v === "boolean" ? v : typeof v === "number" ? v !== 0 : true;
+}
+
+/**
+ * Evaluate a derived-mode rule to its concrete axis value for one RO.
+ * `readUniform(name)` returns the RO's current value for a `u.<name>` leaf
+ * (Trafo3d / M44f / number / …); reading it under `token` registers the
+ * dependency so the pipeline re-keys when it changes. Returns the mapped
+ * mode value (e.g. "back", or `true` for depthWrite).
+ */
+export function evaluateModeRule<A extends ModeAxis>(
+  rule: DerivedModeRule<A>,
+  readUniform: (name: string) => unknown,
+  token: AdaptiveToken,
+): ModeValue<A> {
+  // Collect helper functions + the entry body from the rule's Module.
+  const fns = new Map<string, FnDef>();
+  let body: Stmt | undefined;
+  for (const v of rule.expr.template.values as readonly ValueDef[]) {
+    if (v.kind === "Function") fns.set(v.signature.name, { params: v.signature.parameters.map((p) => p.name), body: v.body });
+    else if (v.kind === "Entry") body = v.entry.body;
+  }
+  if (body === undefined) {
+    throw new Error(`derivedModes: rule for axis '${rule.axis}' has no Entry in its template`);
+  }
+
+  const declaredU32 = declaredToU32(rule, token);
+  const readLeaf = (name: string): unknown => (name === "declared" ? declaredU32 : readUniform(name));
+
+  // Mutually-recursive: an expr `Call` runs a function body; a function body
+  // evaluates exprs via interpretExpr with `callFn` wired back here.
+  const callFn = (name: string, args: EvalValue[]): EvalValue => {
+    const fn = fns.get(name);
+    if (fn === undefined) throw new Error(`derivedModes: rule calls unknown function '${name}'`);
+    const locals = new Map<string, EvalValue>();
+    fn.params.forEach((p, i) => { if (args[i] !== undefined) locals.set(p, args[i]!); });
+    return evalBody(fn.body, locals);
+  };
+  const evalExpr = (e: Expr, locals: Map<string, EvalValue>): EvalValue =>
+    interpretExpr(e, readLeaf, { locals, callFn });
+
+  const run = (s: Stmt, locals: Map<string, EvalValue>): RunResult => {
+    switch (s.kind) {
+      case "Sequential":
+      case "Isolated": {
+        for (const c of s.body) { const r = run(c, locals); if (r !== NO_RETURN) return r; }
+        return NO_RETURN;
+      }
+      case "Declare": {
+        if (s.init !== undefined && s.init.kind === "Expr") locals.set(s.var.name, evalExpr(s.init.value, locals));
+        return NO_RETURN;
+      }
+      case "Write": {
+        if (s.target.kind === "LVar") locals.set(s.target.var.name, evalExpr(s.value, locals));
+        return NO_RETURN;
+      }
+      case "If": {
+        if (truthy(evalExpr(s.cond, locals))) return run(s.then, locals);
+        return s.else !== undefined ? run(s.else, locals) : NO_RETURN;
+      }
+      case "ReturnValue": return evalExpr(s.value, locals);
+      case "Expression":
+      case "Nop":
+      case "Return":
+        return NO_RETURN;
+      default:
+        throw new Error(`derivedModes: unsupported statement '${s.kind}' in rule body`);
+    }
+  };
+  const evalBody = (b: Stmt, locals: Map<string, EvalValue>): EvalValue => {
+    const r = run(b, locals);
+    if (r === NO_RETURN) throw new Error(`derivedModes: rule body for axis '${rule.axis}' produced no return value`);
+    return r;
+  };
+
+  const raw = evalBody(body, new Map());
+  return resolveAxisValue(rule, raw) as ModeValue<A>;
+}

package/src/runtime/derivedUniforms/codegen.ts

@@ -23,6 +23,18 @@ export interface UberKernel {
   readonly strideU32: number;
 }
 
+/**
+ * Reserved rule id for the built-in variable-length trafo-chain arm (GPU
+ * transform propagation). A chain record is laid out as
+ *   [ CHAIN_RULE_ID, out_slot, count, link0, link1, … ]
+ * where each `linkK` is a Constituent handle. The arm folds the df32 product
+ * `link0 · link1 · … · link(count-1)` and writes it (collapsed) to `out_slot`.
+ * One arm handles every chain length, so distinct SG ancestor paths don't each
+ * spawn a kernel arm / recompile. Kept far above the registry's monotonic ids
+ * (which start at 0) so it can never collide. See docs/gpu-transform-propagation.md.
+ */
+export const CHAIN_RULE_ID = 0x7fffffff;
+
 // ─── Rule-shape classification ────────────────────────────────────────
 
 type Shape =
@@ -136,6 +148,12 @@ fn load_entry_mat4(h: u32, r: u32, c: u32) -> vec2<f32> {
 fn write_mat4_entry(out_byte: u32, r: u32, c: u32, v: f32) {
   MainHeap[(out_byte >> 2u) + r * 4u + c] = v;
 }
+// Write one df32 mat4 entry (r,c) into a constituent slot — keeps both hi+lo
+// so a downstream §7 pass reads it at full df32 precision. Used by the chain
+// pass, whose output IS a per-RO Model constituent (not a collapsed uniform).
+fn write_constituent_entry(slot: u32, r: u32, c: u32, e: vec2<f32>) {
+  Constituents[slot * 16u + r * 4u + c] = e;
+}
 fn write_mat3_entry(out_byte: u32, r: u32, c: u32, v: f32) {
   // std140 mat3<f32>: 3 rows × 4-float stride; the 4th column per row is left untouched.
   MainHeap[(out_byte >> 2u) + r * 4u + c] = v;
@@ -144,7 +162,7 @@ fn write_mat3_entry(out_byte: u32, r: u32, c: u32, v: f32) {
 
 function bindings(strideU32: number): string {
   return /* wgsl */ `
-@group(0) @binding(0) var<storage, read>       Constituents: array<vec2<f32>>;
+@group(0) @binding(0) var<storage, read_write> Constituents: array<vec2<f32>>;
 @group(0) @binding(1) var<storage, read_write> MainHeap:     array<f32>;
 @group(0) @binding(2) var<storage, read>       RecordData:   array<u32>;
 struct CountUniform { count: u32 }
@@ -214,6 +232,43 @@ function emitMatMulChainArm(id: number, n: number): string {
   return `\nfn arm_${id}(${params}, out_byte: u32) {\n${body}}\n`;
 }
 
+/** Built-in `CHAIN` arm (GPU transform propagation): variable-length df32
+ *  matmul chain read straight from the record. `RecordData[base+2]` = count;
+ *  `RecordData[base+3+k]` = link k (Constituent handle). Folds
+ *  P = L0·L1·…·L(count-1) in df32 and writes it — keeping BOTH hi+lo — into the
+ *  output CONSTITUENT slot (`out_slot` = the out handle's payload), so a later
+ *  §7 pass reads it at full df32 precision. The inverse half is produced by a
+ *  second chain record over the links' inv slots in reverse order (same arm).
+ *  P starts at identity so count==0 yields identity. */
+const CHAIN_ARM = /* wgsl */ `
+fn arm_chain(base: u32, out_slot: u32) {
+  let count = RecordData[base + 2u];
+  var P: array<vec2<f32>, 16>;
+  for (var i: u32 = 0u; i < 16u; i = i + 1u) { P[i] = vec2<f32>(0.0, 0.0); }
+  P[0] = vec2<f32>(1.0, 0.0); P[5] = vec2<f32>(1.0, 0.0);
+  P[10] = vec2<f32>(1.0, 0.0); P[15] = vec2<f32>(1.0, 0.0);
+  for (var k: u32 = 0u; k < count; k = k + 1u) {
+    let h = RecordData[base + 3u + k];
+    var Q: array<vec2<f32>, 16>;
+    for (var r: u32 = 0u; r < 4u; r = r + 1u) {
+      for (var c: u32 = 0u; c < 4u; c = c + 1u) {
+        var acc = vec2<f32>(0.0, 0.0);
+        for (var t: u32 = 0u; t < 4u; t = t + 1u) {
+          acc = df_add(acc, df_mul(P[r * 4u + t], load_entry_mat4(h, t, c)));
+        }
+        Q[r * 4u + c] = acc;
+      }
+    }
+    P = Q;
+  }
+  for (var r: u32 = 0u; r < 4u; r = r + 1u) {
+    for (var c: u32 = 0u; c < 4u; c = c + 1u) {
+      write_constituent_entry(out_slot, r, c, P[r * 4u + c]);
+    }
+  }
+}
+`;
+
 // ─── Generic path: arbitrary IR lowered via the wgsl printer (f32) ────
 //
 // The rule's IR is rewritten so each input leaf — `ReadInput("Uniform", x)` or
@@ -454,13 +509,16 @@ export function buildUberKernel(registry: DerivedUniformRegistry, strideU32: num
 
   const arms = entries.map((e, i) => emitArm(e, shapes[i]!)).join("");
   const cases = entries.map((e, i) => emitCase(e, shapes[i]!)).join("\n");
-  const needsDf32 = shapes.some((s) => s.kind === "matmulChain");
+  // The CHAIN arm is always present (GPU transform propagation) and always
+  // needs the df32 library.
+  const needsDf32 = true;
 
   const wgsl = `${bindings(strideU32)}
 ${needsDf32 ? DF32_LIB : ""}
 ${HANDLE_HELPERS}
 ${loadersStorers}
 ${arms}
+${CHAIN_ARM}
 @compute @workgroup_size(64)
 fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
   if (gid.x >= Count.count) { return; }
@@ -468,6 +526,7 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
   let rule_id = RecordData[base];
   let out_byte = RecordData[base + 1u] & SLOT_PAYLOAD_MASK;
   switch rule_id {
+    case ${CHAIN_RULE_ID >>> 0}u: { arm_chain(base, out_byte); }
 ${cases}
     default: { return; }
   }

package/src/runtime/derivedUniforms/cpuEval.ts

@@ -198,7 +198,19 @@ function intrinsic(name: string, a: EvalValue[]): EvalValue {
  * `readLeaf`. Returns a host double value (`M44d` / `V3d` / number / …) that
  * `writeField` narrows to f32 when packing the UBO.
  */
-export function interpretExpr(ir: Expr, readLeaf: LeafReader): EvalValue {
+/**
+ * Optional evaluation context. `locals` resolves `Var` nodes (function
+ * params / `let` bindings); `callFn` resolves a user-function `Call` to a
+ * value (its name + already-evaluated args). Derived UNIFORMS pass neither
+ * (their rules are leaf-and-op only); derived MODES pass both (rule bodies
+ * have locals and call helpers like `flipCull`). See derivedModes/cpuEval.
+ */
+export interface EvalOpts {
+  readonly locals?: ReadonlyMap<string, EvalValue>;
+  readonly callFn?: (name: string, args: EvalValue[]) => EvalValue;
+}
+
+export function interpretExpr(ir: Expr, readLeaf: LeafReader, opts: EvalOpts = {}): EvalValue {
   const ev = (e: Expr): EvalValue => {
     switch (e.kind) {
       case "Const": {
@@ -208,11 +220,21 @@ export function interpretExpr(ir: Expr, readLeaf: LeafReader): EvalValue {
         throw new Error("derived eval: null const");
       }
       case "ReadInput": {
-        if (e.scope !== "Uniform") throw new Error("derived eval: non-uniform leaf scope " + e.scope);
+        // Scope-agnostic: the readLeaf decides what a name resolves to
+        // (uniforms for derived uniforms; uniforms + `declared` for modes).
         const raw = readLeaf(e.name);
-        if (raw === undefined) throw new Error("derived eval: missing uniform leaf '" + e.name + "'");
+        if (raw === undefined) throw new Error("derived eval: missing leaf '" + e.name + "'");
         return coerce(raw, e.type);
       }
+      case "Var": {
+        const v = opts.locals?.get(e.var.name);
+        if (v === undefined) throw new Error("derived eval: unbound local '" + e.var.name + "'");
+        return v;
+      }
+      case "Call": {
+        if (opts.callFn === undefined) throw new Error("derived eval: Call '" + e.fn.signature.name + "' but no callFn provided");
+        return opts.callFn(e.fn.signature.name, e.args.map(ev));
+      }
       case "Neg": return negate(ev(e.value));
       case "Not": return !(ev(e.value) as boolean);
       case "Add": return elementwise(ev(e.lhs), ev(e.rhs), (x, y) => x + y);

package/src/runtime/derivedUniforms/dispatch.ts

@@ -43,7 +43,9 @@ export interface DerivedUniformsResources {
 
 function bglEntries(): GPUBindGroupLayoutEntry[] {
   return [
-    { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+    // Constituents: read_write — the chain pass writes per-RO Model constituents
+    // here (a separate, earlier dispatch); §7 reads them. read_write permits both.
+    { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
     { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
     { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
     { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
@@ -119,9 +121,12 @@ class RecordsGpu {
 class UberPipeline {
   private readonly device: GPUDevice;
   readonly bgl: GPUBindGroupLayout;
-  private pipe: GPUComputePipeline | undefined;
+  // Cache one pipeline per record stride (the kernel bakes RECORD_STRIDE). The
+  // chain pass and the §7 pass usually have different strides, and both are
+  // dispatched every frame, so a single-slot cache would thrash → recompile
+  // per frame. Cleared on a registry-version bump (new rule shape).
+  private readonly pipes = new Map<number, GPUComputePipeline>();
   private builtVersion = -1;
-  private builtStride = -1;
 
   constructor(device: GPUDevice) {
     this.device = device;
@@ -129,20 +134,25 @@ class UberPipeline {
   }
 
   pipeline(registry: DerivedUniformRegistry, strideU32: number): GPUComputePipeline | undefined {
-    if (registry.size === 0) return undefined;
-    if (this.pipe !== undefined && this.builtVersion === registry.version && this.builtStride === strideU32) {
-      return this.pipe;
+    // Always buildable: the kernel carries the built-in CHAIN arm even with an
+    // empty registry, so a scene using only transform-propagation chains (no
+    // §7 rules) still gets a pipeline. encodeChunk's recordCount===0 guard is
+    // what skips the dispatch when there's genuinely nothing to do.
+    if (registry.version !== this.builtVersion) {
+      this.pipes.clear();
+      this.builtVersion = registry.version;
     }
+    const cached = this.pipes.get(strideU32);
+    if (cached !== undefined) return cached;
     const { wgsl } = buildUberKernel(registry, strideU32);
     const module = this.device.createShaderModule({ code: wgsl, label: "derivedUniforms.uber" });
-    this.pipe = this.device.createComputePipeline({
+    const pipe = this.device.createComputePipeline({
       label: "derivedUniforms.uber",
       layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.bgl] }),
       compute: { module, entryPoint: "main" },
     });
-    this.builtVersion = registry.version;
-    this.builtStride = strideU32;
-    return this.pipe;
+    this.pipes.set(strideU32, pipe);
+    return pipe;
   }
 }
 

package/src/runtime/derivedUniforms/sceneIntegration.ts

@@ -25,6 +25,7 @@ import {
 } from "./slots.js";
 import { DerivedUniformRegistry } from "./registry.js";
 import { RecordsBuffer, SlotTag, makeHandle } from "./records.js";
+import { CHAIN_RULE_ID } from "./codegen.js";
 import { DerivedUniformsDispatcher, uploadConstituentsRange } from "./dispatch.js";
 import { flatten, type RuleInput } from "./flatten.js";
 import { ruleFromIR, type DerivedRule } from "./rule.js";
@@ -41,6 +42,11 @@ export class DerivedUniformsScene {
    *  scene-wide; records partition by chunk so each dispatch binds
    *  the right chunk's main heap. */
   private readonly recordsByChunk = new Map<number, RecordsBuffer>();
+  /** Scene-wide CHAIN records (GPU transform propagation). Dispatched BEFORE
+   *  the §7 per-chunk passes — they write per-RO Model constituents that §7
+   *  then reads. Scene-wide (not per-chunk) because they target the shared
+   *  constituents buffer, not any chunk's main heap. */
+  readonly chainRecords = new RecordsBuffer();
   readonly dispatcher: DerivedUniformsDispatcher;
   /** Constituents storage GPU buffer (`array<vec2<f32>>` — df32 mat4 halves). */
   constituentsBuf: GPUBuffer;
@@ -57,7 +63,7 @@ export class DerivedUniformsScene {
     this.constituentsBuf = device.createBuffer({
       label: "derivedUniforms.constituents",
       size: initial * DF32_MAT4_BYTES,
-      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
     });
     this.dispatcher = new DerivedUniformsDispatcher(device, {
       constituentsBuf: () => this.constituentsBuf,
@@ -71,6 +77,13 @@ export class DerivedUniformsScene {
     this.mainHeapByChunk.set(chunkIdx, getter);
   }
 
+  /** Any registered main-heap getter (the chain pass needs a MainHeap binding
+   *  even though its arm never touches it). */
+  private firstHeapGetter(): (() => GPUBuffer) | undefined {
+    for (const g of this.mainHeapByChunk.values()) return g;
+    return undefined;
+  }
+
   /** Get-or-create the records buffer for `chunkIdx`. */
   recordsFor(chunkIdx: number): RecordsBuffer {
     let r = this.recordsByChunk.get(chunkIdx);
@@ -97,7 +110,7 @@ export class DerivedUniformsScene {
     this.constituentsBuf = this.device.createBuffer({
       label: "derivedUniforms.constituents",
       size: cap,
-      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
     });
     this.bufferEpoch++;
     // Fresh buffer is zero-initialised; re-upload everything packed so far.
@@ -134,6 +147,17 @@ export class DerivedUniformsScene {
    *  main heap buffer. */
   encode(enc: GPUCommandEncoder): boolean {
     let any = false;
+    // Phase 1: chain pass — writes per-RO Model constituents (fwd+inv) into the
+    // shared constituents buffer. Must run BEFORE the §7 passes that read them.
+    // The MainHeap binding is unused by the chain arm; bind any registered heap.
+    if (this.chainRecords.recordCount > 0) {
+      const anyHeap = this.firstHeapGetter();
+      if (anyHeap === undefined) {
+        throw new Error("derivedUniforms.encode: chain records present but no chunk main-heap registered to bind.");
+      }
+      if (this.dispatcher.encodeChunk(enc, this.registry, this.chainRecords, anyHeap)) any = true;
+    }
+    // Phase 2: §7 per-chunk (reads constituents incl. the chain-written Model).
     for (const [chunkIdx, records] of this.recordsByChunk) {
       if (records.recordCount === 0) continue;
       const heapGetter = this.mainHeapByChunk.get(chunkIdx);
@@ -159,6 +183,18 @@ export class DerivedUniformsScene {
 export interface RoDerivedRequest {
   /** Derived rules to install, keyed by the uniform name each produces. */
   readonly rules: ReadonlyMap<string, DerivedRule>;
+  /**
+   * GPU transform propagation: the SG ancestor trafo chain for THIS RO's
+   * `Model` (root→leaf order, constant runs folded), as `aval<Trafo3d>` links.
+   * Links are constituents shared by aval identity, so a root trafo shared by
+   * N ROs is ONE slot referenced N times (no CPU fan-out). When present, the
+   * chain pass computes a per-RO `Model` constituent (fwd from the links, inv
+   * from the reversed inverse links) and the §7 rules' `Model` leaf resolves to
+   * it — so ModelTrafo / ModelView / ModelViewInv / NormalMatrix / custom rules
+   * all derive from the GPU-composed Model, unchanged. See
+   * docs/gpu-transform-propagation.md.
+   */
+  readonly modelChain?: readonly aval<Trafo3d>[];
   /** Trafo avals available on this RO, keyed by the uniform name a rule leaf may reference (e.g. "ModelTrafo"). */
   readonly trafoAvals: ReadonlyMap<string, aval<Trafo3d>>;
   /** drawHeader byte offset (relative to `drawHeaderBaseByte`) of a host-supplied uniform on this RO; undefined if not present. */
@@ -180,6 +216,9 @@ export interface RoRegistration {
   readonly ruleHashes: readonly string[];
   /** Chunk this registration was placed into — used by deregister. */
   readonly chunkIdx: number;
+  /** Per-RO Model output constituent pair (transform propagation); freed on
+   *  deregister. Present iff the request carried a `modelChain`. */
+  readonly modelPair?: PairedSlots;
 }
 
 export function registerRoDerivations(
@@ -187,7 +226,9 @@ export function registerRoDerivations(
   owner: object,
   req: RoDerivedRequest,
 ): RoRegistration {
-  if (req.rules.size === 0) return { owner, constituentAvals: [], ruleHashes: [], chunkIdx: req.chunkIdx };
+  if (req.rules.size === 0 && req.modelChain === undefined) {
+    return { owner, constituentAvals: [], ruleHashes: [], chunkIdx: req.chunkIdx };
+  }
   const records = scene.recordsFor(req.chunkIdx);
 
   const acquiredAvals: aval<Trafo3d>[] = [];
@@ -207,8 +248,9 @@ export function registerRoDerivations(
   };
   const resolve = (inp: RuleInput): number => {
     // A matrix-typed leaf bound as an aval is a `Trafo3d` ⇒ a df32 constituent slot
-    // (its `Inverse` reads the stored backward half — free).
-    if (inp.type.kind === "Matrix" && req.trafoAvals.has(inp.name)) {
+    // (its `Inverse` reads the stored backward half — free). `Model` may instead
+    // be a GPU-composed chain output already in `pairByName` (modelChain case).
+    if (inp.type.kind === "Matrix" && (req.trafoAvals.has(inp.name) || pairByName.has(inp.name))) {
       const p = acquireTrafo(inp.name);
       return makeHandle(SlotTag.Constituent, inp.inverse ? p.inv : p.fwd);
     }
@@ -225,6 +267,27 @@ export function registerRoDerivations(
     );
   };
 
+  // GPU transform propagation: compute this RO's `Model` as a per-RO constituent
+  // from its ancestor chain, and point §7's `Model` leaf at it. The chain pass
+  // (a separate, earlier dispatch) writes the fwd half from the links and the
+  // inv half from the reversed inverse links.
+  let modelPair: PairedSlots | undefined;
+  if (req.modelChain !== undefined) {
+    modelPair = scene.constituents.allocOutputPair();
+    pairByName.set("Model", modelPair);
+    const linkPairs = req.modelChain.map((av) => {
+      acquiredAvals.push(av);
+      return scene.constituents.acquire(av);
+    });
+    const n = linkPairs.length;
+    // Model.fwd = link0·link1·…·link(n-1)  (forward order, fwd slots).
+    scene.chainRecords.add(owner, CHAIN_RULE_ID, makeHandle(SlotTag.Constituent, modelPair.fwd),
+      [n, ...linkPairs.map((p) => makeHandle(SlotTag.Constituent, p.fwd))]);
+    // Model.inv = link(n-1)⁻¹·…·link0⁻¹  (reversed order, inv slots).
+    scene.chainRecords.add(owner, CHAIN_RULE_ID, makeHandle(SlotTag.Constituent, modelPair.inv),
+      [n, ...linkPairs.slice().reverse().map((p) => makeHandle(SlotTag.Constituent, p.inv))]);
+  }
+
   for (const [outName, rule] of req.rules) {
     // `flatten` returns the same Expr object when nothing was substituted (the common case —
     // the standard recipes reference no derived names), so we can reuse `rule` (it already
@@ -241,12 +304,18 @@ export function registerRoDerivations(
     }
     records.add(owner, id, makeHandle(SlotTag.HostHeap, req.drawHeaderBaseByte + outOff), inSlots);
   }
+
   scene.ensureConstituentsCapacity(scene.constituents.slotCount * DF32_MAT4_BYTES);
-  return { owner, constituentAvals: acquiredAvals, ruleHashes, chunkIdx: req.chunkIdx };
+  return {
+    owner, constituentAvals: acquiredAvals, ruleHashes, chunkIdx: req.chunkIdx,
+    ...(modelPair !== undefined ? { modelPair } : {}),
+  };
 }
 
 export function deregisterRoDerivations(scene: DerivedUniformsScene, reg: RoRegistration): void {
   scene.recordsFor(reg.chunkIdx).removeAllForOwner(reg.owner);
+  scene.chainRecords.removeAllForOwner(reg.owner);
   for (const h of reg.ruleHashes) scene.registry.release(h);
   for (const av of reg.constituentAvals) scene.constituents.release(av);
+  if (reg.modelPair !== undefined) scene.constituents.freeOutputPair(reg.modelPair);
 }