@aardworx/wombat.rendering 0.9.11 → 0.9.12

package/src/runtime/derivedUniforms/rule.ts

@@ -0,0 +1,59 @@
+// §7 v2 — derived-uniform rule: a content-hashed pure IR fragment.
+//
+// A DerivedRule is a closure-shaped value: an output WGSL type plus an IR
+// expression ("ir") that computes it from `ReadInput("Uniform", name)` leaves.
+// The names are resolved per-RenderObject at registration time (constituent
+// slot / host uniform). See docs/derived-uniforms-extensible.md.
+//
+// This is the pre-plugin surface: rules are hand-built from IR exprs. The
+// inline `derivedUniform(u => …)` marker (lowered by the wombat-shader-vite
+// plugin) lands later and produces exactly this shape.
+
+import type { Expr, Type } from "@aardworx/wombat.shader/ir";
+import { hashValue, stableStringify } from "@aardworx/wombat.shader/ir";
+
+/** A rule's IR fragment: the result expression, over `ReadInput("Uniform", …)` leaves. */
+export type IRFragment = Expr;
+
+export interface DerivedRule<T = unknown> {
+  /** Brand — lets `isDerivedRule` recognise a rule among uniform binding values. */
+  readonly __derivedRule: true;
+  /** Output WGSL type (`=== ir.type`). Drives the storer codegen and the drawHeader byte budget. */
+  readonly outputType: Type;
+  /** Pure IR computing the output; every leaf input is a `ReadInput("Uniform", name)`. */
+  readonly ir: IRFragment;
+  /** Stable structural content hash of `ir` — the registry dedup key. */
+  readonly hash: string;
+  /** Phantom — carries the TS result type through `derivedUniform<T>`. Never read. */
+  readonly __t?: T;
+}
+
+/** True iff `x` is a derived-uniform rule (vs. an `aval` / constant value). */
+export function isDerivedRule(x: unknown): x is DerivedRule {
+  return typeof x === "object" && x !== null && (x as { __derivedRule?: unknown }).__derivedRule === true;
+}
+
+/** True iff two IR `Type`s are structurally identical. */
+export function sameType(a: Type, b: Type): boolean {
+  return a === b || stableStringify(a) === stableStringify(b);
+}
+
+/** Stable content hash of an IR expression. */
+export function hashIR(ir: Expr): string {
+  return hashValue(ir);
+}
+
+/** Build a `DerivedRule` from a hand-constructed IR expression. */
+export function ruleFromIR<T = unknown>(ir: Expr, outputType: Type = ir.type): DerivedRule<T> {
+  if (!sameType(outputType, ir.type)) {
+    throw new Error(
+      `derived rule: declared outputType ${stableStringify(outputType)} != ir type ${stableStringify(ir.type)}`,
+    );
+  }
+  return { __derivedRule: true, outputType, ir, hash: hashIR(ir) };
+}
+
+/** A `ReadInput("Uniform", name)` leaf of the given type — the only leaf kind a rule may use. */
+export function uniformRef(name: string, type: Type): Expr {
+  return { kind: "ReadInput", scope: "Uniform", name, type };
+}

package/src/runtime/derivedUniforms/sceneIntegration.ts

@@ -1,84 +1,61 @@
-// §7 → heap scene integration helper.
+// §7 v2 — heap-scene integration.
 //
-// Subscription model. Standard adaptive idiom: calling `av.getValue(t)`
-// inside an `evaluateAlways(t, ...)` scope (re-)adds the evaluating
-// object to `av.outputs`. We don't manage subscription manually.
+// One DerivedUniformsScene per heap scene: owns the rule registry, the (single,
+// scene-wide) records buffer, the constituent-slots heap (df32 trafo halves), the
+// constituents GPU buffer, and the dispatcher. Per RO: flatten each rule against the
+// RO's rule set, register it, resolve every input leaf to a tagged slot handle
+// (constituent fwd/bwd / host drawHeader byte), and push one record.
 //
-// Per frame, the heap scene's `update()` runs `evaluateAlways` once on
-// the parent scene-object (as it already does). Inside that scope:
-//   1. `scene.constituents.pullDirty(token)` drains the dirty queue.
-//      For each dirty aval, it calls `getValue(token)` — which both
-//      gives us the new value AND re-establishes our subscription on
-//      that specific aval. O(changed). Avals that didn't change keep
-//      us in their outputs from earlier evaluations.
-//   2. `scene.uploadDirty(dirtySlots)` — O(changed) value uploads +
-//      O(changed) bitmask flips.
-//   3. Per bucket: `bucket.dispatcher.encode(enc)`. The kernel
-//      early-returns on records whose inputs are all clean.
-//
-// On clean frames pullDirty/uploadDirty are no-ops. The records
-// buffer is static. CPU steady-state cost: zero.
-
-import type { aval, IAdaptiveObject } from "@aardworx/wombat.adaptive";
+// Per frame, inside the heap scene's `evaluateAlways(token, …)` scope:
+//   const dirty = scene.pullDirty(token);   // drains changed trafo avals (re-subscribes)
+//   scene.uploadDirty(dirty);               // O(changed) value uploads
+//   scene.encode(enc);                      // one compute dispatch
+// Clean frames: zero CPU work, records buffer static.
+// See docs/derived-uniforms-extensible.md.
+
+import type { aval, IAdaptiveObject, AdaptiveToken } from "@aardworx/wombat.adaptive";
 import type { Trafo3d } from "@aardworx/wombat.base";
 import {
-  ConstituentSlots,
-  DF32_MAT4_BYTES,
-  type DerivationRecord, type PairedSlots, type SlotIndex,
-  type SubscribeFn,
+  ConstituentSlots, DF32_MAT4_BYTES,
+  type PairedSlots, type SlotIndex,
 } from "./slots.js";
-import {
-  RecipeId, recipeIdByName, recipeInputs, recipeInputCount,
-  DERIVED_UNIFORM_NAMES,
-  type ConstituentRef,
-} from "./recipes.js";
-import {
-  DerivedUniformsDispatcher, DerivedUniformsPipeline,
-  uploadConstituentsRange,
-} from "./dispatch.js";
-
-/** Scene-wide §7 state. One per heap scene. Owns the single records
- *  buffer + dispatcher — all buckets share constituents, dirty mask,
- *  AND main heap (arena.attrs.buffer), so per-bucket records would
- *  just multiply dispatch overhead for no reason. */
+import { DerivedUniformRegistry } from "./registry.js";
+import { RecordsBuffer, SlotTag, makeHandle } from "./records.js";
+import { DerivedUniformsDispatcher, uploadConstituentsRange } from "./dispatch.js";
+import { flatten, type RuleInput } from "./flatten.js";
+import { ruleFromIR, type DerivedRule } from "./rule.js";
+
+export interface DerivedUniformsSceneOptions {
+  readonly initialConstituentSlots?: number;
+}
+
 export class DerivedUniformsScene {
   readonly device: GPUDevice;
   readonly constituents: ConstituentSlots;
-  readonly pipeline:     DerivedUniformsPipeline;
-  readonly dispatcher:   DerivedUniformsDispatcher;
-  /** Constituents storage GPU buffer (df32 mat4 array). */
+  readonly registry = new DerivedUniformRegistry();
+  /** Single scene-wide records buffer — all buckets share constituents AND the main heap, so per-bucket records would just multiply dispatch overhead. */
+  readonly records = new RecordsBuffer();
+  readonly dispatcher: DerivedUniformsDispatcher;
+  /** Constituents storage GPU buffer (`array<vec2<f32>>` — df32 mat4 halves). */
   constituentsBuf: GPUBuffer;
-  /** Caller-owned main heap (arena.attrs.buffer). Updated via
-   *  `rebindMainHeap` on arena resize. */
-  private mainHeapRef: { current: GPUBuffer };
+  private readonly mainHeapRef: { current: GPUBuffer };
   /** Bumped each time a shared GPU buffer is replaced. */
   bufferEpoch = 0;
 
-  constructor(
-    device:      GPUDevice,
-    mainHeapBuf: GPUBuffer,
-    opts?:       { initialConstituentSlots?: number; initialRecordCapacity?: number },
-  ) {
+  constructor(device: GPUDevice, mainHeapBuf: GPUBuffer, opts?: DerivedUniformsSceneOptions) {
     this.device = device;
     const initial = opts?.initialConstituentSlots ?? 64;
-    const subscribe: SubscribeFn = () => {};
-    this.constituents = new ConstituentSlots(subscribe, initial);
-    this.pipeline     = new DerivedUniformsPipeline(device);
+    this.constituents = new ConstituentSlots(() => {}, initial);
     this.constituentsBuf = device.createBuffer({
       label: "derivedUniforms.constituents",
-      size:  initial * DF32_MAT4_BYTES,
+      size: initial * DF32_MAT4_BYTES,
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
     });
     this.mainHeapRef = { current: mainHeapBuf };
-    this.dispatcher = new DerivedUniformsDispatcher(
-      device,
-      this.pipeline,
-      {
-        constituentsBuf: () => this.constituentsBuf,
-        mainHeapBuf:     () => this.mainHeapRef.current,
-      },
-      opts?.initialRecordCapacity ?? 64,
-    );
+    this.dispatcher = new DerivedUniformsDispatcher(device, {
+      constituentsBuf: () => this.constituentsBuf,
+      mainHeapBuf: () => this.mainHeapRef.current,
+    });
   }
 
   rebindMainHeap(mainHeapBuf: GPUBuffer): void {
@@ -92,40 +69,42 @@ export class DerivedUniformsScene {
     this.constituentsBuf.destroy();
     this.constituentsBuf = this.device.createBuffer({
       label: "derivedUniforms.constituents",
-      size:  cap,
+      size: cap,
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
     });
     this.bufferEpoch++;
-    // The fresh buffer is zero-initialized; the previous contents are
-    // gone. Re-upload everything we've ever packed (slot 0..slotCount).
-    // Without this, slots that were last written before the grow read
-    // zero on the GPU — every df_mul on them produces NaN.
+    // Fresh buffer is zero-initialised; re-upload everything packed so far.
     const slotCount = this.constituents.slotCount;
     if (slotCount > 0) {
       const mirror = this.constituents.cpuMirror;
       this.device.queue.writeBuffer(
-        this.constituentsBuf, 0,
-        mirror.buffer, mirror.byteOffset,
-        slotCount * DF32_MAT4_BYTES,
+        this.constituentsBuf, 0, mirror.buffer, mirror.byteOffset, slotCount * DF32_MAT4_BYTES,
       );
     }
   }
 
-  /** Routed from heap scene's `inputChanged(t, o)`. Returns true iff
-   *  `o` matched a known constituent aval. */
+  /** Routed from the heap scene's `inputChanged(t, o)`. True iff `o` is a tracked trafo aval. */
   routeInputChanged(o: IAdaptiveObject): boolean {
     if (!this.constituents.has(o)) return false;
     this.constituents.markDirty(o);
     return true;
   }
 
-  /** Apply the dirty set: upload changed constituent values. O(changed). */
+  /** Drain changed trafo avals (re-subscribes via `getValue`). Call inside the scene's evaluate scope. */
+  pullDirty(token: AdaptiveToken): ReadonlySet<SlotIndex> {
+    return this.constituents.pullDirty(token);
+  }
+
+  /** Upload the changed constituent value range. O(changed). */
   uploadDirty(dirty: ReadonlySet<SlotIndex>): void {
     if (dirty.size === 0) return;
     this.ensureConstituentsCapacity(this.constituents.slotCount * DF32_MAT4_BYTES);
-    uploadConstituentsRange(
-      this.device, this.constituentsBuf, this.constituents.cpuMirror, dirty,
-    );
+    uploadConstituentsRange(this.device, this.constituentsBuf, this.constituents.cpuMirror, dirty);
+  }
+
+  /** Run the uber-kernel. No-op if there are no records. */
+  encode(enc: GPUCommandEncoder): boolean {
+    return this.dispatcher.encode(enc, this.registry, this.records);
   }
 
   dispose(): void {
@@ -136,104 +115,91 @@ export class DerivedUniformsScene {
 
 // ─── Per-RO registration ──────────────────────────────────────────────
 
-export interface RoTrafoInputs {
-  readonly modelTrafo?: aval<Trafo3d> | undefined;
-  readonly viewTrafo?:  aval<Trafo3d> | undefined;
-  readonly projTrafo?:  aval<Trafo3d> | undefined;
-}
-
 export interface RoDerivedRequest {
-  readonly trafos:           RoTrafoInputs;
-  readonly requiredNames:    readonly string[];
-  readonly byteOffsetByName: ReadonlyMap<string, number>;
+  /** Derived rules to install, keyed by the uniform name each produces. */
+  readonly rules: ReadonlyMap<string, DerivedRule>;
+  /** 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. */
+  readonly hostUniformOffset: (name: string) => number | undefined;
+  /** drawHeader byte offset (relative to `drawHeaderBaseByte`) where each derived output is written; undefined if absent. */
+  readonly outputOffset: (name: string) => number | undefined;
+  /** Absolute byte offset of this RO's drawHeader within the main heap. */
   readonly drawHeaderBaseByte: number;
 }
 
 export interface RoRegistration {
-  /** Per-record handles (RecordsBuffer ids) — passed back to deregister. */
-  readonly recordIds: readonly number[];
+  /** The records-buffer owner key (the RenderObject). */
+  readonly owner: object;
   readonly constituentAvals: readonly aval<Trafo3d>[];
+  /** Flattened-rule hashes — for `registry.release` on teardown. */
+  readonly ruleHashes: readonly string[];
 }
 
-/** Register all derived-uniform records for one RO. */
 export function registerRoDerivations(
-  scene:  DerivedUniformsScene,
-  req:    RoDerivedRequest,
+  scene: DerivedUniformsScene,
+  owner: object,
+  req: RoDerivedRequest,
 ): RoRegistration {
-  if (req.requiredNames.length === 0) {
-    return { recordIds: [], constituentAvals: [] };
-  }
+  if (req.rules.size === 0) return { owner, constituentAvals: [], ruleHashes: [] };
 
   const acquiredAvals: aval<Trafo3d>[] = [];
-  const pairFor = new Map<"Model" | "View" | "Proj", PairedSlots>();
-  const TRAFO_FIELD: Record<"Model" | "View" | "Proj", keyof RoTrafoInputs> = {
-    Model: "modelTrafo", View: "viewTrafo", Proj: "projTrafo",
-  };
-  const acquirePair = (key: "Model" | "View" | "Proj"): PairedSlots => {
-    let p = pairFor.get(key);
+  const ruleHashes: string[] = [];
+  const pairByName = new Map<string, PairedSlots>();
+  const acquireTrafo = (name: string): PairedSlots => {
+    let p = pairByName.get(name);
     if (p !== undefined) return p;
-    const av = req.trafos[TRAFO_FIELD[key]];
+    const av = req.trafoAvals.get(name);
     if (av === undefined) {
-      throw new Error(
-        `derivedUniforms: RO requires '${key}' trafo but trafos.${TRAFO_FIELD[key]} is undefined`,
-      );
+      throw new Error(`derivedUniforms: rule references trafo '${name}' not available on this RO`);
     }
     p = scene.constituents.acquire(av);
-    pairFor.set(key, p);
+    pairByName.set(name, p);
     acquiredAvals.push(av);
     return p;
   };
-
-  const resolveConstituent = (ref: ConstituentRef): SlotIndex => {
-    switch (ref) {
-      case "Model.fwd": return acquirePair("Model").fwd;
-      case "Model.bwd": return acquirePair("Model").inv;
-      case "View.fwd":  return acquirePair("View" ).fwd;
-      case "View.bwd":  return acquirePair("View" ).inv;
-      case "Proj.fwd":  return acquirePair("Proj" ).fwd;
-      case "Proj.bwd":  return acquirePair("Proj" ).inv;
+  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)) {
+      const p = acquireTrafo(inp.name);
+      return makeHandle(SlotTag.Constituent, inp.inverse ? p.inv : p.fwd);
+    }
+    // Anything else is a plain host uniform — whatever value reached this RO (the sg
+    // already collapsed any subtree overrides).
+    if (inp.inverse) {
+      throw new Error(`derivedUniforms: Inverse of a non-constituent input '${inp.name}' is not supported`);
     }
+    const off = req.hostUniformOffset(inp.name);
+    if (off !== undefined) return makeHandle(SlotTag.HostHeap, req.drawHeaderBaseByte + off);
+    throw new Error(
+      `derivedUniforms: rule input '${inp.name}' cannot be resolved on this RO ` +
+        `(not a Trafo3d binding, and non-trafo host-uniform leaves aren't supported yet)`,
+    );
   };
 
-  const recordIds: number[] = [];
-  for (const name of req.requiredNames) {
-    const id = recipeIdByName(name);
-    if (id === undefined) {
-      throw new Error(`derivedUniforms: unknown derived name '${name}'`);
+  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
+    // carries a precomputed `.hash`) and skip a redundant IR hash walk per RO.
+    const flatIr = flatten(outName, rule.ir, req.rules);
+    const flat = flatIr === rule.ir ? rule : ruleFromIR(flatIr, rule.outputType);
+    const id = scene.registry.register(flat);
+    ruleHashes.push(flat.hash);
+    const entry = scene.registry.get(id)!;
+    const inSlots = entry.inputs.map(resolve);
+    const outOff = req.outputOffset(outName);
+    if (outOff === undefined) {
+      throw new Error(`derivedUniforms: no drawHeader slot for derived uniform '${outName}' on this RO`);
     }
-    const off = req.byteOffsetByName.get(name);
-    if (off === undefined) {
-      throw new Error(
-        `derivedUniforms: '${name}' has no byte offset in drawHeader for this RO`,
-      );
-    }
-    const refs = recipeInputs(id);
-    const slots = refs.map(resolveConstituent);
-    const inCount = recipeInputCount(id);
-    const rec: DerivationRecord = {
-      recipe:  id as number,
-      in0:     slots[0]!,
-      in1:     inCount >= 2 ? slots[1]! : (0 as SlotIndex),
-      in2:     inCount >= 3 ? slots[2]! : (0 as SlotIndex),
-      outByte: req.drawHeaderBaseByte + off,
-    };
-    recordIds.push(scene.dispatcher.records.add(rec));
+    scene.records.add(owner, id, makeHandle(SlotTag.HostHeap, req.drawHeaderBaseByte + outOff), inSlots);
   }
-
-  return { recordIds, constituentAvals: acquiredAvals };
+  scene.ensureConstituentsCapacity(scene.constituents.slotCount * DF32_MAT4_BYTES);
+  return { owner, constituentAvals: acquiredAvals, ruleHashes };
 }
 
-export function deregisterRoDerivations(
-  scene: DerivedUniformsScene,
-  reg:   RoRegistration,
-): void {
-  for (const id of reg.recordIds) scene.dispatcher.records.remove(id);
+export function deregisterRoDerivations(scene: DerivedUniformsScene, reg: RoRegistration): void {
+  scene.records.removeAllForOwner(reg.owner);
+  for (const h of reg.ruleHashes) scene.registry.release(h);
   for (const av of reg.constituentAvals) scene.constituents.release(av);
 }
-
-export function isDerivedUniformName(name: string): boolean {
-  return DERIVED_UNIFORM_NAMES.has(name);
-}
-
-// Re-export RecipeId for callers (e.g. heapScene's drawHeader walk).
-export { RecipeId };

package/src/runtime/heapScene.ts

@@ -72,8 +72,8 @@ import {
 import {
   DerivedUniformsScene,
   registerRoDerivations, deregisterRoDerivations,
-  isDerivedUniformName,
-  type RoRegistration,
+  isDerivedRule, STANDARD_DERIVED_RULES, STANDARD_TRAFO_LEAVES, inputsOf,
+  type RoRegistration, type DerivedRule,
 } from "./derivedUniforms/index.js";
 
 // ---------------------------------------------------------------------------
@@ -1652,19 +1652,51 @@ export function buildHeapScene(
   // ─── §7 derived-uniforms (opt-in) ─────────────────────────────────
   // Constructed lazily after sceneObj so the SubscribeFn can reference
   // both. `derivedScene` is undefined when the option is off; nothing
-  // else in this file should run when it is.
-  const enableDerivedUniforms = opts.enableDerivedUniforms === true;
+  // else in this file should run when it is. On by default — pass
+  // `enableDerivedUniforms: false` to opt out.
+  const enableDerivedUniforms = opts.enableDerivedUniforms !== false;
   const derivedScene: DerivedUniformsScene | undefined = enableDerivedUniforms
     ? new DerivedUniformsScene(device, arena.attrs.buffer, {
         // Larger initial capacity reduces grow-during-first-frame churn.
         initialConstituentSlots: 4096,
-        initialRecordCapacity:   8192,
       })
     : undefined;
   /** Per-RO §7 registration handles, keyed by global drawId.
    *  Drained on removeDraw to release slots + records. */
   const derivedByDrawId = new Map<number, RoRegistration>();
 
+  /** The derived-uniform rule for a uniform binding on this RO, if any: an explicit
+   *  `derivedUniform(...)` value in `spec.inputs`, or a standard trafo recipe by name
+   *  (recipes apply only when their base-trafo leaves are actually bound on this RO —
+   *  otherwise the field falls back to its `spec.inputs` value, if any).
+   *  (A uniform binding is either a value — an aval/constant — or a rule.) */
+  const ruleForUniform = (spec: HeapDrawSpec, name: string): DerivedRule | undefined => {
+    if (derivedScene === undefined) return undefined;
+    const v = spec.inputs[name];
+    const explicit = isDerivedRule(v);
+    const rule = explicit ? v : STANDARD_DERIVED_RULES.get(name);
+    if (rule === undefined) return undefined;
+    // Check the rule's input leaves are resolvable on this RO. A matrix-typed leaf needs an
+    // aval<Trafo3d> binding (constituent slot). Non-trafo / host-uniform leaves aren't wired
+    // yet — for an explicit user rule that's a hard error; for a standard recipe it just means
+    // "this RO doesn't supply the base trafos", so we fall back to the packed value.
+    for (const inp of inputsOf(rule.ir)) {
+      const specName = STANDARD_TRAFO_LEAVES.get(inp.name) ?? inp.name;
+      const lv = spec.inputs[specName];
+      const resolvable = inp.type.kind === "Matrix" && lv !== undefined && !isDerivedRule(lv);
+      if (!resolvable) {
+        if (explicit) {
+          throw new Error(
+            `derivedUniform '${name}': leaf '${inp.name}' is not resolvable on this RO ` +
+              `(need an aval<Trafo3d> binding; non-trafo host-uniform leaves aren't supported yet)`,
+          );
+        }
+        return undefined; // standard recipe, base trafos not bound here — use the packed value
+      }
+    }
+    return rule;
+  };
+
   // ─── Atlas bindings ───────────────────────────────────────────────
   //
   // A bucket whose textures live in the atlas binds N consecutive
@@ -2625,7 +2657,7 @@ export function buildHeapScene(
         // pre-pass. We still allocate an arena slot here so the
         // drawHeader gets a valid ref written by packBucketHeader; §7
         // overwrites the arena data each frame the inputs are dirty.
-        if (derivedScene !== undefined && isDerivedUniformName(f.name)) {
+        if (ruleForUniform(spec, f.name) !== undefined) {
           const dummyAval = AVal.constant<M44d>(M44d.zero);
           const ref = pool.acquire(
             device, arena.attrs, dummyAval, M44d.zero,
@@ -2762,32 +2794,44 @@ export function buildHeapScene(
     drawIdToIndexAval[drawId] = indicesAval;
 
     // ─── §7 derived-uniforms registration ────────────────────────────
-    // Collect the derived names this effect actually uses (i.e. fields
-    // declared in the drawHeader for this effect AND in the §7 set).
-    // For each, the kernel writes into byte offset
-    //   localSlot * drawHeaderBytes + field.byteOffset
-    // i.e. this RO's drawHeader region in the bucket's drawHeap.
+    // A uniform binding on this RO is either a value (aval/constant) or a rule —
+    // collect the rules (explicit `derivedUniform(...)` values + standard trafo
+    // recipes) for fields the effect declares. The kernel writes each result into
+    // this RO's drawHeader region in the bucket's drawHeap (its arena slot).
     if (derivedScene !== undefined) {
-      const requiredNames: string[] = [];
-      const arenaByteOffsetByName = new Map<string, number>();
+      const ruleSubset = new Map<string, DerivedRule>();
+      const outOffsetByName = new Map<string, number>();
       for (const f of bucket.layout.drawHeaderFields) {
         if (f.name === "__layoutId") continue;
         if (!effectFields.has(f.name)) continue;
-        if (!isDerivedUniformName(f.name)) continue;
+        const rule = ruleForUniform(spec, f.name);
+        if (rule === undefined) continue;
         const ref = perDrawRefs.get(f.name);
         if (ref === undefined) continue;
-        requiredNames.push(f.name);
-        arenaByteOffsetByName.set(f.name, ref + ALLOC_HEADER_PAD_TO);
+        ruleSubset.set(f.name, rule);
+        outOffsetByName.set(f.name, ref + ALLOC_HEADER_PAD_TO);
       }
-      if (requiredNames.length > 0) {
-        const reg = registerRoDerivations(derivedScene, {
-          trafos: {
-            modelTrafo: spec.inputs["ModelTrafo"] as aval<Trafo3d> | undefined,
-            viewTrafo:  spec.inputs["ViewTrafo"]  as aval<Trafo3d> | undefined,
-            projTrafo:  spec.inputs["ProjTrafo"]  as aval<Trafo3d> | undefined,
-          },
-          requiredNames,
-          byteOffsetByName: arenaByteOffsetByName,
+      if (ruleSubset.size > 0) {
+        // Trafo avals a rule leaf may reference: the standard `Model`/`View`/`Proj`
+        // leaf names (mapped to their `*Trafo` bindings), plus every aval-valued input
+        // by its own name (so a `derivedUniform(u => u.ViewTrafo.mul(u.ModelTrafo))`
+        // resolves `u.ViewTrafo` to that binding). resolveSource only uses these for
+        // matrix-typed leaves; a non-matrix leaf falls through to the (unsupported-in-v0)
+        // host path.
+        const trafoAvals = new Map<string, aval<Trafo3d>>();
+        for (const [leaf, specName] of STANDARD_TRAFO_LEAVES) {
+          const av = spec.inputs[specName];
+          if (av !== undefined && !isDerivedRule(av)) trafoAvals.set(leaf, av as aval<Trafo3d>);
+        }
+        for (const n of Object.keys(spec.inputs)) {
+          const v = spec.inputs[n];
+          if (v !== undefined && !isDerivedRule(v) && !trafoAvals.has(n)) trafoAvals.set(n, v as aval<Trafo3d>);
+        }
+        const reg = registerRoDerivations(derivedScene, {}, {
+          rules: ruleSubset,
+          trafoAvals,
+          hostUniformOffset: () => undefined,
+          outputOffset: (n) => outOffsetByName.get(n),
           drawHeaderBaseByte: 0,
         });
         derivedByDrawId.set(drawId, reg);
@@ -3126,19 +3170,19 @@ export function buildHeapScene(
       // adds the evaluating object to the aval's outputs). Without
       // this scope, view changes never propagate again — the scene
       // freezes after one frame.
-      let dirty: ReturnType<typeof derivedScene.constituents.pullDirty> | undefined;
+      let dirty: ReturnType<typeof derivedScene.pullDirty> | undefined;
       sceneObj.evaluateAlways(token, (t) => {
-        dirty = derivedScene.constituents.pullDirty(t);
+        dirty = derivedScene.pullDirty(t);
       });
       const _t1 = performance.now();
       derivedScene.uploadDirty(dirty!);
       const _t2 = performance.now();
-      if (dirty!.size > 0) derivedScene.dispatcher.encode(enc);
+      if (dirty!.size > 0) derivedScene.encode(enc);
       const _t3 = performance.now();
       stats.derivedPullMs   = _t1 - _t0;
       stats.derivedUploadMs = _t2 - _t1;
       stats.derivedEncodeMs = _t3 - _t2;
-      stats.derivedRecords  = derivedScene.dispatcher.records.recordCount;
+      stats.derivedRecords  = derivedScene.records.recordCount;
     }
     let anyDirty = false;
     for (const b of buckets) { if (b.scanDirty) { anyDirty = true; break; } }

package/src/runtime/hybridScene.ts

@@ -225,7 +225,7 @@ export function compileHybridScene(
     fragmentOutputLayout,
     atlasPool,
     ...(opts.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
-    ...(opts.enableDerivedUniforms === true ? { enableDerivedUniforms: true } : {}),
+    ...(opts.enableDerivedUniforms === false ? { enableDerivedUniforms: false } : {}),
   });
 
   // ─── Legacy subset → RenderTree → ScenePass ──────────────────────

package/src/runtime/index.ts

@@ -43,6 +43,14 @@ export { flattenRenderTree } from "./flattenTree.js";
 export { isHeapEligible } from "./heapEligibility.js";
 export { renderObjectToHeapSpec } from "./heapAdapter.js";
 
+// ─── Derived uniforms (§7): a uniform binding is a value (aval/constant) OR a rule ──
+export {
+  derivedUniform, DerivedExpr, type DerivedScope,
+  ruleFromIR, uniformRef, isDerivedRule, hashIR,
+  type DerivedRule, type IRFragment,
+  STANDARD_DERIVED_RULES, isStandardDerivedName,
+} from "./derivedUniforms/index.js";
+
 export {
   compileHybridScene,
   type CompileHybridSceneOptions,

package/src/runtime/renderTask.ts

@@ -255,7 +255,7 @@ class RenderTask implements IRenderTask {
         compileEffect: this.ctx.compileEffect,
         ...(this.ctx.heapEnabled !== undefined ? { heapEnabled: this.ctx.heapEnabled } : {}),
         ...(this.ctx.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
-        ...(this.ctx.enableDerivedUniforms === true ? { enableDerivedUniforms: true } : {}),
+        ...(this.ctx.enableDerivedUniforms === false ? { enableDerivedUniforms: false } : {}),
       });
       this._scenes.set(cmd, s);
     }

package/src/runtime/runtime.ts

@@ -76,7 +76,7 @@ export class Runtime {
       })),
       ...(opts.heapEnabled !== undefined ? { heapEnabled: opts.heapEnabled } : {}),
       ...(opts.enableFamilyMerge === true ? { enableFamilyMerge: true } : {}),
-      ...(opts.enableDerivedUniforms === true ? { enableDerivedUniforms: true } : {}),
+      ...(opts.enableDerivedUniforms === false ? { enableDerivedUniforms: false } : {}),
     };
     // `device.lost` is a real-WebGPU promise; mock devices may not
     // expose it. Treat as "never lost" in that case.

package/dist/runtime/derivedUniforms/slotId.d.ts

@@ -1,15 +0,0 @@
-/** Branded u32 — top bit selects heap, low 31 bits are slot index. */
-export type SlotId = number & {
-    readonly __slotId: unique symbol;
-};
-export declare const SlotId: {
-    /** Encode a Constituents-heap slot. */
-    constituent(idx: number): SlotId;
-    /** Encode an Intermediates-heap slot. */
-    intermediate(idx: number): SlotId;
-    isIntermediate(s: SlotId): boolean;
-    index(s: SlotId): number;
-};
-/** Bytes per df32 mat4 slot: 16 entries × 2 floats × 4 bytes. */
-export declare const DF32_MAT4_BYTES = 128;
-//# sourceMappingURL=slotId.d.ts.map

package/dist/runtime/derivedUniforms/slotId.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"slotId.d.ts","sourceRoot":"","sources":["../../../src/runtime/derivedUniforms/slotId.ts"],"names":[],"mappings":"AAWA,sEAAsE;AACtE,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAInE,eAAO,MAAM,MAAM;IACjB,uCAAuC;qBACtB,MAAM,GAAG,MAAM;IAGhC,yCAAyC;sBACvB,MAAM,GAAG,MAAM;sBAGf,MAAM,GAAG,OAAO;aAGzB,MAAM,GAAG,MAAM;CAGzB,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,eAAe,MAAM,CAAC"}