@aardworx/wombat.rendering 0.9.2 → 0.9.4

package/dist/runtime/heapScene.js

@@ -42,7 +42,7 @@
 // package adds the texture (binding 4) + sampler (binding 5) to that
 // group's bind-group layout; the user's FS WGSL declares them.
 import { Trafo3d, V3d, V4f, M44d } from "@aardworx/wombat.base";
-import { AVal, AdaptiveObject, AdaptiveToken } from "@aardworx/wombat.adaptive";
+import { AVal, AdaptiveObject, AdaptiveToken, HashTable } from "@aardworx/wombat.adaptive";
 import { buildBucketLayout, compileHeapEffect, } from "./heapEffect.js";
 import { compileHeapEffectIR } from "./heapEffectIR.js";
 import { buildShaderFamily, compileShaderFamily, } from "./heapShaderFamily.js";
@@ -115,21 +115,43 @@ const PACKER_F32 = {
     dataBytes: 4, typeId: 0,
     pack: (val, dst, off) => { dst[off] = val; },
 };
-// u32 lives in the arena as 4 bytes too — we write through a transient
-// Uint32 view over the same backing buffer so the integer bit-pattern is
-// preserved (Float32Array assignment would lossily truncate `(u32) -> f32`).
-const PACKER_U32 = {
-    dataBytes: 4, typeId: 0,
-    pack: (val, dst, off) => {
-        new Uint32Array(dst.buffer, dst.byteOffset + off * 4, 1)[0] = val >>> 0;
-    },
-};
-const PACKER_I32 = {
-    dataBytes: 4, typeId: 0,
-    pack: (val, dst, off) => {
-        new Int32Array(dst.buffer, dst.byteOffset + off * 4, 1)[0] = val | 0;
-    },
-};
+// Integer scalars / vectors. The arena is fronted by a `Float32Array`,
+// so writing raw bits has to go through a same-buffer Uint32/Int32 view
+// to avoid the lossy `i32 → f32` coercion you'd get from a direct
+// `dst[off] = ...` assignment.
+function makeIntPacker(ctor, dim) {
+    const bytes = dim * 4;
+    if (dim === 1) {
+        return {
+            dataBytes: bytes, typeId: 0,
+            pack: (val, dst, off) => {
+                new ctor(dst.buffer, dst.byteOffset + off * 4, 1)[0] = val;
+            },
+        };
+    }
+    // Vector: accept {x,y,z,w} components.
+    return {
+        dataBytes: bytes, typeId: 0,
+        pack: (val, dst, off) => {
+            const view = new ctor(dst.buffer, dst.byteOffset + off * 4, dim);
+            const v = val;
+            view[0] = v.x;
+            view[1] = v.y;
+            if (dim >= 3)
+                view[2] = v.z;
+            if (dim >= 4)
+                view[3] = v.w;
+        },
+    };
+}
+const PACKER_U32 = makeIntPacker(Uint32Array, 1);
+const PACKER_UVEC2 = makeIntPacker(Uint32Array, 2);
+const PACKER_UVEC3 = makeIntPacker(Uint32Array, 3);
+const PACKER_UVEC4 = makeIntPacker(Uint32Array, 4);
+const PACKER_I32 = makeIntPacker(Int32Array, 1);
+const PACKER_IVEC2 = makeIntPacker(Int32Array, 2);
+const PACKER_IVEC3 = makeIntPacker(Int32Array, 3);
+const PACKER_IVEC4 = makeIntPacker(Int32Array, 4);
 function packerForWgslType(wgslType) {
     switch (wgslType) {
         case "mat4x4<f32>": return PACKER_MAT4;
@@ -138,7 +160,13 @@ function packerForWgslType(wgslType) {
         case "vec2<f32>": return PACKER_VEC2;
         case "f32": return PACKER_F32;
         case "u32": return PACKER_U32;
+        case "vec2<u32>": return PACKER_UVEC2;
+        case "vec3<u32>": return PACKER_UVEC3;
+        case "vec4<u32>": return PACKER_UVEC4;
         case "i32": return PACKER_I32;
+        case "vec2<i32>": return PACKER_IVEC2;
+        case "vec3<i32>": return PACKER_IVEC3;
+        case "vec4<i32>": return PACKER_IVEC4;
         default:
             throw new Error(`heapScene: no JS-side packer for WGSL type '${wgslType}'`);
     }
@@ -221,6 +249,17 @@ class GrowBuffer {
  * Same code path either way.
  */
 class UniformPool {
+    // Keyed by `aval<unknown>` *by reference* (a plain JS `Map`). These
+    // keys are overwhelmingly reactive `cval`s (per-object trafos,
+    // colours, …) and the hot path is `acquire`/`release` ~once per
+    // drawHeader field per RO. A content-keyed `HashTable` would buy
+    // nothing here — reactive avals never compare content-equal — and
+    // would cost: reactive avals have no `equals`/`getHashCode`, so a
+    // `HashTable` falls back to a WeakMap-counter identity hash per
+    // lookup, measurably slower than `Map`'s native hashing. (Constant-
+    // aval dedup matters where keys are *texture* avals — there the
+    // `AtlasPool` is content-keyed; constant avals there carry a cached
+    // hash and a fast `equals`.)
     byAval = new Map();
     has(aval) { return this.byAval.has(aval); }
     entry(aval) { return this.byAval.get(aval); }
@@ -471,22 +510,58 @@ class AttributeArena {
     }
     release(ref, dataBytes) {
         const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes);
-        this.freeList.push({ off: ref, size: allocBytes });
-        // Coalesce adjacent free entries for cleanliness.
-        this.freeList.sort((a, b) => a.off - b.off);
-        for (let i = 0; i < this.freeList.length - 1;) {
-            const a = this.freeList[i], b = this.freeList[i + 1];
-            if (a.off + a.size === b.off) {
-                a.size += b.size;
-                this.freeList.splice(i + 1, 1);
-            }
-            else
-                i++;
-        }
+        insertSortedFreeBlock(this.freeList, ref, allocBytes);
     }
     onResize(cb) { return this.buf.onResize(cb); }
     destroy() { this.buf.destroy(); }
 }
+/**
+ * Insert `{off, size}` into a free-list kept sorted by `off`, then
+ * coalesce with the two immediate neighbours.
+ *
+ * The list invariant — sorted, non-overlapping, never-adjacent — is
+ * preserved across allocs (which take from the front or split a
+ * block) and releases (this function). The previous implementation
+ * did `push + Array.prototype.sort + linear coalesce scan`, which is
+ * O(N log N) per release. Under a 500-RO bulk-remove the sort
+ * dominated `removeDraw` (~41 ms of self-time in the heap-demo-sg
+ * toggle profile). Binary-search insert + 2-neighbour merge collapses
+ * that to O(log N + N-shift), and is principled — the sort never
+ * actually mattered since we already had the sorted prefix as an
+ * invariant.
+ */
+function insertSortedFreeBlock(freeList, off, size) {
+    // Binary-search for the insertion index (first entry whose off > new).
+    let lo = 0, hi = freeList.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (freeList[mid].off <= off)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    // lo is the index where the new entry would be inserted.
+    // Try merging with the predecessor first; if successful, the merged
+    // block may now be adjacent to its (former) successor too.
+    const prev = lo > 0 ? freeList[lo - 1] : undefined;
+    if (prev !== undefined && prev.off + prev.size === off) {
+        prev.size += size;
+        // Check forward-merge with what was freeList[lo].
+        const next = freeList[lo];
+        if (next !== undefined && prev.off + prev.size === next.off) {
+            prev.size += next.size;
+            freeList.splice(lo, 1);
+        }
+        return;
+    }
+    const next = freeList[lo];
+    if (next !== undefined && off + size === next.off) {
+        next.off = off;
+        next.size += size;
+        return;
+    }
+    freeList.splice(lo, 0, { off, size });
+}
 /**
  * Element-bump allocator over an index GrowBuffer (units = u32). Each
  * draw's index range is allocated as one block; on release the block
@@ -550,17 +625,7 @@ class IndexAllocator {
         return off;
     }
     release(off, elements) {
-        this.freeList.push({ off, size: elements });
-        this.freeList.sort((a, b) => a.off - b.off);
-        for (let i = 0; i < this.freeList.length - 1;) {
-            const a = this.freeList[i], b = this.freeList[i + 1];
-            if (a.off + a.size === b.off) {
-                a.size += b.size;
-                this.freeList.splice(i + 1, 1);
-            }
-            else
-                i++;
-        }
+        insertSortedFreeBlock(this.freeList, off, elements);
     }
     onResize(cb) { return this.buf.onResize(cb); }
     destroy() { this.buf.destroy(); }
@@ -784,6 +849,19 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         throw new Error("buildHeapScene: framebuffer signature has no color attachment");
     }
     const colorFormat = sig.colors.tryFind(colorAttachmentName);
+    // All color targets, ordered by the signature's `colorNames`. Each
+    // entry's format flows into the pipeline's `fragment.targets[i].format`.
+    // The fragmentOutputLayout's `locations` map tells the WGSL emit which
+    // output @location maps to which color attachment; this array is the
+    // matching pipeline-side ordering.
+    const colorTargets = [];
+    for (const name of sig.colorNames) {
+        const fmt = sig.colors.tryFind(name);
+        if (fmt === undefined) {
+            throw new Error(`buildHeapScene: signature missing format for color '${name}'`);
+        }
+        colorTargets.push({ format: fmt });
+    }
     const depthFormat = sig.depthStencil?.format;
     // ─── Global arena (uniform/attribute data + index buffer) ────────
     // Initial capacities are just hints; both buffers pow2-grow on
@@ -946,7 +1024,11 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     // buckets) — `atlasAvalRefs` tracks all (bucket, localSlot) pairs so
     // one swap rewrites N drawHeaders in one drain.
     const atlasAvalDirty = new Set();
-    const atlasAvalRefs = new Map();
+    // Content-keyed (`HashTable`, not a JS `Map`) so distinct
+    // `AVal.constant(tex)` wrappers sharing the same texture collapse to
+    // one `(bucket, slot)` ref-list — matching `AtlasPool.entriesByAval`,
+    // which is now content-keyed too. Reactive avals key by reference.
+    const atlasAvalRefs = new HashTable();
     /**
      * Per-draw bucket dirty (rare in steady state — only fires when
      * something forces a header rewrite, e.g. a drawHeap GrowBuffer
@@ -1147,30 +1229,59 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     // ─── Buckets ──────────────────────────────────────────────────────
     const buckets = [];
     const bucketByKey = new Map();
-    const familyByEffect = new Map();
+    // Keyed by `effect.id` (content hash), NOT object identity. Two
+    // Effect objects with identical content (e.g. produced by separate
+    // calls to `effect(...)` or the pickChain composer) share one
+    // FamilyState. This is the right correctness/perf knob: building a
+    // family by content means an upstream caller that legitimately
+    // produces different-but-identical Effect objects per leaf still
+    // reuses one pipeline + one bucket.
+    const familyByEffectId = new Map();
     let familyBuilt = false;
     const enableFamilyMerge = opts.enableFamilyMerge === true;
     function compileFamilyFor(effects, perInstanceByEffect) {
-        const schema = buildShaderFamily(effects, opts.fragmentOutputLayout, undefined, {
+        // Family-merge (multi-effect dispatch via layoutId switch) has been
+        // disabled — it was a perf illusion. Every effect compiles to its
+        // own standalone pipeline; the per-bucket WGSL comes from
+        // `compileHeapEffectIR(effect, layout, opts, "standalone")` and is
+        // used directly as the bucket's shader module (no wrapper, no
+        // dispatch). The schema is still derived from the same
+        // `buildShaderFamily` path so the runtime's drawHeader packer,
+        // bind-group layout, etc. don't change shape — `__layoutId`
+        // remains a u32 slot that's written as 0 per RO (harmless).
+        //
+        // `heapShaderFamily.compileShaderFamily` is kept around but
+        // unused; the function and its tests stay disabled.
+        if (effects.length !== 1) {
+            throw new Error("heapScene: multi-effect family-merge disabled (was a perf illusion). " +
+                "Build one bucket per effect.");
+        }
+        const effect = effects[0];
+        const schema = buildShaderFamily([effect], opts.fragmentOutputLayout, undefined, {
             atlasizeAllTextures: atlasPool !== undefined,
             perEffectPerInstance: perInstanceByEffect,
         });
-        const compiled = compileShaderFamily(schema, opts.fragmentOutputLayout);
-        const vsModule = device.createShaderModule({ code: compiled.vs, label: `heapScene/family/${schema.id}/vs` });
-        const fsModule = device.createShaderModule({ code: compiled.fs, label: `heapScene/family/${schema.id}/fs` });
+        const compileOpts = opts.fragmentOutputLayout !== undefined
+            ? { target: "wgsl", fragmentOutputLayout: opts.fragmentOutputLayout }
+            : { target: "wgsl" };
+        const ir = compileHeapEffectIR(effect, schema.drawHeaderUnion, compileOpts, "standalone");
+        const vsModule = device.createShaderModule({ code: ir.vs, label: `heapScene/standalone/${schema.id}/vs` });
+        const fsModule = device.createShaderModule({ code: ir.fs, label: `heapScene/standalone/${schema.id}/fs` });
         const fieldsForEffect = new Map();
-        for (const e of schema.effects) {
-            const s = schema.perEffectSchema.get(e);
-            const fields = new Set();
-            for (const a of s.attributes)
-                fields.add(a.name);
-            for (const u of s.uniforms)
-                fields.add(u.name);
-            for (const t of s.textures)
-                fields.add(t.name);
-            fieldsForEffect.set(e, fields);
-        }
-        return { schema, vsModule, fsModule, fieldsForEffect };
+        const s = schema.perEffectSchema.get(effect);
+        const fields = new Set();
+        for (const a of s.attributes)
+            fields.add(a.name);
+        for (const u of s.uniforms)
+            fields.add(u.name);
+        for (const t of s.textures)
+            fields.add(t.name);
+        fieldsForEffect.set(effect.id, fields);
+        return {
+            schema, vsModule, fsModule, fieldsForEffect,
+            vsEntryName: ir.vsEntry,
+            fsEntryName: ir.fsEntry,
+        };
     }
     function buildFamilyFromSpecs(specs) {
         if (familyBuilt)
@@ -1184,48 +1295,43 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         // layout to address per-instance attribute reads via `instId`
         // instead of `vertex_index` — without this, instanced effects
         // produce broken geometry.
-        const seen = new Set();
+        // De-dupe by effect.id so two Effects with identical content but
+        // distinct object identities collapse to one family + one bucket.
+        const seenIds = new Set();
         const unique = [];
-        const perInstanceByEffect = new Map();
+        const perInstanceByEffectId = new Map();
         for (const spec of specs) {
             const e = spec.effect;
-            let entry = perInstanceByEffect.get(e);
+            let entry = perInstanceByEffectId.get(e.id);
             if (entry === undefined) {
                 entry = { attributes: new Set(), uniforms: new Set() };
-                perInstanceByEffect.set(e, entry);
+                perInstanceByEffectId.set(e.id, entry);
             }
             if (spec.instanceAttributes !== undefined) {
                 for (const name of Object.keys(spec.instanceAttributes))
                     entry.attributes.add(name);
             }
-            if (!seen.has(e)) {
-                seen.add(e);
+            if (!seenIds.has(e.id)) {
+                seenIds.add(e.id);
                 unique.push(e);
             }
         }
-        if (enableFamilyMerge) {
-            const merged = compileFamilyFor(unique, perInstanceByEffect);
-            for (const e of unique)
-                familyByEffect.set(e, merged);
-        }
-        else {
-            // Default: one family per effect — no shared layoutId switch.
-            // Per-effect bucketing is at-or-better than merged on tested
-            // workloads; merge stays opt-in pending trace-based v2.
-            for (const e of unique) {
-                const perI = perInstanceByEffect.get(e);
-                const singleMap = new Map();
-                if (perI !== undefined)
-                    singleMap.set(e, perI);
-                familyByEffect.set(e, compileFamilyFor([e], singleMap));
-            }
+        // Family-merge disabled: always one bucket per effect.
+        // `enableFamilyMerge` is ignored.
+        void enableFamilyMerge;
+        for (const e of unique) {
+            const perI = perInstanceByEffectId.get(e.id);
+            const singleMap = new Map();
+            if (perI !== undefined)
+                singleMap.set(e, perI);
+            familyByEffectId.set(e.id, compileFamilyFor([e], singleMap));
         }
         familyBuilt = true;
     }
     function familyFor(effect) {
-        const f = familyByEffect.get(effect);
+        const f = familyByEffectId.get(effect.id);
         if (f === undefined) {
-            const known = [...familyByEffect.keys()].map(e => e.id).join(",");
+            const known = [...familyByEffectId.keys()].join(",");
             throw new Error(`heapScene: family is frozen; effect ${effect.id} not in {${known}}; ` +
                 `reactive family rebuild is v2`);
         }
@@ -1251,17 +1357,102 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         }
         return id;
     };
-    const psIds = new WeakMap();
-    let psCounter = 0;
+    // PipelineState content key. Hashes by the identities of the inner
+    // aval references rather than the wrapper object itself: callers
+    // (notably `wombat.dom`'s `derivePipelineState`) construct a fresh
+    // PipelineState object per leaf even when every contributing aval
+    // is shared — without a content-aware key, every leaf gets its own
+    // bucket and the heap path's drawIndirect coalescing collapses to
+    // one record per bucket. With this key, two leaves that pulled the
+    // same `state.mode` / `state.cullMode` / `state.depthTest` / … avals
+    // bucket together.
+    //
+    // For CONSTANT avals (`isConstant === true`) we key by *value* — two
+    // distinct `AVal.constant(0)` objects produced at different call
+    // sites must collapse to the same bucket. Reactive avals fall back
+    // to reference identity (the right semantic — value can tick).
+    const avalIds = new WeakMap();
+    const valueIds = new Map();
+    let avalCounter = 0;
+    const avalIdOf = (av) => {
+        if (av === undefined)
+            return "_";
+        // Reactive aval — key by reference. (`isConstant` is on the
+        // public IAdaptive surface; guard via runtime check so off-spec
+        // duck-types don't blow up.)
+        const isConst = av.isConstant === true;
+        if (!isConst) {
+            let id = avalIds.get(av);
+            if (id === undefined) {
+                id = avalCounter++;
+                avalIds.set(av, id);
+            }
+            return `a${id}`;
+        }
+        // Constant: key by value. Force is safe (constant: no upstream
+        // dep) and only runs once per distinct aval-object thanks to the
+        // outer avalIds cache below.
+        let id = avalIds.get(av);
+        if (id !== undefined)
+            return `c${id}`;
+        // Constant avals ignore the token; use AdaptiveToken.top to satisfy
+        // the type and traverse a no-op evaluation.
+        const v = av.getValue(AdaptiveToken.top);
+        // Value-typed (`equals` + `getHashCode`)? Try to intern by hash
+        // bucket + equals so two distinct AVal.constant(M44d.identity)
+        // collapse. Falls back to a per-value string key otherwise.
+        let vKey;
+        if (v !== null && typeof v === "object" &&
+            typeof v.getHashCode === "function" &&
+            typeof v.equals === "function") {
+            const hc = v.getHashCode() | 0;
+            vKey = `hv:${hc}`;
+        }
+        else if (v === null || typeof v !== "object") {
+            vKey = `pv:${typeof v}:${String(v)}`;
+        }
+        else {
+            // Plain object — fall back to reference identity (matches the
+            // memo runtime's behaviour for unhashable objects).
+            let oid = avalIds.get(v);
+            if (oid === undefined) {
+                oid = avalCounter++;
+                avalIds.set(v, oid);
+            }
+            vKey = `ov:${oid}`;
+        }
+        let vid = valueIds.get(vKey);
+        if (vid === undefined) {
+            vid = avalCounter++;
+            valueIds.set(vKey, vid);
+        }
+        avalIds.set(av, vid);
+        return `c${vid}`;
+    };
+    const psContentIds = new WeakMap();
     const psIdOf = (ps) => {
         if (ps === undefined)
             return "ps#default";
-        let id = psIds.get(ps);
-        if (id === undefined) {
-            id = `ps#${psCounter++}`;
-            psIds.set(ps, id);
-        }
-        return id;
+        const cached = psContentIds.get(ps);
+        if (cached !== undefined)
+            return cached;
+        const r = ps.rasterizer;
+        const parts = [
+            avalIdOf(r.topology),
+            avalIdOf(r.cullMode),
+            avalIdOf(r.frontFace),
+            avalIdOf(r.depthBias),
+            ps.depth !== undefined
+                ? `d:${avalIdOf(ps.depth.write)}:${avalIdOf(ps.depth.compare)}:${avalIdOf(ps.depth.clamp)}`
+                : "d:_",
+            ps.stencil !== undefined ? "s:1" : "s:_",
+            avalIdOf(ps.blends),
+            avalIdOf(ps.alphaToCoverage),
+            avalIdOf(ps.blendConstant),
+        ];
+        const key = `ps#${parts.join("|")}`;
+        psContentIds.set(ps, key);
+        return key;
     };
     function resolvePipelineState(ps) {
         if (ps === undefined) {
@@ -1446,14 +1637,14 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         const isAtlasBucket = layout.atlasTextureBindings.size > 0;
         const vsModule = fam.vsModule;
         const fsModule = fam.fsModule;
-        const vsEntry = "family_vs_main";
-        const fsEntry = "family_fs_main";
+        const vsEntry = fam.vsEntryName;
+        const fsEntry = fam.fsEntryName;
         const { pipelineLayout } = getBgl(layout, isAtlasBucket);
         const pipeline = device.createRenderPipeline({
             label: `heapScene/${bk}/pipeline`,
             layout: pipelineLayout,
             vertex: { module: vsModule, entryPoint: vsEntry, buffers: [] },
-            fragment: { module: fsModule, entryPoint: fsEntry, targets: [{ format: colorFormat }] },
+            fragment: { module: fsModule, entryPoint: fsEntry, targets: colorTargets },
             primitive: { topology: ps.topology, cullMode: ps.cullMode, frontFace: ps.frontFace },
             ...(depthFormat !== undefined && ps.depth !== undefined
                 ? { depthStencil: { format: depthFormat, depthWriteEnabled: ps.depth.write, depthCompare: ps.depth.compare } }
@@ -1480,7 +1671,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             localPosRefs: [], localNorRefs: [],
             localEntries: [], localToDrawId: [],
             localPerDrawAvals: [], localPerDrawRefs: [], localLayoutIds: [],
-            drawSlots: [], dirty: new Set(),
+            drawSlots: new Set(), dirty: new Set(),
             drawTableDirtyMin: Infinity, drawTableDirtyMax: 0,
             recordCount: 0, slotToRecord: [], recordToSlot: [],
             totalEmitEstimate: 0,
@@ -1488,6 +1679,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             isAtlasBucket,
             localAtlasReleases: [],
             localAtlasTextures: [],
+            localAtlasArrIdx: [],
         };
         {
             const dtBuf = new GrowBuffer(device, `heapScene/${bk}/drawTable`, GPUBufferUsage.STORAGE, 1024);
@@ -1681,7 +1873,21 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     };
     Object.defineProperty(stats, "groups", { get: () => buckets.length, configurable: true });
     // ─── addDraw / removeDraw ─────────────────────────────────────────
+    // Public addDraw wrapper. Establishes a sceneObj.evaluateAlways
+    // scope so external callers (no batched outer eval) still register
+    // sceneObj as an output of any aval the spec touches. Internal call
+    // sites (drainAsetWith, batched initial-population) already run
+    // inside a single outer evaluateAlways and invoke addDrawImpl
+    // directly with their token — collapsing 1000× nested
+    // evaluateAlways into 1× outer.
     function addDraw(spec) {
+        let id = -1;
+        sceneObj.evaluateAlways(AdaptiveToken.top, (tok) => {
+            id = addDrawImpl(spec, tok);
+        });
+        return id;
+    }
+    function addDrawImpl(spec, outerTok) {
         const drawId = nextDrawId++;
         // Family-merge (slice 3c): build the family lazily from this
         // single spec when no batched lazy-build occurred earlier (e.g.
@@ -1699,7 +1905,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             : new Set();
         const bucket = findOrCreateBucket(spec.effect, spec.textures, spec.pipelineState);
         const fam = familyFor(spec.effect);
-        const effectFields = fam.fieldsForEffect.get(spec.effect);
+        const effectFields = fam.fieldsForEffect.get(spec.effect.id);
         // Indices live in their own INDEX-usage buffer (WebGPU constraint).
         // Aval-keyed: 19K instanced clones of the same mesh share one
         // index allocation + one upload.
@@ -1718,7 +1924,8 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         // emerges from aval identity either way.
         const perDrawAvals = [];
         const perDrawRefs = new Map();
-        sceneObj.evaluateAlways(AdaptiveToken.top, (tok) => {
+        {
+            const tok = outerTok;
             for (const f of bucket.layout.drawHeaderFields) {
                 // Atlas-variant texture bindings carry inline values rather than
                 // pool refs; packAtlasTextureFields fills them after this loop.
@@ -1783,14 +1990,14 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 perDrawRefs.set(f.name, ref);
                 perDrawAvals.push(av);
             }
-        });
+        }
         bucket.localPosRefs[localSlot] = perDrawRefs.get("Positions");
         bucket.localNorRefs[localSlot] = perDrawRefs.get("Normals");
         bucket.localEntries[localSlot] = {
             indexCount: idxAlloc.count, firstIndex: idxAlloc.firstIndex, instanceCount,
         };
         bucket.localToDrawId[localSlot] = drawId;
-        bucket.drawSlots.push(localSlot);
+        bucket.drawSlots.add(localSlot);
         bucket.localPerDrawAvals[localSlot] = perDrawAvals;
         bucket.localPerDrawRefs[localSlot] = perDrawRefs;
         const layoutId = fam.schema.layoutIdOf.get(spec.effect);
@@ -1805,15 +2012,14 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             const sourceAval = spec.textures.sourceAval;
             const repackFn = spec.textures.repack;
             if (sourceAval !== undefined && repackFn !== undefined) {
-                sceneObj.evaluateAlways(AdaptiveToken.top, (tok) => {
-                    // touch — registers sceneObj as an output of sourceAval.
-                    sourceAval.getValue(tok);
-                });
+                // touch — registers sceneObj as an output of sourceAval.
+                sourceAval.getValue(outerTok);
                 let arr = atlasAvalRefs.get(sourceAval);
                 if (arr === undefined) {
                     arr = [];
                     atlasAvalRefs.set(sourceAval, arr);
                 }
+                bucket.localAtlasArrIdx[localSlot] = arr.length;
                 arr.push({ bucket, localSlot, repack: repackFn, sampler: spec.textures.sampler });
             }
         }
@@ -1963,12 +2169,18 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         const atlasTex = bucket.localAtlasTextures[localSlot];
         if (atlasTex !== undefined) {
             const sourceAval = atlasTex.sourceAval;
-            if (sourceAval !== undefined) {
+            const i = bucket.localAtlasArrIdx[localSlot];
+            if (sourceAval !== undefined && i !== undefined) {
                 const arr = atlasAvalRefs.get(sourceAval);
                 if (arr !== undefined) {
-                    const i = arr.findIndex(r => r.bucket === bucket && r.localSlot === localSlot);
-                    if (i >= 0)
-                        arr.splice(i, 1);
+                    // Swap-pop: O(1) regardless of array length.
+                    const last = arr.length - 1;
+                    if (i !== last) {
+                        const moved = arr[last];
+                        arr[i] = moved;
+                        moved.bucket.localAtlasArrIdx[moved.localSlot] = i;
+                    }
+                    arr.pop();
                     if (arr.length === 0) {
                         atlasAvalRefs.delete(sourceAval);
                         atlasAvalDirty.delete(sourceAval);
@@ -1978,6 +2190,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         }
         bucket.localAtlasReleases[localSlot] = undefined;
         bucket.localAtlasTextures[localSlot] = undefined;
+        bucket.localAtlasArrIdx[localSlot] = undefined;
         bucket.localPerDrawAvals[localSlot] = undefined;
         bucket.localPerDrawRefs[localSlot] = undefined;
         bucket.localLayoutIds[localSlot] = undefined;
@@ -1985,9 +2198,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         bucket.localNorRefs[localSlot] = undefined;
         bucket.localEntries[localSlot] = undefined;
         bucket.localToDrawId[localSlot] = undefined;
-        const idx = bucket.drawSlots.indexOf(localSlot);
-        if (idx >= 0)
-            bucket.drawSlots.splice(idx, 1);
+        bucket.drawSlots.delete(localSlot);
         bucket.dirty.delete(localSlot);
         bucket.drawHeap.release(localSlot);
         drawIdToBucket[drawId] = undefined;
@@ -2005,7 +2216,11 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         const delta = asetReader.getChanges(tok);
         delta.iter((op) => {
             if (op.count > 0) {
-                const id = addDraw(op.value);
+                // Re-use the outer evaluateAlways scope's token (caller is
+                // already sceneObj) — collapses N nested evaluateAlways into
+                // one for a bulk add. Saves a per-RO setUnsafeEvaluationDepth
+                // + outputs.add(sceneObj) round trip.
+                const id = addDrawImpl(op.value, tok);
                 specToDrawId.set(op.value, id);
             }
             else {
@@ -2025,8 +2240,10 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         const arr = initialDraws;
         if (arr.length > 0)
             buildFamilyFromSpecs(arr);
-        for (const d of arr)
-            addDraw(d);
+        sceneObj.evaluateAlways(AdaptiveToken.top, (tok) => {
+            for (const d of arr)
+                addDrawImpl(d, tok);
+        });
     }
     else {
         asetReader = initialDraws.getReader();
@@ -2049,7 +2266,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                     buildFamilyFromSpecs(adds);
                 for (const op of remaining) {
                     if (op.count > 0) {
-                        const id = addDraw(op.value);
+                        const id = addDrawImpl(op.value, tok);
                         specToDrawId.set(op.value, id);
                     }
                     else {