@aardworx/wombat.rendering 0.9.2 → 0.9.4

package/src/runtime/heapScene.ts

@@ -45,9 +45,9 @@
 import { Trafo3d, V3d, V4f, M44d, type V2f } from "@aardworx/wombat.base";
 import type { ITexture } from "../core/texture.js";
 import type { ISampler } from "../core/sampler.js";
-import { AVal, AdaptiveObject, AdaptiveToken } from "@aardworx/wombat.adaptive";
+import { AVal, AdaptiveObject, AdaptiveToken, HashTable } from "@aardworx/wombat.adaptive";
 import type { aval, aset, IAdaptiveObject, IDisposable, IHashSetReader } from "@aardworx/wombat.adaptive";
-import type { Effect } from "@aardworx/wombat.shader";
+import type { Effect, CompileOptions } from "@aardworx/wombat.shader";
 import type { PipelineState } from "../core/pipelineState.js";
 import type { BufferView } from "../core/bufferView.js";
 import type { IBuffer, HostBufferSource } from "../core/buffer.js";
@@ -174,21 +174,43 @@ const PACKER_F32: WgslPacker = {
   dataBytes: 4, typeId: 0,
   pack: (val, dst, off) => { dst[off] = val as number; },
 };
-// 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: WgslPacker = {
-  dataBytes: 4, typeId: 0,
-  pack: (val, dst, off) => {
-    new Uint32Array(dst.buffer, dst.byteOffset + off * 4, 1)[0] = (val as number) >>> 0;
-  },
-};
-const PACKER_I32: WgslPacker = {
-  dataBytes: 4, typeId: 0,
-  pack: (val, dst, off) => {
-    new Int32Array(dst.buffer, dst.byteOffset + off * 4, 1)[0] = (val as number) | 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: typeof Uint32Array | typeof Int32Array,
+  dim: 1 | 2 | 3 | 4,
+): WgslPacker {
+  const bytes = dim * 4;
+  if (dim === 1) {
+    return {
+      dataBytes: bytes, typeId: 0,
+      pack: (val, dst, off) => {
+        new ctor(dst.buffer as ArrayBuffer, dst.byteOffset + off * 4, 1)[0] = val as number;
+      },
+    };
+  }
+  // Vector: accept {x,y,z,w} components.
+  return {
+    dataBytes: bytes, typeId: 0,
+    pack: (val, dst, off) => {
+      const view = new ctor(dst.buffer as ArrayBuffer, dst.byteOffset + off * 4, dim);
+      const v = val as { x: number; y: number; z?: number; w?: number };
+      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: string): WgslPacker {
   switch (wgslType) {
@@ -198,7 +220,13 @@ function packerForWgslType(wgslType: string): WgslPacker {
     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}'`);
   }
@@ -330,6 +358,17 @@ interface PoolEntry {
  * 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`.)
   private readonly byAval = new Map<aval<unknown>, PoolEntry>();
 
   has(aval: aval<unknown>): boolean { return this.byAval.has(aval); }
@@ -603,19 +642,62 @@ class AttributeArena {
   }
   release(ref: number, dataBytes: number): void {
     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: () => void): IDisposable { return this.buf.onResize(cb); }
   destroy(): void { 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: number; size: number }[],
+  off: number,
+  size: number,
+): void {
+  // 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
@@ -674,13 +756,7 @@ class IndexAllocator {
     return off;
   }
   release(off: number, elements: number): void {
-    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: () => void): IDisposable { return this.buf.onResize(cb); }
   destroy(): void { this.buf.destroy(); }
@@ -995,8 +1071,15 @@ interface Bucket {
    */
   readonly localLayoutIds: (number | undefined)[];
 
-  /** Live local slots (drives the render loop). */
-  readonly drawSlots: number[];
+  /**
+   * Live local slots. A Set rather than an array so addDraw/removeDraw
+   * are both O(1): a 500-element bulk-remove on a 1000-element bucket
+   * would otherwise burn 250K shifts in the linear-array splice path.
+   * The render loop iterates this once per frame; iteration order
+   * isn't load-bearing (slot→record indirection happens via
+   * `slotToRecord` / `recordToSlot`).
+   */
+  readonly drawSlots: Set<number>;
   /** Local slots whose DrawHeader needs re-pack + writeBuffer next frame. */
   readonly dirty: Set<number>;
 
@@ -1039,6 +1122,12 @@ interface Bucket {
    * GrowBuffer reallocation. Standalone-only buckets keep this empty.
    */
   readonly localAtlasTextures: ((HeapTextureSet & { kind: "atlas" }) | undefined)[];
+  /**
+   * Per-local-slot index into `atlasAvalRefs[sourceAval]` — lets
+   * removeDraw do swap-pop without an O(N) findIndex scan. `undefined`
+   * for slots without an atlas source aval.
+   */
+  readonly localAtlasArrIdx: (number | undefined)[];
 }
 
 // ---------------------------------------------------------------------------
@@ -1310,6 +1399,19 @@ export function buildHeapScene(
     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: { format: GPUTextureFormat }[] = [];
+  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) ────────
@@ -1513,7 +1615,11 @@ export function buildHeapScene(
     readonly repack: (newTex: ITexture) => import("./textureAtlas/atlasPool.js").AtlasAcquisition;
     readonly sampler: ISampler;
   }
-  const atlasAvalRefs = new Map<aval<ITexture>, AtlasAvalRef[]>();
+  // 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<aval<ITexture>, AtlasAvalRef[]>();
   /**
    * Per-draw bucket dirty (rare in steady state — only fires when
    * something forces a header rewrite, e.g. a drawHeap GrowBuffer
@@ -1750,9 +1856,20 @@ export function buildHeapScene(
     schema: ShaderFamilySchema;
     vsModule: GPUShaderModule;
     fsModule: GPUShaderModule;
-    fieldsForEffect: Map<Effect, Set<string>>;
+    /** Actual @vertex entry-point name in `vsModule`. */
+    vsEntryName: string;
+    /** Actual @fragment entry-point name in `fsModule`. */
+    fsEntryName: string;
+    fieldsForEffect: Map<string, Set<string>>;
   }
-  const familyByEffect = new Map<Effect, FamilyState>();
+  // 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<string, FamilyState>();
   let familyBuilt = false;
   const enableFamilyMerge = opts.enableFamilyMerge === true;
 
@@ -1760,26 +1877,50 @@ export function buildHeapScene(
     effects: readonly Effect[],
     perInstanceByEffect: ReadonlyMap<Effect, { attributes: Set<string>; uniforms: Set<string> }>,
   ): FamilyState {
+    // 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(
-      effects, opts.fragmentOutputLayout, undefined,
+      [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 fieldsForEffect = new Map<Effect, Set<string>>();
-    for (const e of schema.effects) {
-      const s = schema.perEffectSchema.get(e)!;
-      const fields = new Set<string>();
-      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 compileOpts: CompileOptions = 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<string, Set<string>>();
+    const s = schema.perEffectSchema.get(effect)!;
+    const fields = new Set<string>();
+    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: readonly HeapDrawSpec[]): void {
@@ -1793,45 +1934,42 @@ export function buildHeapScene(
     // layout to address per-instance attribute reads via `instId`
     // instead of `vertex_index` — without this, instanced effects
     // produce broken geometry.
-    const seen = new Set<Effect>();
+    // 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<string>();
     const unique: Effect[] = [];
-    const perInstanceByEffect = new Map<Effect, {
+    const perInstanceByEffectId = new Map<string, {
       attributes: Set<string>;
       uniforms: Set<string>;
     }>();
     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<string>(), uniforms: new Set<string>() };
-        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); unique.push(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<Effect, { attributes: Set<string>; uniforms: Set<string> }>();
-        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<Effect, { attributes: Set<string>; uniforms: Set<string> }>();
+      if (perI !== undefined) singleMap.set(e, perI);
+      familyByEffectId.set(e.id, compileFamilyFor([e], singleMap));
     }
     familyBuilt = true;
   }
 
   function familyFor(effect: Effect): FamilyState {
-    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`,
@@ -1857,13 +1995,89 @@ export function buildHeapScene(
     if (id === undefined) { id = `tex#${texCounter++}`; textureIds.set(t, id); }
     return id;
   };
-  const psIds = new WeakMap<PipelineState, string>();
-  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<object, number>();
+  const valueIds = new Map<string, number>();
+  let avalCounter = 0;
+  const avalIdOf = (av: aval<unknown> | undefined): string => {
+    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 as { isConstant?: unknown }).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: string;
+    if (
+      v !== null && typeof v === "object" &&
+      typeof (v as { getHashCode?: unknown }).getHashCode === "function" &&
+      typeof (v as { equals?: unknown }).equals === "function"
+    ) {
+      const hc = (v as { getHashCode(): number }).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 as object);
+      if (oid === undefined) { oid = avalCounter++; avalIds.set(v as object, 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<PipelineState, string>();
   const psIdOf = (ps: PipelineState | undefined): string => {
     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: string[] = [
+      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;
   };
 
   /** Resolved (forced) snapshot of the user's PipelineState. */
@@ -2074,15 +2288,15 @@ export function buildHeapScene(
     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 } }
@@ -2114,7 +2328,7 @@ export function buildHeapScene(
       localPosRefs: [], localNorRefs: [],
       localEntries: [], localToDrawId: [],
       localPerDrawAvals: [], localPerDrawRefs: [], localLayoutIds: [],
-      drawSlots: [], dirty: new Set<number>(),
+      drawSlots: new Set<number>(), dirty: new Set<number>(),
       drawTableDirtyMin: Infinity, drawTableDirtyMax: 0,
       recordCount: 0, slotToRecord: [], recordToSlot: [],
       totalEmitEstimate: 0,
@@ -2122,6 +2336,7 @@ export function buildHeapScene(
       isAtlasBucket,
       localAtlasReleases: [],
       localAtlasTextures: [],
+      localAtlasArrIdx: [],
     };
     {
       const dtBuf = new GrowBuffer(
@@ -2343,7 +2558,21 @@ export function buildHeapScene(
   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: HeapDrawSpec): number {
+    let id = -1;
+    sceneObj.evaluateAlways(AdaptiveToken.top, (tok) => {
+      id = addDrawImpl(spec, tok);
+    });
+    return id;
+  }
+  function addDrawImpl(spec: HeapDrawSpec, outerTok: AdaptiveToken): number {
     const drawId = nextDrawId++;
     // Family-merge (slice 3c): build the family lazily from this
     // single spec when no batched lazy-build occurred earlier (e.g.
@@ -2360,7 +2589,7 @@ export function buildHeapScene(
       : new Set<string>();
     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
@@ -2382,7 +2611,8 @@ export function buildHeapScene(
     // emerges from aval identity either way.
     const perDrawAvals: aval<unknown>[] = [];
     const perDrawRefs = new Map<string, number>();
-    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.
@@ -2454,7 +2684,7 @@ export function buildHeapScene(
         perDrawRefs.set(f.name, ref);
         perDrawAvals.push(av);
       }
-    });
+    }
 
     bucket.localPosRefs[localSlot] = perDrawRefs.get("Positions");
     bucket.localNorRefs[localSlot] = perDrawRefs.get("Normals");
@@ -2462,7 +2692,7 @@ export function buildHeapScene(
       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)!;
@@ -2478,15 +2708,14 @@ export function buildHeapScene(
       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 });
       }
     }
@@ -2629,11 +2858,18 @@ export function buildHeapScene(
     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);
@@ -2643,6 +2879,7 @@ export function buildHeapScene(
     }
     bucket.localAtlasReleases[localSlot] = undefined;
     bucket.localAtlasTextures[localSlot] = undefined;
+    bucket.localAtlasArrIdx[localSlot] = undefined;
 
     bucket.localPerDrawAvals[localSlot] = undefined;
     bucket.localPerDrawRefs[localSlot]  = undefined;
@@ -2651,8 +2888,7 @@ export function buildHeapScene(
     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);
 
@@ -2672,7 +2908,11 @@ export function buildHeapScene(
     const delta = asetReader.getChanges(tok);
     delta.iter((op: { value: HeapDrawSpec; count: number }) => {
       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 {
         const id = specToDrawId.get(op.value);
@@ -2691,7 +2931,9 @@ export function buildHeapScene(
     // array is empty (family will build lazily when an addDraw fires).
     const arr = initialDraws as readonly HeapDrawSpec[];
     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 as aset<HeapDrawSpec>).getReader();
     sceneObj.evaluateAlways(AdaptiveToken.top, (tok) => {
@@ -2711,7 +2953,7 @@ export function buildHeapScene(
         if (adds.length > 0) 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 {
             const id = specToDrawId.get(op.value);