@aardworx/wombat.rendering 0.19.24 → 0.20.0

package/src/core/renderObject.ts

@@ -63,10 +63,28 @@ export interface RenderObject {
   readonly samplers: HashMap<string, aval<ISampler>>;
   /** name → storage buffer source. */
   readonly storageBuffers?: HashMap<string, aval<IBuffer>>;
+  /**
+   * Scene-level INJECTED storage buffers (e.g. the OIT node pool the
+   * transparency task threads into every transparent leaf). Unlike
+   * `storageBuffers`, these do NOT disqualify the RO from the heap
+   * path — the heap binds them once per bucket (they are shared by
+   * construction). The classic path treats them exactly like
+   * `storageBuffers` (leaf-own entries win on name conflict).
+   */
+  readonly injectedStorage?: HashMap<string, aval<IBuffer>>;
 
   /** Index buffer for indexed draws. */
   readonly indices?: BufferView;
   readonly drawCall: aval<DrawCall>;
+  /**
+   * Optional picking id (u32 < 2^24). First-class instead of a
+   * `PickId` uniform: one unique `AVal.constant` per RO would drag a
+   * pool entry + per-RO provider identity + adaptive bookkeeping in —
+   * measured ~6.5 KB of JS heap PER RO at scale. The heap path writes
+   * this INLINE into the drawHeader (like `__layoutId`); the classic
+   * path synthesizes the `PickId` uniform from it.
+   */
+  readonly pickId?: number;
   /**
    * Optional gate: when `active` ticks to `false`, the runtime must
    * skip drawing this RO this frame **without** releasing pool

package/src/resources/preparedRenderObject.ts

@@ -12,7 +12,7 @@
 // PreparedRenderObject so flipping a non-pipeline-affecting field
 // (`stencilReference`, `blendConstant`) does NOT trigger a recompile.
 
-import {
+import { type IUniformProvider,
   AdaptiveResource,
   AttributeProvider,
   BufferView,
@@ -340,7 +340,8 @@ function buildPipelineForSnap(
         }
       : undefined;
   const desc: CompileRenderPipelineDescription = {
-    ...(ctx.label !== undefined ? { label: ctx.label } : {}),
+    // default label = the effect identity — attributable GPU debugging
+    label: ctx.label ?? `classic/${ctx.effectId ?? "anon"}`,
     ...(ctx.effectId !== undefined ? { effectId: ctx.effectId } : {}),
     vertexShaderSource: ctx.vsSource,
     fragmentShaderSource: ctx.fsSource,
@@ -736,8 +737,16 @@ export function prepareRenderObject(
   const perGroup: EntryDesc[][] = [];
   for (let g = 0; g <= maxGroup; g++) perGroup.push([]);
 
+  // First-class `RenderObject.pickId` → synthesized `PickId` uniform on
+  // the classic path (the heap path writes it inline into the
+  // drawHeader instead — see INLINE_HEADER_UNIFORMS). Classic scenes
+  // are small, so a per-RO constant aval is fine here.
+  const uniformSource: IUniformProvider = obj.pickId !== undefined
+    ? withPickId(obj.pickId, asUniformProvider(obj.uniforms))
+    : asUniformProvider(obj.uniforms);
+
   for (const ub of iface.uniformBlocks) {
-    const merged = mergeUniformInputs(asUniformProvider(obj.uniforms), effect.avalBindings, ub);
+    const merged = mergeUniformInputs(uniformSource, effect.avalBindings, ub);
     const block = ubAsBlock(ub);
     const res = prepareUniformBuffer(device, block, merged, {
       ...(opts.label !== undefined ? { label: `${opts.label}.${ub.name}` } : {}),
@@ -768,7 +777,7 @@ export function prepareRenderObject(
   }
 
   for (const sb of iface.storageBuffers) {
-    const av = obj.storageBuffers?.tryFind(sb.name);
+    const av = obj.storageBuffers?.tryFind(sb.name) ?? obj.injectedStorage?.tryFind(sb.name);
     if (av === undefined) throw new Error(`prepareRenderObject: missing storage buffer "${sb.name}"`);
     const usage = BufferUsage.STORAGE
       | (sb.access === "read_write" ? BufferUsage.COPY_DST : 0);
@@ -811,7 +820,9 @@ export function prepareRenderObject(
   // 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);
+    const uniProv = obj.pickId !== undefined
+      ? withPickId(obj.pickId, asUniformProvider(obj.uniforms))
+      : asUniformProvider(obj.uniforms);
     modeUniformReader = (name: string, token: AdaptiveToken): unknown => {
       const v = uniProv.tryGet(name);
       if (v === undefined) return undefined;
@@ -844,6 +855,15 @@ export function prepareRenderObject(
 const SENTINEL_PIPELINE = { __sentinel: "PreparedRenderObject.pipeline" } as unknown as GPURenderPipeline;
 
 // ---------------------------------------------------------------------------
+/** Overlay provider: `PickId` first (constant), then `base`. */
+function withPickId(pickId: number, base: IUniformProvider): IUniformProvider {
+  const pick = AVal.constant<number>(pickId);
+  return {
+    tryGet(name: string) { return name === "PickId" ? (pick as aval<unknown>) : base.tryGet(name); },
+    *names() { yield "PickId"; yield* base.names(); },
+  };
+}
+
 // Uniform input merging — `obj.uniforms` wins; `avalBindings` is fallback.
 // ---------------------------------------------------------------------------
 
@@ -867,7 +887,10 @@ function mergeUniformInputs(
     // here just as the heap path derives it on the GPU, so the legacy path
     // serves the same declared uniforms.
     const recipe = STANDARD_DERIVED_RULES.get(f.name);
-    if (recipe !== undefined) merged = merged.add(f.name, ruleToAval(recipe, user, bindings));
+    if (recipe !== undefined) { merged = merged.add(f.name, ruleToAval(recipe, user, bindings)); continue; }
+    // An unresolved field stays ZERO in the uniform buffer — silent garbage
+    // transforms/values downstream. Say so once per (block, field).
+    console.warn(`prepareRenderObject: uniform block field "${f.name}" resolves to undefined (buffer stays zero)`);
   }
   return merged;
 }

package/src/resources/uniformBuffer.ts

@@ -99,7 +99,9 @@ class UniformBufferResource extends AdaptiveResource<GPUBuffer> {
       const desc: GPUBufferDescriptor = {
         size: this._scratch.bytes.byteLength,
         usage: BufferUsage.UNIFORM | BufferUsage.COPY_DST,
-        ...(this.label !== undefined ? { label: this.label } : {}),
+        // default label: the block's field names — makes GPU debugging
+        // (writeBuffer interception, buffer inspectors) attributable.
+        label: this.label ?? `ubo{${this.layout.fields.map((f) => f.name).join(",")}}`,
       };
       this._gpu = this.device.createBuffer(desc);
     }

package/src/runtime/derivedModes/modeKeyCpu.ts

@@ -165,18 +165,32 @@ function stripFormatFor(topology: GPUPrimitiveTopology): GPUIndexFormat | undefi
  * — `addMarkingCallback` is a no-op for an aval that never marks, so
  * no special-casing required.
  */
+/** Canonical descriptor per modeKey. The modeKey is a COMPLETE encoding
+ *  of the descriptor (that's what makes it the bucket key), so two
+ *  trackers with equal keys can share one frozen snapshot object —
+ *  at heap scale most draws share a handful of pipeline states, and a
+ *  per-draw descriptor (+ its attachments array) was measurable ballast.
+ *  The map is bounded by the number of DISTINCT pipeline states. */
+const descriptorInterning = new Map<bigint, PipelineStateDescriptor>();
+function internDescriptor(key: bigint, d: PipelineStateDescriptor): PipelineStateDescriptor {
+  const hit = descriptorInterning.get(key);
+  if (hit !== undefined) return hit;
+  descriptorInterning.set(key, d);
+  return d;
+}
+
 export class ModeKeyTracker implements IDisposable {
   readonly ps: PipelineState | undefined;
   readonly signature: FramebufferSignature;
   private readonly onDirty: () => void;
-  private readonly subs: IDisposable[] = [];
+  private subs: IDisposable[] | undefined;
   private cachedDescriptor: PipelineStateDescriptor;
   private cachedModeKey: bigint;
   private readonly modeRules: RoModeRules | undefined;
   private readonly uniformAvals: ReadonlyMap<string, aval<unknown>> | undefined;
   /** Avals discovered while evaluating rules; merged into the leaf
    *  set returned by `forEachLeaf` so the heap scene subscribes once. */
-  private readonly ruleDeps = new Set<aval<unknown>>();
+  private ruleDeps: Set<aval<unknown>> | undefined;
 
   constructor(
     ps: PipelineState | undefined,
@@ -201,8 +215,9 @@ export class ModeKeyTracker implements IDisposable {
     this.onDirty   = onDirty;
     if (options.modeRules    !== undefined) this.modeRules    = options.modeRules;
     if (options.uniformAvals !== undefined) this.uniformAvals = options.uniformAvals;
-    this.cachedDescriptor = this.snapshot();
-    this.cachedModeKey    = encodeModeKey(this.cachedDescriptor);
+    const d = this.snapshot();
+    this.cachedModeKey    = encodeModeKey(d);
+    this.cachedDescriptor = internDescriptor(this.cachedModeKey, d);
     if (options.skipSubscribe !== true) this.subscribeAll();
   }
 
@@ -210,7 +225,7 @@ export class ModeKeyTracker implements IDisposable {
     return snapshotDescriptor(this.ps, this.signature, {
       ...(this.modeRules    !== undefined ? { modeRules:    this.modeRules    } : {}),
       ...(this.uniformAvals !== undefined ? { uniformAvals: this.uniformAvals } : {}),
-      recordDep: (av) => { this.ruleDeps.add(av); },
+      recordDep: (av) => { (this.ruleDeps ??= new Set()).add(av); },
     });
   }
 
@@ -257,7 +272,7 @@ export class ModeKeyTracker implements IDisposable {
         }
       }
     }
-    for (const av of this.ruleDeps) visit(av);
+    if (this.ruleDeps !== undefined) for (const av of this.ruleDeps) visit(av);
   }
 
   get descriptor(): PipelineStateDescriptor { return this.cachedDescriptor; }
@@ -274,18 +289,18 @@ export class ModeKeyTracker implements IDisposable {
    * subscription-dedupe layer picks them up.
    */
   recompute(): boolean {
-    this.ruleDeps.clear();
+    this.ruleDeps?.clear();
     const next = this.snapshot();
     const nextKey = encodeModeKey(next);
     if (nextKey === this.cachedModeKey) return false;
-    this.cachedDescriptor = next;
+    this.cachedDescriptor = internDescriptor(nextKey, next);
     this.cachedModeKey    = nextKey;
     return true;
   }
 
   dispose(): void {
-    for (const s of this.subs) s.dispose();
-    this.subs.length = 0;
+    if (this.subs !== undefined) for (const s of this.subs) s.dispose();
+    this.subs = undefined;
   }
 
   private subscribeAll(): void {
@@ -318,7 +333,7 @@ export class ModeKeyTracker implements IDisposable {
   }
 
   private sub(a: aval<unknown>): void {
-    this.subs.push(addMarkingCallback(a, this.onDirty));
+    (this.subs ??= []).push(addMarkingCallback(a, this.onDirty));
   }
 
   private subBlendState(b: PsBlendState): void {

package/src/runtime/derivedModes/partitionDispatcher.ts

@@ -248,6 +248,13 @@ export class GpuPartitionScene {
     this.masterShadow[recordIdx * this.recordU32 + 5] = comboId >>> 0;
   }
 
+  /** Update an existing record's `indexStart` (field 2 = allocBase + slice).
+   *  Used by index-buffer compaction; caller flags the bucket partitionDirty. */
+  setRecordIndexStart(recordIdx: number, indexStart: number): void {
+    if (recordIdx < 0 || recordIdx >= this.numRecords) return;
+    this.masterShadow[recordIdx * this.recordU32 + 2] = indexStart >>> 0;
+  }
+
   /** Update an existing record's uniform ref by uniform index. */
   setRecordUniformRef(recordIdx: number, uniformIdx: number, ref: number): void {
     if (recordIdx < 0 || recordIdx >= this.numRecords) return;
@@ -255,6 +262,29 @@ export class GpuPartitionScene {
     this.masterShadow[recordIdx * this.recordU32 + PARTITION_RECORD_PREFIX_U32 + uniformIdx] = ref >>> 0;
   }
 
+  /**
+   * Re-seat every record's baked arena uniform refs after a main-heap
+   * compaction relocated their allocations. `remap` maps OLD→NEW arena byte
+   * offset (alloc header offset, same space the refs are stored in). Returns
+   * the number of ref words rewritten; the caller must flag the bucket
+   * `partitionDirty` so the master re-uploads. O(records × numUniforms).
+   */
+  remapUniformRefs(remap: ReadonlyMap<number, number>): number {
+    if (remap.size === 0 || this._numUniforms === 0) return 0;
+    const ru32 = this.recordU32;
+    let changed = 0;
+    for (let i = 0; i < this.numRecords; i++) {
+      const o = i * ru32 + PARTITION_RECORD_PREFIX_U32;
+      for (let k = 0; k < this._numUniforms; k++) {
+        const nn = remap.get(this.masterShadow[o + k]!);
+        if (nn === undefined) continue;
+        this.masterShadow[o + k] = nn >>> 0;
+        changed++;
+      }
+    }
+    return changed;
+  }
+
   removeRecord(recordIdx: number): number {
     if (recordIdx < 0 || recordIdx >= this.numRecords) return -1;
     const last = this.numRecords - 1;

package/src/runtime/derivedUniforms/codegen.ts

@@ -88,28 +88,49 @@ function classify(entry: RuleEntry): Shape {
 
 // ─── WGSL fragments ───────────────────────────────────────────────────
 
+// Error-free transforms survive ONLY if the compiler cannot see their
+// algebra: WebKit's WGSL→MSL path compiles with fast-math, which folds
+// (a+b)-a → b (two_sum dies) and distributes Dekker's split products into
+// exact cancellation (two_prod dies) — df32 silently degrades to f32, the
+// planet-scale 0.25m wobble on iOS. Desktop drivers fold the naked forms
+// too. Defense: the EFT-critical constants 1/-1/0 come from the `Count`
+// uniform, whose contents no shader compiler can constant-fold; validated
+// per-primitive on Apple M-series + NVIDIA/Vulkan (df32-probe, variant J).
 const DF32_LIB = /* wgsl */ `
-fn split12(a: f32) -> vec2<f32> {
-  let hi = bitcast<f32>(bitcast<u32>(a) & 0xFFFFE000u);
-  return vec2<f32>(hi, a - hi);
-}
+// launder: value-preserving, but an opaque integer op the optimizer
+// cannot trace through (Count.zeroBits == 0 at runtime).
+fn ln_(x: f32) -> f32 { return bitcast<f32>(bitcast<u32>(x) ^ Count.zeroBits); }
 fn two_sum(a: f32, b: f32) -> vec2<f32> {
   let s  = a + b;
-  let bb = fma(1.0, s, -a);
-  let t1 = fma(1.0, s, -bb);
-  let t2 = fma(1.0, a, -t1);
-  let t3 = fma(1.0, b, -bb);
+  let bb = fma(Count.one, s, -a);
+  let t1 = fma(Count.one, s, -bb);
+  let t2 = fma(Count.one, a, -t1);
+  let t3 = fma(Count.one, b, -bb);
   return vec2<f32>(s, t2 + t3);
 }
 fn quick_two_sum(a: f32, b: f32) -> vec2<f32> {
   let s = a + b;
-  let t = fma(1.0, s, -a);
-  return vec2<f32>(s, fma(1.0, b, -t));
+  let t = fma(Count.one, s, -a);
+  return vec2<f32>(s, fma(Count.one, b, -t));
+}
+// Veltkamp split with LAUNDERED halves. The laundering is load-bearing on
+// two fronts: Apple's fast-math distributes Dekker's partial products into
+// exact symbolic cancellation (err ≡ a*b - p ≡ 0) unless the halves are
+// opaque; and an fma-based two_prod (err = fma(a,b,-p)) is NOT an option —
+// Qualcomm Adreno and Intel Xe lower fma() to an unfused multiply-add,
+// which makes that error term exactly zero. Laundered Dekker needs no fma
+// at all, so it is exact on every backend probed (NVIDIA/Vulkan, Apple
+// M-series/Metal, Adreno/Android, Intel Xe/D3D).
+fn lsplit12(a: f32) -> vec2<f32> {
+  // 12/12 mantissa split (11 explicit + implicit high bits): every partial
+  // product below is <= 24 bits, i.e. exactly representable in f32.
+  let hi = bitcast<f32>(bitcast<u32>(a) & 0xFFFFF000u);
+  return vec2<f32>(ln_(hi), ln_(a - hi));
 }
 fn two_prod(a: f32, b: f32) -> vec2<f32> {
   let p = a * b;
-  let A = split12(a);
-  let B = split12(b);
+  let A = lsplit12(a);
+  let B = lsplit12(b);
   let err = ((A.x * B.x - p) + A.x * B.y + A.y * B.x) + A.y * B.y;
   return vec2<f32>(p, err);
 }
@@ -165,7 +186,7 @@ function bindings(strideU32: number): string {
 @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 }
+struct CountUniform { count: u32, zeroBits: u32, one: f32, negOne: f32 }
 @group(0) @binding(3) var<uniform>             Count: CountUniform;
 
 const RECORD_STRIDE: u32 = ${strideU32 >>> 0}u;

package/src/runtime/derivedUniforms/dispatch.ts

@@ -85,6 +85,12 @@ class RecordsGpu {
       size: 16, // uniform min binding size
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     });
+    // Fields 1..3 are DF32_LIB's fast-math guards (see codegen.ts): zeroBits,
+    // one, negOne — runtime values the shader compiler cannot constant-fold.
+    const init = new ArrayBuffer(16);
+    new Uint32Array(init, 0, 2).set([0, 0]); // count, zeroBits
+    new Float32Array(init, 8, 2).set([1.0, -1.0]); // one, negOne
+    device.queue.writeBuffer(this.countBuf, 0, init);
   }
 
   /** Re-upload the packed record data if it changed since last sync, and refresh `Count`. */

package/src/runtime/derivedUniforms/records.ts

@@ -48,7 +48,42 @@ const MIN_STRIDE_U32 = 5; // rule_id, out_slot, in0, in1, in2 — covers the 13
 export class RecordsBuffer {
   private buf: Uint32Array;
   private owners: (RecordOwner | undefined)[] = [];
-  private readonly byOwner = new Map<RecordOwner, Set<number>>();
+  /** Record indices per owner. A single number for the common one-
+   *  record-per-owner case, promoted to a small array on the second —
+   *  saves a whole `Set` per RO at heap scale. */
+  private readonly byOwner = new Map<RecordOwner, number | number[]>();
+
+  private ownerAdd(owner: RecordOwner, idx: number): void {
+    const v = this.byOwner.get(owner);
+    if (v === undefined) this.byOwner.set(owner, idx);
+    else if (typeof v === "number") this.byOwner.set(owner, [v, idx]);
+    else v.push(idx);
+  }
+  private ownerDelete(owner: RecordOwner, idx: number): void {
+    const v = this.byOwner.get(owner);
+    if (v === undefined) return;
+    if (typeof v === "number") {
+      if (v === idx) this.byOwner.delete(owner);
+      return;
+    }
+    const i = v.indexOf(idx);
+    if (i >= 0) {
+      v[i] = v[v.length - 1]!;
+      v.pop();
+      if (v.length === 1) this.byOwner.set(owner, v[0]!);
+      else if (v.length === 0) this.byOwner.delete(owner);
+    }
+  }
+  private ownerReplace(owner: RecordOwner, oldIdx: number, newIdx: number): void {
+    const v = this.byOwner.get(owner);
+    if (v === undefined) return;
+    if (typeof v === "number") {
+      if (v === oldIdx) this.byOwner.set(owner, newIdx);
+      return;
+    }
+    const i = v.indexOf(oldIdx);
+    if (i >= 0) v[i] = newIdx;
+  }
   private strideU32 = MIN_STRIDE_U32;
   private count = 0;
   /** Bumps whenever the byte layout changes shape (stride growth) so the dispatcher recompiles. */
@@ -86,44 +121,64 @@ export class RecordsBuffer {
     for (let i = 0; i < inSlots.length; i++) this.buf[base + 2 + i] = inSlots[i]! >>> 0;
     for (let i = base + 2 + inSlots.length; i < base + this.strideU32; i++) this.buf[i] = 0;
     this.owners[idx] = owner;
-    let set = this.byOwner.get(owner);
-    if (set === undefined) {
-      set = new Set();
-      this.byOwner.set(owner, set);
-    }
-    set.add(idx);
+    this.ownerAdd(owner, idx);
     this.generation++;
     return idx;
   }
 
   /** Remove every record owned by `owner` (swap-remove against the tail). */
   removeAllForOwner(owner: RecordOwner): void {
-    const set = this.byOwner.get(owner);
-    if (set === undefined || set.size === 0) {
-      this.byOwner.delete(owner);
+    const v = this.byOwner.get(owner);
+    if (v === undefined) {
       return;
     }
     // Process highest indices first so a swap can never move a not-yet-removed
     // record of this owner that we still hold a stale index for.
-    const indices = [...set].sort((a, b) => b - a);
+    const indices = typeof v === "number" ? [v] : [...v].sort((a, b) => b - a);
     for (const idx of indices) this.removeAt(idx);
     this.byOwner.delete(owner);
     this.generation++;
   }
 
+  /**
+   * Re-seat `HostHeap` handles after a main-heap compaction relocated their
+   * backing allocations. `remap` maps an OLD handle payload (the data byte
+   * offset in the main heap) to its NEW one. `Constituent` handles point into
+   * the separate df32 slot buffer (never compacted) and are left untouched.
+   * Returns the number of handle words rewritten; bumps `generation` so the
+   * dispatcher re-uploads. O(records × stride).
+   */
+  remapHostHeap(remap: ReadonlyMap<number, number>): number {
+    if (remap.size === 0 || this.count === 0) return 0;
+    const s = this.strideU32;
+    let changed = 0;
+    for (let i = 0; i < this.count; i++) {
+      const base = i * s;
+      // out_slot at base+1, in_slots at base+2 .. base+s-1.
+      for (let w = base + 1; w < base + s; w++) {
+        const h = this.buf[w]!;
+        if (handleTag(h) !== SlotTag.HostHeap) continue;
+        const nn = remap.get(handlePayload(h));
+        if (nn === undefined) continue;
+        this.buf[w] = makeHandle(SlotTag.HostHeap, nn);
+        changed++;
+      }
+    }
+    if (changed > 0) this.generation++;
+    return changed;
+  }
+
   private removeAt(idx: number): void {
     const last = this.count - 1;
     // The record currently at `idx` is the one being removed.
-    this.byOwner.get(this.owners[idx]!)?.delete(idx);
+    this.ownerDelete(this.owners[idx]!, idx);
     if (idx !== last) {
       // Move the tail record's words into the hole, and re-home it.
       const dst = idx * this.strideU32;
       const src = last * this.strideU32;
       this.buf.copyWithin(dst, src, src + this.strideU32);
       const lastOwner = this.owners[last]!;
-      const lset = this.byOwner.get(lastOwner)!;
-      lset.delete(last);
-      lset.add(idx);
+      this.ownerReplace(lastOwner, last, idx);
       this.owners[idx] = lastOwner;
     }
     this.owners[last] = undefined;

package/src/runtime/derivedUniforms/sceneIntegration.ts

@@ -109,6 +109,16 @@ export class DerivedUniformsScene {
     return r;
   }
 
+  /**
+   * Re-seat the per-chunk derived-uniform records' `HostHeap` handles
+   * (derived outputs and host-uniform inputs) after the main heap compacted
+   * `chunkIdx`. `remap` maps OLD→NEW data byte offsets. Returns words changed.
+   */
+  remapHostHeap(chunkIdx: number, remap: ReadonlyMap<number, number>): number {
+    const r = this.recordsByChunk.get(chunkIdx);
+    return r === undefined ? 0 : r.remapHostHeap(remap);
+  }
+
   /** Total record count summed across every chunk's records buffer.
    *  Used by the scene's stats / diagnostics. */
   get totalRecordCount(): number {
@@ -264,14 +274,19 @@ export class TrafoTree {
     this.byKey.set(key, node);
     const h = (s: number): number => makeHandle(SlotTag.Constituent, s);
     const recs = this.scene.chainRecordsFor(level);
-    // node.world.fwd = link.fwd · parent.world.fwd  (just link at the root end).
-    // node.world.inv = parent.world.inv · link.inv  (reversed; just link at root).
+    // node.world.fwd = parent.world.fwd · link.fwd  (just link at the root end):
+    // deeper links sit on the RIGHT so they hit the column vector FIRST —
+    // p' = root · … · leaf · p, the scene-graph inner-first contract. (The
+    // previous `link · parent` order applied ancestors first, which put nested
+    // child trafos in WORLD space — invisible for the ubiquitous single-link
+    // chains, wrong for e.g. a translate under an adaptive billboard trafo.)
+    // node.world.inv = link.inv · parent.world.inv  (reversed accordingly).
     if (parent === undefined) {
       recs.add(node, CHAIN_RULE_ID, h(modelPair.fwd), [1, h(link.fwd)]);
       recs.add(node, CHAIN_RULE_ID, h(modelPair.inv), [1, h(link.inv)]);
     } else {
-      recs.add(node, CHAIN_RULE_ID, h(modelPair.fwd), [2, h(link.fwd), h(parent.modelPair.fwd)]);
-      recs.add(node, CHAIN_RULE_ID, h(modelPair.inv), [2, h(parent.modelPair.inv), h(link.inv)]);
+      recs.add(node, CHAIN_RULE_ID, h(modelPair.fwd), [2, h(parent.modelPair.fwd), h(link.fwd)]);
+      recs.add(node, CHAIN_RULE_ID, h(modelPair.inv), [2, h(link.inv), h(parent.modelPair.inv)]);
     }
     return node;
   }

package/src/runtime/flattenTree.ts

@@ -19,6 +19,49 @@ import { AListBridges } from "@aardworx/wombat.adaptive";
 import type { RenderObject } from "../core/renderObject.js";
 import type { RenderTree } from "../core/renderTree.js";
 
+/** True when `tree` contains no reactive nodes — its RenderObjects can
+ *  be enumerated as a plain iterable (no inner aset / reader needed). */
+function isStaticTree(tree: RenderTree): boolean {
+  switch (tree.kind) {
+    case "Empty":
+    case "Leaf":
+      return true;
+    case "Ordered":
+    case "Unordered":
+      return tree.children.every(isStaticTree);
+    default:
+      return false;
+  }
+}
+
+/** Enumerate a static subtree's RenderObjects (pre: `isStaticTree`). */
+function* staticObjects(tree: RenderTree): Iterable<RenderObject> {
+  switch (tree.kind) {
+    case "Empty":
+      return;
+    case "Leaf":
+      yield tree.object;
+      return;
+    case "Ordered":
+    case "Unordered":
+      for (const c of tree.children) yield* staticObjects(c);
+      return;
+    default:
+      throw new Error(`staticObjects: reactive node '${tree.kind}'`);
+  }
+}
+
+/** Flatten a reactive container of subtrees. The static children go
+ *  through `collectSeq` (plain iterables — ONE reader for the whole
+ *  set, instead of a ConstantAset + reader + subscription PER LEAF,
+ *  which at heap scale was megabytes of ballast); reactive children
+ *  keep the full `collect`. */
+function flattenChildSet(children: aset<RenderTree>): aset<RenderObject> {
+  const staticPart = children.filter(isStaticTree).collectSeq(staticObjects);
+  const reactivePart = children.filter(t => !isStaticTree(t)).collect(flattenRenderTree);
+  return ASet.union(staticPart, reactivePart);
+}
+
 export function flattenRenderTree(tree: RenderTree): aset<RenderObject> {
   switch (tree.kind) {
     case "Empty":
@@ -27,6 +70,8 @@ export function flattenRenderTree(tree: RenderTree): aset<RenderObject> {
       return ASet.single(tree.object);
     case "Ordered":
     case "Unordered": {
+      // Fully-static subtree → one constant aset over a plain array.
+      if (isStaticTree(tree)) return ASet.ofArray([...staticObjects(tree)]);
       // N-ary union via `unionMany(aset<aset<T>>)`. The naïve
       // `children.reduce(ASet.union)` builds a 2N-deep nested-union
       // tree; the reader's traversal recurses through it and blows
@@ -39,8 +84,8 @@ export function flattenRenderTree(tree: RenderTree): aset<RenderObject> {
     case "Adaptive":
       return ASet.bind(flattenRenderTree, tree.tree);
     case "OrderedFromList":
-      return ASet.collect(flattenRenderTree, AListBridges.toASet(tree.children));
+      return flattenChildSet(AListBridges.toASet(tree.children));
     case "UnorderedFromSet":
-      return ASet.collect(flattenRenderTree, tree.children);
+      return flattenChildSet(tree.children);
   }
 }