@aardworx/wombat.rendering 0.19.24 → 0.20.0

package/dist/runtime/heapScene.js

@@ -43,7 +43,7 @@
 // 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, HashTable } from "@aardworx/wombat.adaptive";
-import { buildBucketLayout, compileHeapEffect, } from "./heapEffect.js";
+import { INLINE_HEADER_UNIFORMS, buildBucketLayout, compileHeapEffect, } from "./heapEffect.js";
 import { compileHeapEffectIR } from "./heapEffectIR.js";
 import { buildShaderFamily, compileShaderFamily, } from "./heapShaderFamily.js";
 import { ATLAS_PAGE_FORMATS, atlasFormatIndex, } from "./textureAtlas/atlasPool.js";
@@ -52,7 +52,7 @@ import { DerivedUniformsScene, registerRoDerivations, deregisterRoDerivations, i
 import { packerForWgslType, PACKER_MAT4 } from "./heapScene/packers.js";
 import { HEAP_SCAN_WGSL, SCAN_TILE_SIZE, SCAN_WG_SIZE, SCAN_MAX_RECORDS, TILE_K, RECORD_U32, RECORD_BYTES, } from "./heapScene/scanKernel.js";
 import { GrowBuffer, MIN_BUFFER_BYTES, POW2, ALIGN16, } from "./heapScene/growBuffer.js";
-import { UniformPool, IndexPool, DrawHeap, AttributeArena, IndexAllocator, buildArenaState, arenaBytes, writeAttribute, asAval, isBufferView, asFloat32, ALLOC_HEADER_BYTES, ALLOC_HEADER_PAD_TO, ENC_V3F_TIGHT, SEM_POSITIONS, SEM_NORMALS, } from "./heapScene/pools.js";
+import { UniformPool, IndexPool, DrawHeap, buildArenaState, arenaBytes, writeAttribute, asAval, isBufferView, asFloat32, ALLOC_HEADER_BYTES, ALLOC_HEADER_PAD_TO, ENC_V3F_TIGHT, ENC_OCT32, ENC_C4B, SEM_POSITIONS, SEM_NORMALS, COMPACTION_WASTE_FLOOR_BYTES, } from "./heapScene/pools.js";
 import { encodeModeKey } from "./pipelineCache/index.js";
 import { snapshotDescriptor, ModeKeyTracker } from "./derivedModes/modeKeyCpu.js";
 import { GpuPartitionScene } from "./derivedModes/partitionDispatcher.js";
@@ -60,6 +60,41 @@ import { emitPartitionKernel, substituteReadInputInStmt, collectUniformReadsInSt
 import {} from "./derivedModes/rule.js";
 import { addMarkingCallback } from "@aardworx/wombat.adaptive";
 import { analyseOutputSet, evaluateStructural, evaluateStructuralSet, stableStringify, } from "@aardworx/wombat.shader/ir";
+const NOOP = () => { };
+const packPackedAttr = (val, dst, off) => {
+    const src = val.data;
+    new Uint32Array(dst.buffer, dst.byteOffset + off * 4, src.length).set(src);
+};
+const packF32Verbatim = (val, dst, off) => {
+    dst.set(val, off);
+};
+const packHostU32Bits = (val, dst, off) => {
+    const ibuf = val;
+    if (ibuf.kind !== "host") {
+        throw new Error("heapScene: packed BufferView aval flipped to native GPUBuffer");
+    }
+    const d = ibuf.data;
+    // reinterpret the u32 payload as f32 bits for the arena write
+    dst.set(new Float32Array(d.buffer, d.byteOffset, d.byteLength >>> 2), off);
+};
+const packHostF32 = (val, dst, off) => {
+    const ibuf = val;
+    if (ibuf.kind !== "host") {
+        throw new Error("heapScene: BufferView aval flipped to native GPUBuffer; not supported in heap path");
+    }
+    dst.set(asFloat32(ibuf.data), off);
+};
+/** Broadcast prefix copy — the only variant that genuinely captures. */
+function packHostPrefix(limitFloats) {
+    return (val, dst, off) => {
+        const ibuf = val;
+        if (ibuf.kind !== "host") {
+            throw new Error("heapScene: BufferView aval flipped to native GPUBuffer; not supported in heap path");
+        }
+        const src = asFloat32(ibuf.data);
+        dst.set(src.subarray(0, limitFloats), off);
+    };
+}
 // GrowBuffer + ALIGN16 + MIN_BUFFER_BYTES + POW2 live in ./heapScene/growBuffer.
 // Packers (WGSL-type → JS-value → arena bytes) live in ./heapScene/packers.
 // ---------------------------------------------------------------------------
@@ -93,6 +128,57 @@ import { analyseOutputSet, evaluateStructural, evaluateStructuralSet, stableStri
  *  prelude then uses the local vertex index directly (no indexStorage lookup).
  *  Must match the literal in heapEffect.ts's `megacallSearchPrelude`. */
 export const HEAP_NONINDEXED = 0xffffffff;
+export function oct32(data) {
+    const u = data instanceof Uint32Array ? data : new Uint32Array(data.buffer, data.byteOffset, data.length);
+    return { kind: "heap-packed", enc: "oct32", data: u };
+}
+export function c4b(data) {
+    if (data instanceof Uint8Array) {
+        if (data.byteLength % 4 !== 0 || data.byteOffset % 4 !== 0) {
+            throw new Error("heapScene.c4b: RGBA8 data must be 4-byte sized and aligned");
+        }
+        return { kind: "heap-packed", enc: "c4b", data: new Uint32Array(data.buffer, data.byteOffset, data.byteLength / 4) };
+    }
+    return { kind: "heap-packed", enc: "c4b", data };
+}
+export function isHeapPackedAttribute(v) {
+    return typeof v === "object" && v !== null
+        && v.kind === "heap-packed"
+        && v.data instanceof Uint32Array;
+}
+/** Create a standalone `HeapStorage`. Pass it to `buildHeapScene` via
+ *  `opts.storage` to share one arena across multiple heaps. */
+export function createHeapStorage(device, opts = {}) {
+    void device;
+    // Initial capacities are hints; the buffers pow2-grow on demand.
+    const arena = buildArenaState(device, Math.max(64 * 1024, opts.initialArenaBytes ?? 0), 16 * 1024, "heapStorage", GPUBufferUsage.STORAGE, opts.maxChunkBytes);
+    const pool = new UniformPool();
+    const indexPool = new IndexPool();
+    const consumers = new Set();
+    return {
+        arena, pool, indexPool,
+        register(c) {
+            consumers.add(c);
+            return { dispose: () => { consumers.delete(c); } };
+        },
+        compact(dev, floor, force) {
+            arena.attrs.flush(dev); // GPU buffer current for the copy
+            const remaps = arena.attrs.compact(dev, floor, force);
+            for (const { chunkIdx, remap } of remaps) {
+                // Storage-level dedup pools first (uniform refs); then each scene
+                // re-seats its drawHeaders / derive / partition / index `_indexStart`
+                // (the index re-seat reads `indexPool.baseFor` at the OLD ref, so the
+                // index pool is remapped LAST, after all consumers).
+                pool.remapRefs(chunkIdx, remap);
+                for (const c of consumers)
+                    c.applyRemap(chunkIdx, remap);
+                indexPool.remapRefs(chunkIdx, remap);
+            }
+            return remaps.length;
+        },
+        dispose() { arena.attrs.destroy(); },
+    };
+}
 export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     const atlasPool = opts.atlasPool;
     const colorAttachmentName = sig.colorNames[0];
@@ -114,12 +200,21 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         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
-    // demand. Skip per-draw enumeration since aval-keyed sharing makes
-    // the actual allocated size hard to predict (10K instanced draws
-    // sharing the same Positions array → 1 alloc, not 10K).
-    const arena = buildArenaState(device, 64 * 1024, 16 * 1024, "heapScene", GPUBufferUsage.STORAGE, opts.maxChunkBytes);
+    // ─── Storage (arena + dedup pools) — private or shared ───────────
+    // The chunked arena (uniform/attribute data + index buffer) and the
+    // aval-keyed dedup pools live in a `HeapStorage`. Default: a private
+    // store this scene owns. `opts.storage`: a shared store (the same
+    // geometry/uniforms rendered by multiple heaps — e.g. shadow + color
+    // pass — are deduped once). The local `arena`/`pool`/`indexPool`
+    // bindings below keep every downstream reference unchanged.
+    const ownsStorage = opts.storage === undefined;
+    const storage = opts.storage ?? createHeapStorage(device, {
+        ...(opts.maxChunkBytes !== undefined ? { maxChunkBytes: opts.maxChunkBytes } : {}),
+        ...(opts.initialArenaBytes !== undefined ? { initialArenaBytes: opts.initialArenaBytes } : {}),
+    });
+    const arena = storage.arena;
+    const pool = storage.pool;
+    const indexPool = storage.indexPool;
     // ─── Per-draw global bookkeeping (sparse, indexed by drawId) ──────
     const drawIdToBucket = [];
     const drawIdToLocalSlot = [];
@@ -291,6 +386,23 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             const p = packerForWgslType(f.uniformWgslType ?? "");
             return { dataBytes: p.dataBytes, typeId: p.typeId, length: 1, pack: p.pack };
         }
+        // Packed attribute encodings (oct32 unit vectors / C4b colors): one
+        // u32 per element, decoded by the VS's typeId-selected arm. 3× smaller
+        // in the arena AND host-side (the caller keeps the packed source).
+        if (isHeapPackedAttribute(value)) {
+            const pa = value;
+            const wantType = pa.enc === "oct32" ? "vec3<f32>" : "vec4<f32>";
+            if (f.attributeWgslType !== wantType) {
+                throw new Error(`heapScene: ${pa.enc} attribute supplied for '${f.attributeWgslType}' field — ` +
+                    `oct32 requires vec3<f32>, c4b requires vec4<f32>`);
+            }
+            return {
+                dataBytes: pa.data.byteLength,
+                typeId: pa.enc === "oct32" ? ENC_OCT32 : ENC_C4B,
+                length: pa.data.length,
+                pack: packPackedAttr,
+            };
+        }
         // attribute-ref: variable-size array; we copy verbatim into the
         // arena. The current encoding is V3F_TIGHT (3 f32s per element).
         const arr = value;
@@ -303,7 +415,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             dataBytes: arr.byteLength,
             typeId: ENC_V3F_TIGHT,
             length,
-            pack: (val, dst, off) => { dst.set(val, off); },
+            pack: packF32Verbatim,
         };
     }
     /**
@@ -323,6 +435,36 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         if (offset !== 0) {
             throw new Error(`heapScene: BufferView offset ${offset} > 0 not yet supported`);
         }
+        // Packed encodings by ELEMENT TYPE (the BufferView analogue of the
+        // oct32()/c4b() HeapDrawSpec markers): one u32 per element in the
+        // arena, decoded by the VS typeId arm. Dedup stays aval-keyed like
+        // any other BufferView attribute.
+        const etName = bv.elementType.name;
+        if (etName === "oct32" || etName === "c4b") {
+            const want = etName === "oct32" ? "vec3<f32>" : "vec4<f32>";
+            if (f.attributeWgslType !== want) {
+                throw new Error(`heapScene: ${etName} BufferView requires a ${want} schema attribute (got ${f.attributeWgslType ?? "?"})`);
+            }
+            const strideP = bv.stride ?? 4;
+            const isBroadcastP = bv.singleValue !== undefined || strideP === 0;
+            if (!isBroadcastP && strideP !== 4) {
+                throw new Error(`heapScene: ${etName} BufferView stride ${strideP} not tight (4) and not a broadcast`);
+            }
+            const ibP = bv.buffer.force( /* allow-force */);
+            if (ibP.kind !== "host") {
+                throw new Error(`heapScene: ${etName} BufferView wraps a native GPUBuffer; not supported in heap path`);
+            }
+            const lengthP = isBroadcastP ? 1 : ibP.sizeBytes / 4;
+            const dataBytesP = 4 * lengthP;
+            return {
+                dataBytes: dataBytesP,
+                typeId: etName === "oct32" ? ENC_OCT32 : ENC_C4B,
+                length: lengthP,
+                // Tight case: the copy limit equals the source payload, so the
+                // static packer (which derives it from the buffer) is exact.
+                pack: isBroadcastP ? packHostPrefix(dataBytesP / 4) : packHostU32Bits,
+            };
+        }
         // In-arena element bytes: the storage layout the shader will read
         // from. vec4 is always 16 (read via `heapV4f[idx]`), vec3 is 12
         // (read as 3 f32s), vec2 is 8, scalar is 4. V3f source for a vec4
@@ -366,15 +508,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             dataBytes,
             typeId: ENC_V3F_TIGHT,
             length,
-            pack: (val, dst, off) => {
-                const ibuf = val;
-                if (ibuf.kind !== "host") {
-                    throw new Error("heapScene: BufferView aval flipped to native GPUBuffer; not supported in heap path");
-                }
-                const src = asFloat32(ibuf.data);
-                const limitFloats = dataBytes / 4;
-                dst.set(src.subarray(0, limitFloats), off);
-            },
+            pack: isBroadcast ? packHostPrefix(dataBytes / 4) : packHostF32,
         };
     }
     /**
@@ -400,9 +534,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             },
         };
     }
-    // ─── Pools — aval-keyed refcounted allocations ────────────────────
-    const pool = new UniformPool();
-    const indexPool = new IndexPool();
+    // (`pool` / `indexPool` are owned by `storage`, bound above.)
     // ─── Adaptive routing: aval marks → repack the pool entry ─────────
     // With pool-managed per-draw uniforms, value changes don't touch
     // any DrawHeader (refs stay constant) — only the arena allocation's
@@ -456,6 +588,9 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     // both. `derivedScene` is undefined when the option is off; nothing
     // else in this file should run when it is. On by default — pass
     // `enableDerivedUniforms: false` to opt out.
+    const enableCompaction = opts.enableCompaction !== false;
+    const releaseConstantAttributes = opts.releaseConstantAttributes === true;
+    const compactionWasteFloor = opts.compactionWasteFloorBytes ?? COMPACTION_WASTE_FLOOR_BYTES;
     const enableDerivedUniforms = opts.enableDerivedUniforms !== false;
     const derivedScene = enableDerivedUniforms
         ? new DerivedUniformsScene(device, {
@@ -544,6 +679,18 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     // that don't yet point at an allocated AtlasPage. WebGPU rejects
     // bind-group entries with `undefined` resources, so every slot in
     // the N-wide ladder must hold a valid view at all times.
+    // 4-byte placeholder storage buffer — binds user-storage slots on the
+    // seed bind group built before the first addDraw delivers the real
+    // buffers (rebuilt immediately after).
+    let storagePlaceholder;
+    function getStoragePlaceholder() {
+        if (storagePlaceholder === undefined) {
+            storagePlaceholder = device.createBuffer({
+                label: "heapScene/storagePlaceholder", size: 4, usage: GPUBufferUsage.STORAGE,
+            });
+        }
+        return storagePlaceholder;
+    }
     let atlasPlaceholders;
     function getAtlasPlaceholder(format) {
         if (atlasPlaceholders === undefined) {
@@ -566,6 +713,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     function getBgl(layout, withAtlasArrays) {
         const key = `t${layout.textureBindings.map(t => t.wgslType).join(",")}` +
             `|s${layout.samplerBindings.map(s => s.wgslType).join(",")}` +
+            `|sb${layout.storageBindings.map(b => `${b.binding}${b.access === "read_write" ? "w" : "r"}`).join(",")}` +
             `|a${withAtlasArrays ? 1 : 0}`;
         let e = bglCache.get(key);
         if (e !== undefined)
@@ -593,6 +741,14 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 sampler: { type: s.wgslType === "sampler_comparison" ? "comparison" : "filtering" },
             });
         }
+        for (const sb of layout.storageBindings) {
+            // FRAGMENT only: WebGPU forbids writable storage in vertex stages,
+            // and the OIT writers are fragment-side anyway.
+            entries.push({
+                binding: sb.binding, visibility: GPUShaderStage.FRAGMENT,
+                buffer: { type: sb.access === "read_write" ? "storage" : "read-only-storage" },
+            });
+        }
         if (withAtlasArrays) {
             // 2N + 1 entries: N linear textures, N srgb textures, 1 sampler.
             for (let i = 0; i < ATLAS_ARRAY_SIZE; i++) {
@@ -697,11 +853,32 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         if (cached !== undefined)
             return cached;
         const { pipelineLayout } = getBgl(layout, isAtlasBucket);
+        // Per-descriptor color targets: blend + write mask come from the RO's
+        // PipelineState (`desc.attachments`, ordered by signature colorNames —
+        // the same values the modeKey encodes). Using the bare scene-level
+        // `colorTargets` here silently dropped blends/write-masks from every
+        // heap pipeline: transparent heap leaves painted opaque, and the OIT
+        // pick passes' write-mask-0 "Colors" leaked color onto the composite.
+        const targets = colorTargets.map((t, i) => {
+            const a = desc.attachments[i];
+            if (a === undefined)
+                return { format: t.format };
+            return {
+                format: t.format,
+                writeMask: a.writeMask,
+                ...(a.enabled
+                    ? { blend: {
+                            color: { operation: a.color.operation, srcFactor: a.color.srcFactor, dstFactor: a.color.dstFactor },
+                            alpha: { operation: a.alpha.operation, srcFactor: a.alpha.srcFactor, dstFactor: a.alpha.dstFactor },
+                        } }
+                    : {}),
+            };
+        });
         const pipeline = device.createRenderPipeline({
             label: `heapScene/cached/${cacheKey}`,
             layout: pipelineLayout,
             vertex: { module: fam.vsModule, entryPoint: fam.vsEntryName, buffers: [] },
-            fragment: { module: fam.fsModule, entryPoint: fam.fsEntryName, targets: colorTargets },
+            fragment: { module: fam.fsModule, entryPoint: fam.fsEntryName, targets },
             primitive: { topology: desc.topology, cullMode: desc.cullMode, frontFace: desc.frontFace },
             ...(depthFormat !== undefined && desc.depth !== undefined
                 ? { depthStencil: { format: depthFormat, depthWriteEnabled: desc.depth.write, depthCompare: desc.depth.compare } }
@@ -826,6 +1003,29 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         }
         familyFor(effect); // throws if unknown
     }
+    /**
+     * Reactive family rebuild: register a new effect's family when it first
+     * appears after the initial freeze. Family-merge is disabled, so every
+     * Effect already gets its OWN independent single-member family (its own
+     * shader modules + buckets); a late effect just needs its family compiled
+     * and added — no rebuild of existing families. Idempotent.
+     */
+    function ensureFamilyForSpec(spec) {
+        if (!familyBuilt) {
+            buildFamilyFromSpecs([spec]);
+            return;
+        }
+        if (familyByEffectId.has(spec.effect.id))
+            return;
+        const entry = { attributes: new Set(), uniforms: new Set() };
+        if (spec.instanceAttributes !== undefined) {
+            for (const name of Object.keys(spec.instanceAttributes))
+                entry.attributes.add(name);
+        }
+        const singleMap = new Map();
+        singleMap.set(spec.effect, entry);
+        familyByEffectId.set(spec.effect.id, compileFamilyFor([spec.effect], singleMap));
+    }
     // ─── id-of helpers ────────────────────────────────────────────────
     const idOf = (s) => `effect#${s.id}`;
     const textureIds = new WeakMap();
@@ -961,7 +1161,10 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             // binary search. Minimum one zero-record to satisfy WebGPU non-
             // zero size constraint when the bucket is empty.
             const dtBytes = Math.max(RECORD_BYTES, s.recordCount * RECORD_BYTES);
-            entries.push({ binding: 4, resource: { buffer: s.drawTableBuf.buffer, offset: 0, size: dtBytes } }, { binding: 5, resource: { buffer: arena.indices.chunk(bucket.chunkIdx).buffer } }, { binding: 6, resource: { buffer: s.firstDrawInTileBuf.buffer } });
+            entries.push({ binding: 4, resource: { buffer: s.drawTableBuf.buffer, offset: 0, size: dtBytes } }, 
+            // Index data lives in the attr arena now (the VS storage-decodes it);
+            // bind the same buffer as the gather views.
+            { binding: 5, resource: { buffer: attrsBuf } }, { binding: 6, resource: { buffer: s.firstDrawInTileBuf.buffer } });
             s.renderBoundRecordCount = s.recordCount;
         }
         // Schema-driven texture + sampler entries. v1 user surface still
@@ -1009,6 +1212,21 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             // here — the atlas slots come from the per-format page tracking
             // below.
         }
+        for (const sb of bucket.layout.storageBindings) {
+            const av = bucket.storageBuffers?.get(sb.name);
+            if (av === undefined) {
+                // Buffers arrive with the first addDraw; the seed slot built at
+                // bucket creation is rebuilt right after they land. Bind a
+                // 4-byte placeholder so the seed bind group validates.
+                entries.push({ binding: sb.binding, resource: { buffer: getStoragePlaceholder() } });
+                continue;
+            }
+            const ib = av.force( /* allow-force */);
+            if (ib.kind !== "gpu") {
+                throw new Error(`heapScene: user storage buffer '${sb.name}' must be a GPU-backed IBuffer`);
+            }
+            entries.push({ binding: sb.binding, resource: { buffer: ib.buffer } });
+        }
         if (bucket.isAtlasBucket) {
             if (atlasPool === undefined) {
                 throw new Error("heapScene: atlas-variant bucket needs `atlasPool` in BuildHeapSceneOptions");
@@ -1081,15 +1299,6 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             atlasPool.onPageAdded(f, () => rebuildAllBindGroups(true));
         }
     }
-    arena.indices.onAnyResize((resizedChunkIdx) => {
-        for (const b of buckets) {
-            if (b.chunkIdx !== resizedChunkIdx)
-                continue;
-            for (let i = 0; i < b.slots.length; i++) {
-                b.slots[i].bindGroup = buildBucketBindGroup(b, i);
-            }
-        }
-    });
     // ─── findOrCreateBucket ───────────────────────────────────────────
     // Slice 3c: the bucket key collapses to (familyId, pipelineState).
     // Every member effect in the family shares one bucket per
@@ -1746,7 +1955,11 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             if (cpuMigration !== undefined) {
                 let totalEmit = 0;
                 for (const m of cpuMigration) {
-                    const uRefs = bucket.uniformOrder.map(n => m.perDrawRefs.get(n) ?? 0);
+                    const uRefs = bucket.uniformOrder.map(n => {
+                        const i = bucket.fieldIdx.get(n);
+                        const r = i === undefined ? -1 : m.perDrawRefs[i];
+                        return r < 0 ? 0 : r;
+                    });
                     const recIdx = partition.appendRecord(m.localSlot, m.firstIndex, m.indexCount, m.instanceCount, m.targetComboId, uRefs);
                     bucket.drawIdToRecord.set(m.drawId, recIdx);
                     bucket.recordToDrawId[recIdx] = m.drawId;
@@ -1857,8 +2070,11 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         const isAtlasBucket = layout.atlasTextureBindings.size > 0;
         const drawHeapBuf = new GrowBuffer(device, `heapScene/${bk}/drawHeap`, GPUBufferUsage.STORAGE, Math.max(layout.drawHeaderBytes, 64));
         const drawHeap = new DrawHeap(drawHeapBuf, layout.drawHeaderBytes);
+        const fieldIdx = new Map();
+        layout.drawHeaderFields.forEach((f, i) => fieldIdx.set(f.name, i));
         const bucket = {
             label: bk, textures: undefined, layout, chunkIdx,
+            storageBuffers: undefined, storageDirty: false, storageSubs: [],
             slots: [], // populated lazily by ensureSlot per modeKey
             bindGroup: null, // legacy field; slot.bindGroup is the real one
             drawHeap,
@@ -1866,7 +2082,10 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             headerDirtyMin: Infinity, headerDirtyMax: 0,
             localPosRefs: [], localNorRefs: [],
             localEntries: [], localToDrawId: [],
-            localPerDrawAvals: [], localPerDrawRefs: [], localLayoutIds: [],
+            localPerDrawAvals: [], localPerDrawRawFieldIdx: [], localPerDrawRefs: [], localLayoutIds: [],
+            fieldIdx,
+            posFieldIdx: fieldIdx.get("Positions") ?? -1,
+            norFieldIdx: fieldIdx.get("Normals") ?? -1,
             drawSlots: new Set(), dirty: new Set(),
             isAtlasBucket,
             localAtlasReleases: [],
@@ -1936,7 +2155,9 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         const dst = bucket.drawHeaderStaging;
         const u32 = new Uint32Array(dst.buffer, dst.byteOffset, dst.length);
         const baseFloat = (localSlot * bucket.layout.drawHeaderBytes) / 4;
-        for (const f of bucket.layout.drawHeaderFields) {
+        const fields = bucket.layout.drawHeaderFields;
+        for (let i = 0; i < fields.length; i++) {
+            const f = fields[i];
             // texture-ref fields carry inline values (pageRef/formatBits as u32,
             // origin/size as vec2<f32>) and are filled by packAtlasTextureFields.
             if (f.kind === "texture-ref")
@@ -1950,15 +2171,11 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 u32[fOff] = layoutId >>> 0;
                 continue;
             }
-            const ref = perDrawRefs.get(f.name);
-            if (ref === undefined) {
-                // Family-merge: a slot's effect doesn't populate every field of
-                // the union; leave the unused slots zero — the layoutId switch
-                // ensures they're never read by the wrong effect's helper.
-                u32[fOff] = 0;
-                continue;
-            }
-            u32[fOff] = ref;
+            const ref = perDrawRefs[i];
+            // Family-merge: a slot's effect doesn't populate every field of
+            // the union (−1); leave the unused slots zero — the layoutId
+            // switch ensures they're never read by the wrong effect's helper.
+            u32[fOff] = ref < 0 ? 0 : ref;
         }
     }
     // ─── Atlas drawHeader packing + page-set tracking ─────────────────
@@ -2043,6 +2260,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         totalDraws: 0,
         drawBytes: 0,
         geometryBytes: 0,
+        compactions: 0,
         derivedPullMs: 0,
         derivedUploadMs: 0,
         derivedEncodeMs: 0,
@@ -2085,12 +2303,10 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         // single spec when no batched lazy-build occurred earlier (e.g.
         // direct addDraw at runtime). The aset / array initial-population
         // paths build from the full effect set up front.
-        if (!familyBuilt) {
-            buildFamilyFromSpecs([spec]);
-        }
-        else {
-            ensureFamilyKnowsEffect(spec.effect);
-        }
+        // Build the family lazily from this spec (first addDraw), or register a
+        // newly-seen effect's family on the fly (reactive rebuild) — supports a
+        // scene mixing multiple effects added over time (tiles + markers + …).
+        ensureFamilyForSpec(spec);
         const perInstanceUniforms = new Set();
         const perInstanceAttributes = spec.instanceAttributes !== undefined
             ? new Set(Object.keys(spec.instanceAttributes))
@@ -2111,16 +2327,48 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 token: outerTok,
             });
         }
-        // §3 chunk routing — pick which arena chunk this RO's allocations
-        // land in. Preference order:
-        //   1. If any of the RO's bindings is an aval that's already
-        //      allocated in some chunk via the uniform pool, prefer that
-        //      chunk to avoid duplication.
-        //   2. Otherwise, use the newest open chunk (highest chunkIdx).
-        //      ChunkedArena.alloc spills to the next chunk automatically
-        //      when this one is full; the spill ends up driving the
-        //      pool's `finalChunk` selection so all of the RO's
-        //      allocations land in one chunk consistently.
+        // ─── Group-fit page placement (§3) ───────────────────────────────
+        // A draw's whole group — uniforms + attributes + INDEX data (all one
+        // arena now) — must land on ONE chunk/page (the draw binds one buffer).
+        // Estimate the group's arena bytes (exact per-field via the same
+        // placement helpers, ignoring dedup ⇒ an upper bound on the NEW bytes a
+        // chunk must absorb), then place the group on a chunk with room — prefer
+        // one already holding a shared input, else the newest, else open a fresh
+        // page. This replaces the old cross-chunk spill → throw, so a scene can
+        // grow past one buffer's cap (WebGPU's storage-buffer binding limit).
+        const fam = familyFor(spec.effect);
+        const effectFields = fam.fieldsForEffect.get(spec.effect.id);
+        const layout = fam.schema.drawHeaderUnion;
+        const hasIndices = spec.indices !== undefined;
+        const indicesAval = hasIndices ? asAval(spec.indices) : undefined;
+        const indexArr = hasIndices ? readPlain(spec.indices) : undefined;
+        const instanceCount = spec.instanceCount !== undefined
+            ? readPlain(spec.instanceCount) : 1;
+        let estBytes = indexArr !== undefined ? ALIGN16(ALLOC_HEADER_PAD_TO + indexArr.byteLength) : 0;
+        for (const f of layout.drawHeaderFields) {
+            if (f.kind === "texture-ref" || f.name === "__layoutId" || INLINE_HEADER_UNIFORMS.has(f.name) || !effectFields.has(f.name))
+                continue;
+            if (ruleForUniform(spec, f.name) !== undefined) {
+                estBytes += ALIGN16(ALLOC_HEADER_PAD_TO + PACKER_MAT4.dataBytes); // §7 derived dummy mat4
+                continue;
+            }
+            const perInstUniform = f.kind === "uniform-ref" && perInstanceUniforms.has(f.name);
+            const perInstAttr = f.kind === "attribute-ref" && perInstanceAttributes.has(f.name);
+            const provided = perInstAttr ? spec.instanceAttributes[f.name] : spec.inputs[f.name];
+            if (provided === undefined)
+                continue; // the acquire loop throws with a precise message
+            let dataBytes;
+            if (f.kind === "attribute-ref" && !perInstUniform && isBufferView(provided)) {
+                dataBytes = bufferViewPlacement(f, provided).dataBytes;
+            }
+            else {
+                const value = asAval(provided).getValue(outerTok);
+                dataBytes = (perInstUniform
+                    ? perInstancePlacementFor(f, value, instanceCount)
+                    : poolPlacementFor(f, value)).dataBytes;
+            }
+            estBytes += ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes);
+        }
         let chunkIdx;
         {
             let preferred;
@@ -2135,9 +2383,35 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                     }
                 }
             }
-            chunkIdx = preferred ?? Math.max(0, arena.attrs.chunkCount - 1);
+            const fits = (c) => arena.attrs.bumpHeadroom(c) >= estBytes;
+            const newest = arena.attrs.chunkCount - 1;
+            chunkIdx =
+                preferred !== undefined && fits(preferred) ? preferred
+                    : fits(newest) ? newest
+                        : arena.attrs.openPage();
         }
         const bucket = findOrCreateBucket(spec.effect, spec.textures, spec.pipelineState, chunkIdx, precomputedDescriptor);
+        // User storage buffers (layout.storageBindings): bucket-level, set once.
+        if (bucket.layout.storageBindings.length > 0 && bucket.storageBuffers === undefined) {
+            if (spec.storageBuffers === undefined) {
+                throw new Error(`heapScene: bucket '${bucket.label}' needs storage buffers ` +
+                    `(${bucket.layout.storageBindings.map(b => b.name).join(", ")}) but spec.storageBuffers is undefined`);
+            }
+            bucket.storageBuffers = spec.storageBuffers;
+            // A storage aval marking (e.g. the OIT head buffer reallocating on a
+            // canvas resize) invalidates every slot bind group of this bucket.
+            for (const av of spec.storageBuffers.values()) {
+                const disposer = av
+                    .addMarkingCallback?.(() => { bucket.storageDirty = true; });
+                if (disposer !== undefined)
+                    bucket.storageSubs.push(disposer);
+            }
+            // Slots seeded before the buffers were known carry incomplete bind
+            // groups — rebuild them now.
+            for (let i = 0; i < bucket.slots.length; i++) {
+                bucket.slots[i].bindGroup = buildBucketBindGroup(bucket, i);
+            }
+        }
         // Phase 5c.3 — every RO carrying a derived-mode rule is registered
         // on the bucket (lazy-promoting it to GPU-routed on the first
         // call). ROs may carry DIFFERENT rules even when they share the
@@ -2169,18 +2443,16 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         // tables every frame from the master.
         const roSlot = bucket.gpuRouted ? bucket.slots[0] : ensureSlot(bucket, roDescriptor);
         const roSlotIdx = bucket.slots.indexOf(roSlot);
-        const fam = familyFor(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. NON-INDEXED draws (spec.indices
-        // omitted) skip the index pool entirely: the drawTable record stores
-        // firstIndex = HEAP_NONINDEXED (sentinel) and indexCount = vertexCount,
-        // and the megacall prelude uses the local vertex index directly.
-        const hasIndices = spec.indices !== undefined;
-        const indicesAval = hasIndices ? asAval(spec.indices) : undefined;
+        // Indices ride the same arena as attributes/uniforms (the VS storage-
+        // decodes them). Aval-keyed: 19K instanced clones of the same mesh share
+        // one index allocation + one upload. NON-INDEXED draws (spec.indices
+        // omitted) skip the pool: the drawTable record stores firstIndex =
+        // HEAP_NONINDEXED (sentinel) and indexCount = vertexCount, and the
+        // megacall prelude uses the local vertex index directly. `indicesAval` /
+        // `indexArr` were read above for the group estimate; the group landed
+        // wholly on `bucket.chunkIdx`, so this allocation can't spill.
         const idxAlloc = hasIndices
-            ? indexPool.acquire(device, arena.indices, indicesAval, bucket.chunkIdx, readPlain(spec.indices))
+            ? indexPool.acquire(device, arena.attrs, indicesAval, bucket.chunkIdx, indexArr)
             : undefined;
         // Emit count per instance + the firstIndex field written to the record.
         // Slice: emit only [firstIndex, firstIndex+indexCount) of the (shared,
@@ -2189,17 +2461,26 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         const emitCount = hasIndices ? (spec.indexCount ?? idxAlloc.count) : (spec.vertexCount ?? 0);
         const firstIndexField = hasIndices ? (idxAlloc.firstIndex + (spec.firstIndex ?? 0)) : HEAP_NONINDEXED;
         const localSlot = bucket.drawHeap.alloc();
-        // Per-RO instancing: read `spec.instanceCount` (defaults to 1).
-        const instanceCount = spec.instanceCount !== undefined
-            ? readPlain(spec.instanceCount)
-            : 1;
         // Walk the bucket's schema-driven DrawHeader fields. Per-instance
         // attributes pull from `spec.instanceAttributes` and pack into an
         // array allocation; everything else pulls from `spec.inputs` and
         // packs as a single value. Both go through the same pool — sharing
         // emerges from aval identity either way.
         const perDrawAvals = [];
-        const perDrawRefs = new Map();
+        let perDrawRawFieldIdx;
+        const perDrawRefs = new Int32Array(bucket.layout.drawHeaderFields.length).fill(-1);
+        const setRef = (name, ref) => {
+            const i = bucket.fieldIdx.get(name);
+            if (i !== undefined)
+                perDrawRefs[i] = ref;
+        };
+        const getRef = (name) => {
+            const i = bucket.fieldIdx.get(name);
+            if (i === undefined)
+                return undefined;
+            const r = perDrawRefs[i];
+            return r < 0 ? undefined : r;
+        };
         {
             const tok = outerTok;
             for (const f of bucket.layout.drawHeaderFields) {
@@ -2214,15 +2495,42 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                     continue;
                 if (!effectFields.has(f.name))
                     continue;
+                // Inline header uniforms (PickId): the header word IS the u32
+                // value — write it via perDrawRefs (packBucketHeader copies
+                // refs verbatim), skip the pool entirely. A provider-supplied
+                // PickId aval still works below as the (slow) fallback.
+                if (INLINE_HEADER_UNIFORMS.has(f.name)) {
+                    const iv = f.name === "PickId" ? spec.pickId : undefined;
+                    if (iv !== undefined) {
+                        setRef(f.name, iv >>> 0);
+                        continue;
+                    }
+                    const provInline = spec.inputs[f.name];
+                    if (typeof provInline === "number") {
+                        setRef(f.name, provInline >>> 0);
+                        continue;
+                    }
+                    if (provInline === undefined) {
+                        // No id at all (picking disabled but the effect still
+                        // reads the uniform): 0 = "no pick", a reserved id.
+                        setRef(f.name, 0);
+                        continue;
+                    }
+                    // fall through: aval-provided → legacy pooled path
+                }
                 // §7: derived-uniform fields are produced by the compute
                 // 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 (ruleForUniform(spec, f.name) !== undefined) {
-                    const dummyAval = AVal.constant(M44d.zero);
-                    const ref = pool.acquire(device, arena.attrs, dummyAval, bucket.chunkIdx, M44d.zero, PACKER_MAT4.dataBytes, PACKER_MAT4.typeId, 1, PACKER_MAT4.pack);
-                    perDrawRefs.set(f.name, ref);
-                    perDrawAvals.push(dummyAval);
+                    // Raw (aval-less) slot: §7's compute pre-pass overwrites the
+                    // data every dirty frame, so a keyed pool entry (placeholder
+                    // ConstantVal + Map per draw) bought nothing. The ref lives
+                    // in the drawHeader cell (compaction re-seats it there);
+                    // removeDraw frees it via `perDrawRawFieldIdx`.
+                    const ref = pool.allocRaw(arena.attrs, bucket.chunkIdx, PACKER_MAT4.dataBytes, PACKER_MAT4.typeId, 1);
+                    setRef(f.name, ref);
+                    (perDrawRawFieldIdx ??= []).push(bucket.fieldIdx.get(f.name));
                     continue;
                 }
                 const isPerInstanceUniformField = f.kind === "uniform-ref" && perInstanceUniforms.has(f.name);
@@ -2249,12 +2557,37 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 let av;
                 let value;
                 let placement;
+                let releasable;
                 if (f.kind === "attribute-ref" && !isPerInstanceUniformField && isBufferView(provided)) {
                     const bv = provided;
                     placement = bufferViewPlacement(f, bv);
                     av = bv.buffer;
                     value = bv.buffer.getValue(tok);
                 }
+                else if (releaseConstantAttributes
+                    && f.kind === "attribute-ref"
+                    && !isPerInstanceUniformField
+                    && !(typeof provided === "object" && provided !== null
+                        && typeof provided.getValue === "function")) {
+                    // Plain value (raw array / packed marker) → CONSTANT by definition.
+                    // Wrap in a droppable holder: after this field's arena write the GPU
+                    // copy is the only copy the heap ever reads again, so the payload is
+                    // released (real avals never take this branch — changeable data
+                    // stays alive by contract).
+                    const holder = {
+                        _v: provided,
+                        getValue() {
+                            if (holder._v === null) {
+                                throw new Error("heapScene: constant attribute payload was released after staging (releaseConstantAttributes)");
+                            }
+                            return holder._v;
+                        },
+                    };
+                    releasable = holder;
+                    av = holder;
+                    value = provided;
+                    placement = poolPlacementFor(f, value);
+                }
                 else {
                     av = asAval(provided);
                     value = av.getValue(tok);
@@ -2263,18 +2596,21 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                         : poolPlacementFor(f, value);
                 }
                 const ref = pool.acquire(device, arena.attrs, av, bucket.chunkIdx, value, placement.dataBytes, placement.typeId, placement.length, placement.pack);
-                perDrawRefs.set(f.name, ref);
+                if (releasable !== undefined)
+                    releasable._v = null; // staged — drop the CPU copy
+                setRef(f.name, ref);
                 perDrawAvals.push(av);
             }
         }
-        bucket.localPosRefs[localSlot] = perDrawRefs.get("Positions");
-        bucket.localNorRefs[localSlot] = perDrawRefs.get("Normals");
+        bucket.localPosRefs[localSlot] = getRef("Positions");
+        bucket.localNorRefs[localSlot] = getRef("Normals");
         bucket.localEntries[localSlot] = {
             indexCount: emitCount, firstIndex: firstIndexField, instanceCount,
         };
         bucket.localToDrawId[localSlot] = drawId;
         bucket.drawSlots.add(localSlot);
         bucket.localPerDrawAvals[localSlot] = perDrawAvals;
+        bucket.localPerDrawRawFieldIdx[localSlot] = perDrawRawFieldIdx;
         bucket.localPerDrawRefs[localSlot] = perDrawRefs;
         const layoutId = fam.schema.layoutIdOf.get(spec.effect);
         bucket.localLayoutIds[localSlot] = layoutId;
@@ -2377,7 +2713,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             // don't carry a given name (e.g. their effect doesn't declare
             // it) get 0 — the kernel only reads refs through combo fns that
             // gate on `r.comboId`, so an unread 0 is harmless.
-            const uniformRefs = (bucket.uniformOrder ?? []).map(name => perDrawRefs.get(name) ?? 0);
+            const uniformRefs = (bucket.uniformOrder ?? []).map(name => getRef(name) ?? 0);
             partition.appendRecord(localSlot, firstIndexField, emitCount, instanceCount, roComboId, uniformRefs);
             bucket.drawIdToRecord.set(drawId, recIdx);
             bucket.recordToDrawId[recIdx] = drawId;
@@ -2477,7 +2813,11 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             }
             uniformAvals = m;
         }
-        const tracker = new ModeKeyTracker(spec.pipelineState, sig, () => { dirtyModeKeyDrawIds.add(drawId); }, {
+        const tracker = new ModeKeyTracker(spec.pipelineState, sig, 
+        // skipSubscribe means the tracker never invokes onDirty itself
+        // (scene-level modeAvalToDrawIds dispatches instead) — a shared
+        // noop avoids one closure per draw.
+        NOOP, {
             skipSubscribe: true,
             ...(spec.modeRules !== undefined ? { modeRules: spec.modeRules } : {}),
             ...(uniformAvals !== undefined ? { uniformAvals } : {}),
@@ -2509,14 +2849,14 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             const ruleSubset = new Map();
             const outOffsetByName = new Map();
             for (const f of bucket.layout.drawHeaderFields) {
-                if (f.name === "__layoutId")
+                if (f.name === "__layoutId" || INLINE_HEADER_UNIFORMS.has(f.name))
                     continue;
                 if (!effectFields.has(f.name))
                     continue;
                 const rule = ruleForUniform(spec, f.name);
                 if (rule === undefined)
                     continue;
-                const ref = perDrawRefs.get(f.name);
+                const ref = getRef(f.name);
                 if (ref === undefined)
                     continue;
                 ruleSubset.set(f.name, rule);
@@ -2545,7 +2885,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                     trafoAvals,
                     ...(spec.modelChain !== undefined ? { modelChain: spec.modelChain } : {}),
                     hostUniformOffset: (n) => {
-                        const r = perDrawRefs.get(n);
+                        const r = getRef(n);
                         return r === undefined ? undefined : r + ALLOC_HEADER_PAD_TO;
                     },
                     outputOffset: (n) => outOffsetByName.get(n),
@@ -2660,9 +3000,23 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         if (avals !== undefined)
             for (const av of avals)
                 pool.release(arena.attrs, av, bucket.chunkIdx);
+        // Raw §7 slots: the live ref is the drawHeader cell (compaction
+        // keeps it current); free it directly.
+        const rawIdxs = bucket.localPerDrawRawFieldIdx[localSlot];
+        if (rawIdxs !== undefined) {
+            const rawRefs = bucket.localPerDrawRefs[localSlot];
+            if (rawRefs !== undefined) {
+                for (const fi of rawIdxs) {
+                    const ref = rawRefs[fi];
+                    if (ref >= 0)
+                        pool.releaseRaw(arena.attrs, bucket.chunkIdx, ref, PACKER_MAT4.dataBytes);
+                }
+            }
+            bucket.localPerDrawRawFieldIdx[localSlot] = undefined;
+        }
         const idxAval = drawIdToIndexAval[drawId];
         if (idxAval !== undefined)
-            indexPool.release(arena.indices, idxAval, bucket.chunkIdx);
+            indexPool.release(arena.attrs, idxAval, bucket.chunkIdx);
         const atlasRel = bucket.localAtlasReleases[localSlot];
         if (atlasRel !== undefined)
             atlasRel();
@@ -2729,14 +3083,16 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         if (asetReader === undefined)
             return;
         const delta = asetReader.getChanges(tok);
+        // Process removals before adds. A remove+add in the same
+        // transaction must free its slot / arena region / atlas tile
+        // before the add allocates, so the freelist reuses the just-freed
+        // block instead of growing the high-water toward
+        // live + removed-this-tick. (Matches Aardvark's removals-first
+        // delta discipline.)
+        const adds = [];
         delta.iter((op) => {
             if (op.count > 0) {
-                // 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);
+                adds.push(op.value);
             }
             else {
                 const id = specToDrawId.get(op.value);
@@ -2746,6 +3102,13 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 }
             }
         });
+        // 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 round trip.
+        for (const value of adds) {
+            const id = addDrawImpl(value, tok);
+            specToDrawId.set(value, id);
+        }
     }
     // ─── Initial population ───────────────────────────────────────────
     if (Array.isArray(initialDraws)) {
@@ -2764,9 +3127,9 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         asetReader = initialDraws.getReader();
         sceneObj.evaluateAlways(AdaptiveToken.top, (tok) => {
             // First drain: snapshot all add-ops, build the family from their
-            // effects up front, then run addDraw. Subsequent drains either
-            // reuse the frozen family (matching effects) or throw on a new
-            // unseen effect (per the v1 frozen-family contract).
+            // effects up front, then run addDraw. Subsequent drains reuse the
+            // family, or register a newly-seen effect's family on the fly
+            // (ensureFamilyForSpec, via addDrawImpl).
             if (!familyBuilt) {
                 const reader = asetReader;
                 const delta = reader.getChanges(tok);
@@ -2798,6 +3161,148 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             }
         });
     }
+    // ─── Heap compaction (attribute arena + index buffer) ────────────
+    /**
+     * Compact every arena/index chunk whose fragmentation waste crosses the
+     * floor (or unconditionally when `force`), then re-seat EVERY cached ref so
+     * the relocated allocations stay addressable. Attribute arena:
+     *   • uniform-pool entries (`pool.remapRefs`)
+     *   • §7 derived-uniform record handles (`derivedScene.remapHostHeap`)
+     *   • modes partition master refs (`partitionScene.remapUniformRefs`)
+     *   • drawHeader cells + the Pos/Nor caches (re-`packBucketHeader`)
+     * Index buffer (ref = `allocBase + slice`, held in the drawTable / partition
+     * master + IndexPool entry):
+     *   • per-draw `indexStart` in the CPU drawTable or partition master
+     *   • `localEntries[slot].firstIndex` + IndexPool entry base
+     * Must run with the buffers current (we flush first) and before the
+     * per-bucket header / drawTable flush so the re-seated records upload.
+     */
+    // Per-scene ref re-seat after the shared store relocates regions. Registered
+    // with `storage`; the store calls it (for THIS scene + any others sharing the
+    // store) inside `storage.compact`. Re-seats derived records, partition master
+    // refs, drawHeader cells, and index `_indexStart` — everything this scene
+    // caches that points into the arena. (The storage-level uniform/index pools
+    // are re-seated by the store itself, around this call.)
+    function applyRemap(chunkIdx, remap) {
+        if (derivedScene !== undefined) {
+            // §7 handles store DATA offsets (ref + header pad), not header refs.
+            const dataRemap = new Map();
+            for (const [o, n] of remap) {
+                dataRemap.set(o + ALLOC_HEADER_PAD_TO, n + ALLOC_HEADER_PAD_TO);
+            }
+            derivedScene.remapHostHeap(chunkIdx, dataRemap);
+        }
+        {
+            for (const bucket of buckets) {
+                if (bucket.chunkIdx !== chunkIdx)
+                    continue;
+                if (bucket.gpuRouted && bucket.partitionScene !== undefined) {
+                    if (bucket.partitionScene.remapUniformRefs(remap) > 0) {
+                        bucket.partitionDirty = true;
+                    }
+                }
+                for (const localSlot of bucket.drawSlots) {
+                    // (a) Index region re-seat. Index data is an attr-arena region now,
+                    // so it relocates in THIS pass. Its draw stores `_indexStart` (an
+                    // element offset = allocBase + slice) in the drawTable / partition
+                    // master; shift it by the region's element delta. Independent of the
+                    // uniform re-seat below (a slot's indices may move while its uniforms
+                    // don't), so it runs before the `changed` gate.
+                    const drawId = bucket.localToDrawId[localSlot];
+                    if (drawId !== undefined) {
+                        const iav = drawIdToIndexAval[drawId];
+                        const oldRef = iav !== undefined ? indexPool.baseFor(iav, chunkIdx) : undefined;
+                        const newRef = oldRef !== undefined ? remap.get(oldRef) : undefined;
+                        const entry = bucket.localEntries[localSlot];
+                        if (oldRef !== undefined && newRef !== undefined && entry !== undefined) {
+                            const newStart = entry.firstIndex + ((newRef - oldRef) >> 2);
+                            entry.firstIndex = newStart;
+                            if (bucket.gpuRouted && bucket.partitionScene !== undefined) {
+                                const recIdx = bucket.drawIdToRecord?.get(drawId);
+                                if (recIdx !== undefined) {
+                                    bucket.partitionScene.setRecordIndexStart(recIdx, newStart);
+                                    bucket.partitionDirty = true;
+                                }
+                            }
+                            else {
+                                const slotIdx = drawIdToSlotIdx[drawId];
+                                const slot = slotIdx !== undefined ? bucket.slots[slotIdx] : bucket.slots[0];
+                                const recIdx = slot?.slotToRecord[localSlot];
+                                if (slot !== undefined && recIdx !== undefined && recIdx >= 0) {
+                                    slot.drawTableShadow[recIdx * RECORD_U32 + 2] = newStart >>> 0;
+                                    const off = recIdx * RECORD_BYTES;
+                                    if (off < slot.drawTableDirtyMin)
+                                        slot.drawTableDirtyMin = off;
+                                    if (off + RECORD_BYTES > slot.drawTableDirtyMax)
+                                        slot.drawTableDirtyMax = off + RECORD_BYTES;
+                                }
+                            }
+                        }
+                    }
+                    // (b) Uniform/attr drawHeader cells (+ Pos/Nor caches).
+                    const refs = bucket.localPerDrawRefs[localSlot];
+                    if (refs === undefined)
+                        continue;
+                    let changed = false;
+                    for (let i = 0; i < refs.length; i++) {
+                        const ref = refs[i];
+                        if (ref < 0)
+                            continue;
+                        const fld = bucket.layout.drawHeaderFields[i];
+                        // Inline header values (PickId/__layoutId) are NOT arena
+                        // refs — a numeric collision with an old offset must not
+                        // remap them.
+                        if (fld.name === "__layoutId" || INLINE_HEADER_UNIFORMS.has(fld.name))
+                            continue;
+                        const nn = remap.get(ref);
+                        if (nn !== undefined) {
+                            refs[i] = nn;
+                            changed = true;
+                        }
+                    }
+                    if (!changed)
+                        continue;
+                    const pr = bucket.posFieldIdx >= 0 ? refs[bucket.posFieldIdx] : -1;
+                    const nr = bucket.norFieldIdx >= 0 ? refs[bucket.norFieldIdx] : -1;
+                    bucket.localPosRefs[localSlot] = pr < 0 ? undefined : pr;
+                    bucket.localNorRefs[localSlot] = nr < 0 ? undefined : nr;
+                    packBucketHeader(bucket, localSlot, refs, bucket.localLayoutIds[localSlot] ?? 0);
+                    if (bucket.isAtlasBucket) {
+                        const ts = bucket.localAtlasTextures[localSlot];
+                        if (ts !== undefined)
+                            packAtlasTextureFields(bucket, localSlot, ts);
+                    }
+                    const byteOff = localSlot * bucket.layout.drawHeaderBytes;
+                    if (byteOff < bucket.headerDirtyMin)
+                        bucket.headerDirtyMin = byteOff;
+                    const end = byteOff + bucket.layout.drawHeaderBytes;
+                    if (end > bucket.headerDirtyMax)
+                        bucket.headerDirtyMax = end;
+                }
+            }
+        }
+    }
+    // Register this scene as a consumer of the (possibly shared) store, so a
+    // compaction — triggered by THIS scene or any other sharing the store —
+    // re-seats this scene's refs. Disposed in `dispose()`.
+    const storageReg = storage.register({ applyRemap });
+    // ─── Compaction (delegates to the shared store) ──────────────────
+    function runCompaction(force) {
+        const compacted = storage.compact(device, compactionWasteFloor, force);
+        stats.compactions += compacted;
+        // update() flushes the re-seated drawHeaders via its own per-bucket loop
+        // right after this returns; the forced (test) path runs outside update(),
+        // so it flushes this scene's dirtied headers itself.
+        if (force) {
+            for (const bucket of buckets) {
+                if (bucket.headerDirtyMax > bucket.headerDirtyMin) {
+                    device.queue.writeBuffer(bucket.drawHeap.buffer, bucket.headerDirtyMin, bucket.drawHeaderStaging.buffer, bucket.drawHeaderStaging.byteOffset + bucket.headerDirtyMin, bucket.headerDirtyMax - bucket.headerDirtyMin);
+                    bucket.headerDirtyMin = Infinity;
+                    bucket.headerDirtyMax = 0;
+                }
+            }
+        }
+    }
     // ─── update / encodeIntoPass / frame / dispose ───────────────────
     /**
      * CPU-side data refresh: drain pending aset deltas, repack any
@@ -2810,6 +3315,16 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         let totalDirtyBytes = 0;
         sceneObj.evaluateAlways(token, (tok) => {
             drainAsetWith(tok);
+            // User storage buffers that marked (e.g. the OIT head buffer
+            // reallocating on a resize) invalidate the bucket's bind groups.
+            for (const b of buckets) {
+                if (!b.storageDirty)
+                    continue;
+                b.storageDirty = false;
+                for (let i = 0; i < b.slots.length; i++) {
+                    b.slots[i].bindGroup = buildBucketBindGroup(b, i);
+                }
+            }
             // 0. Reactive rebucket: any RO whose PipelineState modeKey
             //    changed since last frame moves to its new bucket.
             //    `dirtyModeKeyDrawIds` was populated by ModeKeyTracker's
@@ -3032,7 +3547,16 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         // initial population for 10K ROs this collapses ~30K calls into
         // ~5 (arena, indices, plus one per bucket).
         arena.attrs.flush(device);
-        arena.indices.flush(device);
+        // ─── Waste-triggered attribute-arena compaction ─────────────────
+        // Relocate live allocations to the front of each chunk once
+        // fragmentation waste crosses the floor — exact-size freelist reuse
+        // can't reclaim a drifting size distribution, so the arena would
+        // otherwise ratchet to its high-water forever. Runs AFTER the arena
+        // flush (GPU buffer current) and BEFORE the header flush (so the
+        // re-seated drawHeaders upload below). Indices live in a separate
+        // buffer and are not compacted here.
+        if (enableCompaction)
+            runCompaction(false);
         for (const bucket of buckets) {
             if (bucket.headerDirtyMax > bucket.headerDirtyMin) {
                 device.queue.writeBuffer(bucket.drawHeap.buffer, bucket.headerDirtyMin, bucket.drawHeaderStaging.buffer, bucket.drawHeaderStaging.byteOffset + bucket.headerDirtyMin, bucket.headerDirtyMax - bucket.headerDirtyMin);
@@ -3232,14 +3756,44 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         destroyBucketResources(b);
     }
     function dispose() {
-        arena.attrs.destroy();
-        arena.indices.destroy();
+        // Stop receiving compaction remaps for the shared store.
+        storageReg.dispose();
+        // Shared storage: release this scene's allocations so the shared pool's
+        // refcounts stay correct (another scene may still hold the same regions),
+        // but don't destroy the buffers — the storage owner does that. Private
+        // storage: the whole arena is torn down wholesale, so per-draw release is
+        // unnecessary.
+        if (!ownsStorage) {
+            for (let drawId = 0; drawId < drawIdToBucket.length; drawId++) {
+                if (drawIdToBucket[drawId] !== undefined)
+                    removeDraw(drawId);
+            }
+        }
         for (const b of buckets)
             destroyBucketResources(b);
+        if (ownsStorage)
+            storage.dispose();
     }
     // Test-only escape hatch for inspecting megacall bucket state. Not
     // part of the public API surface — keep cast at use-site.
     const _debug = {
+        /** Force a full heap compaction pass (attribute arena + index buffer)
+         *  regardless of the waste heuristics (bypasses the floor + 50%-live
+         *  gate), re-seat all refs, flush. Returns residual waste afterwards in
+         *  bytes (attr bytes + index elements×4; 0 when fully packed). Test-only —
+         *  drives relocation deterministically without engineering megabytes of
+         *  fragmentation. Callers should `update()` afterward to flush drawTables /
+         *  re-dispatch the partition (the render path does this). */
+        forceCompact() {
+            runCompaction(true);
+            return arena.attrs.totalWasteBytes();
+        },
+        /** Current arena fragmentation waste (bytes) — covers uniforms,
+         *  attributes, and index regions (all one arena now). */
+        attrWasteBytes() { return arena.attrs.totalWasteBytes(); },
+        /** Number of arena chunks (pages) currently open. >1 means group
+         *  placement rolled past one buffer cap. */
+        pageCount() { return arena.attrs.chunkCount; },
         bucketsForTest() {
             return buckets.map(b => ({
                 indirectBuf: b.slots[0].indirectBuf,
@@ -3279,12 +3833,12 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             // multi-chunk-aware validator needs per-bucket-chunkIdx
             // staging which is a bigger refactor; assert for now so
             // multi-chunk callers don't get false-passes.
-            if (arena.attrs.chunkCount > 1 || arena.indices.chunkCount > 1) {
+            if (arena.attrs.chunkCount > 1) {
                 throw new Error("heapScene/validateHeap: multi-chunk arenas not yet supported by this validator (chunk-0-only). " +
                     "Run with the default chunk cap (no second chunk opened) for now.");
             }
             const arenaSize = arena.attrs.chunk(0).buffer.size;
-            const indicesSize = arena.indices.chunk(0).buffer.size;
+            const indicesSize = arenaSize; // indices live in the attr arena now
             const enc = device.createCommandEncoder({ label: "validateHeap" });
             const stage = (src, size) => {
                 const c = device.createBuffer({
@@ -3295,7 +3849,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 return c;
             };
             const arenaCopy = stage(arena.attrs.chunk(0).buffer, arenaSize);
-            const indicesCopy = indicesSize > 0 ? stage(arena.indices.chunk(0).buffer, indicesSize) : undefined;
+            const indicesCopy = arenaCopy; // same buffer; _indexStart is an element offset into it
             const TILE_K_LOCAL = 64;
             const dcs = [];
             for (const b of buckets) {
@@ -3348,7 +3902,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 for (let slot = 0; slot < recordCount; slot++) {
                     const slotOff = slot * stride;
                     for (const f of dc.bucket.layout.drawHeaderFields) {
-                        if (f.name === "__layoutId")
+                        if (f.name === "__layoutId" || INLINE_HEADER_UNIFORMS.has(f.name))
                             continue;
                         if (f.kind !== "uniform-ref" && f.kind !== "attribute-ref")
                             continue;
@@ -3384,18 +3938,9 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                                 ? `prev=[${arenaU32[refU32 - 4]},${arenaU32[refU32 - 3]},${arenaU32[refU32 - 2]},${arenaU32[refU32 - 1]}] `
                                 : "";
                             const here = `here=[${arenaU32[refU32]},${arenaU32[refU32 + 1]},${arenaU32[refU32 + 2]},${arenaU32[refU32 + 3]},${arenaU32[refU32 + 4]},${arenaU32[refU32 + 5]},${arenaU32[refU32 + 6]},${arenaU32[refU32 + 7]}]`;
-                            // Compare CPU shadow vs GPU read-back. Differ → GPU
-                            // write corrupted; match → bug is in CPU-side write path
-                            // OR the alloc never went through pool.acquire.
-                            const shadowChunk = arena.attrs.chunk(0);
-                            const shadowU32 = shadowChunk.peekShadowU32(ref, 8);
-                            const shadowStr = `shadow=[${shadowU32[0]},${shadowU32[1]},${shadowU32[2]},${shadowU32[3]},${shadowU32[4]},${shadowU32[5]},${shadowU32[6]},${shadowU32[7]}]`;
-                            const cpuMatches = shadowU32[0] === arenaU32[refU32]
-                                && shadowU32[1] === arenaU32[refU32 + 1]
-                                && shadowU32[2] === arenaU32[refU32 + 2]
-                                && shadowU32[3] === arenaU32[refU32 + 3];
-                            const verdict = cpuMatches ? "GPU=CPU (likely CPU-write bug)" : "GPU≠CPU (likely GPU-write corruption)";
-                            push(`bucket#${bucketIdx} slot=${slot} field='${f.name}' alloc@0x${ref.toString(16)} typeId=${typeId} unknown ${verdict} ${before}${here} ${shadowStr}`);
+                            // (Mirror-less arena: no CPU shadow to cross-check against —
+                            // the GPU read-back is the only copy.)
+                            push(`bucket#${bucketIdx} slot=${slot} field='${f.name}' alloc@0x${ref.toString(16)} typeId=${typeId} unknown ${before}${here}`);
                             attrAllocsBad++;
                             continue;
                         }
@@ -3598,11 +4143,11 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             const push = (s) => { if (issues.length < 30)
                 issues.push(s); };
             // §3 v1: chunk-0-only like validateHeap.
-            if (arena.attrs.chunkCount > 1 || arena.indices.chunkCount > 1) {
+            if (arena.attrs.chunkCount > 1) {
                 throw new Error("heapScene/simulateDraws: multi-chunk arenas not yet supported (chunk-0-only).");
             }
             const arenaSize = arena.attrs.chunk(0).buffer.size;
-            const indicesSize = arena.indices.chunk(0).buffer.size;
+            const indicesSize = arenaSize; // indices live in the attr arena now
             // Stage all buffers we'll need.
             const enc = device.createCommandEncoder({ label: "simulateDraws" });
             const stage = (src, size) => {
@@ -3613,7 +4158,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 return c;
             };
             const arenaCopy = stage(arena.attrs.chunk(0).buffer, arenaSize);
-            const indicesCopy = indicesSize > 0 ? stage(arena.indices.chunk(0).buffer, indicesSize) : undefined;
+            const indicesCopy = arenaCopy; // same buffer; _indexStart is an element offset into it
             const dcs = [];
             for (const b of buckets) {
                 if (b.slots[0].recordCount === 0 || b.slots[0].totalEmitEstimate === 0)
@@ -3654,7 +4199,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             for (const dc of dcs) {
                 const fs = [];
                 for (const f of dc.bucket.layout.drawHeaderFields) {
-                    if (f.name === "__layoutId")
+                    if (f.name === "__layoutId" || INLINE_HEADER_UNIFORMS.has(f.name))
                         continue;
                     if (f.kind !== "uniform-ref" && f.kind !== "attribute-ref")
                         continue;
@@ -3865,11 +4410,11 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             // cross-RO triangle symptom.
             const allocClaims = [];
             // §3 v1: chunk-0-only (see validateHeap).
-            if (arena.attrs.chunkCount > 1 || arena.indices.chunkCount > 1) {
+            if (arena.attrs.chunkCount > 1) {
                 throw new Error("heapScene/checkTriangleCoherence: multi-chunk arenas not yet supported (chunk-0-only).");
             }
             const arenaBuf0 = arena.attrs.chunk(0).buffer;
-            const indicesBuf0 = arena.indices.chunk(0).buffer;
+            const indicesBuf0 = arena.attrs.chunk(0).buffer;
             // Stage arena + arena.indices once (shared across buckets).
             const arenaCopy = device.createBuffer({
                 size: arenaBuf0.size,
@@ -4322,7 +4867,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                     { binding: 0, resource: { buffer: target.slots[0].drawTableBuf.buffer } },
                     { binding: 1, resource: { buffer: target.slots[0].firstDrawInTileBuf.buffer } },
                     { binding: 2, resource: { buffer: sampleBuf } },
-                    { binding: 3, resource: { buffer: arena.indices.chunk(target.chunkIdx).buffer } },
+                    { binding: 3, resource: { buffer: arena.attrs.chunk(target.chunkIdx).buffer } },
                     { binding: 4, resource: { buffer: outBuf } },
                     { binding: 5, resource: { buffer: paramBuf } },
                 ],
@@ -4346,7 +4891,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             outBuf.destroy();
             paramBuf.destroy();
             // Read drawTable + indices for CPU expectation.
-            const idxBuf = arena.indices.chunk(target.chunkIdx).buffer;
+            const idxBuf = arena.attrs.chunk(target.chunkIdx).buffer;
             const indicesCopy2 = device.createBuffer({
                 size: idxBuf.size,
                 usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,