@aardworx/wombat.rendering 0.19.24 → 0.20.0

package/dist/runtime/heapScene/pools.js

@@ -3,11 +3,11 @@
 // classes here are tightly interleaved:
 //
 //   AttributeArena    — byte-bump over a STORAGE GrowBuffer
-//   IndexAllocator    — element-bump over an INDEX GrowBuffer
+//   (index arrays are AttributeArena regions too — VS storage-decodes them)
 //   DrawHeap          — slot-indexed allocator over a STORAGE GrowBuffer
 //                       (one slot per RO drawHeader)
 //   UniformPool       — aval-keyed refcounted alloc on top of AttributeArena
-//   IndexPool         — aval-keyed refcounted alloc on top of IndexAllocator,
+//   IndexPool         — aval-keyed refcounted alloc on top of AttributeArena,
 //                       with value-tuple dedup for constant avals (§5b).
 //
 // Plus the per-allocation header constants used by all of them and
@@ -17,8 +17,7 @@
 import { AVal } from "@aardworx/wombat.adaptive";
 import { GrowBuffer, ALIGN16, DEFAULT_MAX_BUFFER_BYTES } from "./growBuffer.js";
 import { Freelist } from "./freelist.js";
-import { DirtyRanges } from "./dirtyRanges.js";
-import { ChunkedAttributeArena, ChunkedIndexAllocator } from "./chunkedArena.js";
+import { ChunkedAttributeArena } from "./chunkedArena.js";
 // ─── Debug toggles ─────────────────────────────────────────────────────
 /** Opt-in O(live-allocs) overlap validation on every alloc. Set
  *  `globalThis.__wombatDebugAllocOverlap = true` BEFORE scene creation
@@ -33,8 +32,16 @@ const DEBUG_ALLOC_OVERLAP = globalThis
  *  up for future vec4 reads). */
 export const ALLOC_HEADER_BYTES = 8;
 export const ALLOC_HEADER_PAD_TO = 16;
-/** Encoding-tag enum (low 16 bits of typeId). */
+/** Default fragmentation-waste floor (bytes) below which `AttributeArena`
+ *  declines to compact — relocating a few KB isn't worth a GPU copy +
+ *  ref re-seat. Matches Aardvark's 4 MiB compaction floor. */
+export const COMPACTION_WASTE_FLOOR_BYTES = 4 * 1024 * 1024;
+/** Encoding-tag enum (low 16 bits of typeId). The generated VS decode
+ *  branches on this per field (2-arm select; header word 0 shares the
+ *  cache line with the broadcast length in word 1). */
 export const ENC_V3F_TIGHT = 1; // tightly-packed array of vec3<f32> (12 B/elt)
+export const ENC_OCT32 = 2; // oct-packed unit vectors, 2×unorm16 in one u32 (4 B/elt)
+export const ENC_C4B = 3; // RGBA8-unorm colors, one u32/elt → unpack4x8unorm (4 B/elt)
 /** Semantic-tag enum (high 16 bits of typeId). Optional metadata —
  *  the shader doesn't branch on this. */
 export const SEM_POSITIONS = 1;
@@ -48,37 +55,114 @@ export const SEM_NORMALS = 2;
  * an aval still share the underlying allocation.
  */
 export class UniformPool {
+    /** Value is a single `PoolEntry` (the overwhelmingly common case —
+     *  one aval, one chunk) or a `Map<chunkIdx, PoolEntry>` once the
+     *  same aval is allocated in a second chunk. The flat form saves a
+     *  whole inner `Map` per aval, which at heap scale (several avals
+     *  per draw) is megabytes of JS heap. */
     byAval = new Map();
+    getEntry(av, chunkIdx) {
+        const v = this.byAval.get(av);
+        if (v === undefined)
+            return undefined;
+        if (v instanceof Map)
+            return v.get(chunkIdx);
+        return v.chunkIdx === chunkIdx ? v : undefined;
+    }
+    setEntry(av, e) {
+        const v = this.byAval.get(av);
+        if (v === undefined) {
+            this.byAval.set(av, e);
+            return;
+        }
+        if (v instanceof Map) {
+            v.set(e.chunkIdx, e);
+            return;
+        }
+        const m = new Map();
+        m.set(v.chunkIdx, v);
+        m.set(e.chunkIdx, e);
+        this.byAval.set(av, m);
+    }
+    deleteEntry(av, chunkIdx) {
+        const v = this.byAval.get(av);
+        if (v === undefined)
+            return;
+        if (v instanceof Map) {
+            v.delete(chunkIdx);
+            if (v.size === 1) {
+                this.byAval.set(av, v.values().next().value);
+            }
+            else if (v.size === 0)
+                this.byAval.delete(av);
+            return;
+        }
+        if (v.chunkIdx === chunkIdx)
+            this.byAval.delete(av);
+    }
+    *entriesOf(av) {
+        const v = this.byAval.get(av);
+        if (v === undefined)
+            return;
+        if (v instanceof Map)
+            yield* v.values();
+        else
+            yield v;
+    }
     has(av, chunkIdx) {
-        return this.byAval.get(av)?.has(chunkIdx) ?? false;
+        return this.getEntry(av, chunkIdx) !== undefined;
     }
     /** True when the pool holds at least one entry for `av` in any
      *  chunk. Used by the scene's `inputChanged` dispatch to decide
      *  whether a marking aval is one of our tracked allocations. */
     hasAny(av) {
-        return (this.byAval.get(av)?.size ?? 0) > 0;
+        const v = this.byAval.get(av);
+        return v !== undefined && (!(v instanceof Map) || v.size > 0);
     }
     entry(av, chunkIdx) {
-        return this.byAval.get(av)?.get(chunkIdx);
+        return this.getEntry(av, chunkIdx);
     }
     /** First chunk this aval is allocated in, if any. Used by `addRO`
      *  to prefer co-locating a new RO with its already-allocated
      *  shared inputs (avoids unnecessary duplication). */
     firstChunkContaining(av) {
-        const byChunk = this.byAval.get(av);
-        if (byChunk === undefined || byChunk.size === 0)
-            return undefined;
-        return byChunk.keys().next().value;
+        for (const e of this.entriesOf(av))
+            return e.chunkIdx;
+        return undefined;
+    }
+    /**
+     * Unkeyed allocation for slots the GPU overwrites every dirty frame
+     * (§7 derived-uniform outputs). No aval, no `byAval` entry, no
+     * sharing — the caller keeps the ref in its drawHeader cell (which
+     * the compaction remap re-seats) and frees it with `releaseRaw`.
+     * Avoids a placeholder `AVal.constant` + pool entry per draw.
+     */
+    allocRaw(arena, chunkIdx, dataBytes, typeId, length) {
+        const r = arena.alloc(dataBytes, chunkIdx);
+        if (r.chunkIdx !== chunkIdx) {
+            throw new Error(`UniformPool.allocRaw: allocator spilled from chunk ${chunkIdx} to chunk ${r.chunkIdx} ` +
+                `(${dataBytes} bytes). Caller's bucket is bound to chunk ${chunkIdx}.`);
+        }
+        const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + dataBytes);
+        const buf = new ArrayBuffer(allocBytes);
+        const u32 = new Uint32Array(buf);
+        u32[0] = typeId;
+        u32[1] = length;
+        u32[2] = length > 0 ? Math.floor(dataBytes / length) : 0;
+        arena.write(chunkIdx, r.off, new Uint8Array(buf));
+        return r.off;
+    }
+    releaseRaw(arena, chunkIdx, ref, dataBytes) {
+        arena.release(chunkIdx, ref, dataBytes);
     }
     /**
      * Acquire (or share) an allocation for `aval` in `chunkIdx`.
      * Returns the byte offset within that chunk's GPUBuffer. If a
      * fresh allocation is made, the value is packed + uploaded
-     * immediately into the chunk's CPU shadow.
+     * immediately to the chunk's GPU buffer (mirror-less).
      */
     acquire(device, arena, av, chunkIdx, value, dataBytes, typeId, length, pack) {
-        let byChunk = this.byAval.get(av);
-        const existing = byChunk?.get(chunkIdx);
+        const existing = this.getEntry(av, chunkIdx);
         if (existing !== undefined) {
             existing.refcount++;
             return existing.ref;
@@ -110,18 +194,13 @@ export class UniformPool {
         pack(value, f32, ALLOC_HEADER_PAD_TO / 4);
         arena.write(finalChunk, r.off, new Uint8Array(buf));
         void device;
-        if (byChunk === undefined) {
-            byChunk = new Map();
-            this.byAval.set(av, byChunk);
-        }
-        byChunk.set(finalChunk, {
+        this.setEntry(av, {
             chunkIdx: finalChunk, ref: r.off, dataBytes, typeId, pack, refcount: 1,
         });
         return r.off;
     }
     release(arena, av, chunkIdx) {
-        const byChunk = this.byAval.get(av);
-        const e = byChunk?.get(chunkIdx);
+        const e = this.getEntry(av, chunkIdx);
         if (e === undefined)
             return;
         e.refcount--;
@@ -138,20 +217,30 @@ export class UniformPool {
         // 16 B inside the previous alloc → overlapping allocations →
         // garbage `typeId`/`length` in the attribute header.
         arena.release(e.chunkIdx, e.ref, e.dataBytes);
-        byChunk.delete(chunkIdx);
-        if (byChunk.size === 0)
-            this.byAval.delete(av);
+        this.deleteEntry(av, chunkIdx);
+    }
+    /** Re-seat every entry's `ref` in `chunkIdx` after a waste-triggered
+     *  arena compaction relocated allocations. `remap` maps OLD→NEW byte
+     *  offset. Entries whose ref didn't move are left as-is. O(entries). */
+    remapRefs(chunkIdx, remap) {
+        if (remap.size === 0)
+            return;
+        for (const v of this.byAval.values()) {
+            const e = v instanceof Map ? v.get(chunkIdx) : (v.chunkIdx === chunkIdx ? v : undefined);
+            if (e === undefined)
+                continue;
+            const nn = remap.get(e.ref);
+            if (nn !== undefined)
+                e.ref = nn;
+        }
     }
     /** Re-pack one entry's data region into every chunk that holds
      *  this aval. When an aval is shared across N chunks (each chunk
      *  has its own duplicate alloc), every duplicate needs the
      *  refresh so all the chunks' ROs see the new value. */
     repack(device, arena, av, val) {
-        const byChunk = this.byAval.get(av);
-        if (byChunk === undefined)
-            return;
         let dst;
-        for (const e of byChunk.values()) {
+        for (const e of this.entriesOf(av)) {
             if (dst === undefined || dst.length !== e.dataBytes / 4) {
                 dst = new Float32Array(e.dataBytes / 4);
             }
@@ -163,18 +252,15 @@ export class UniformPool {
     /** Total bytes touched by `repack` for this aval — sum across
      *  chunks. Used by the dirty-bytes diagnostics. */
     totalDataBytes(av) {
-        const byChunk = this.byAval.get(av);
-        if (byChunk === undefined)
-            return 0;
         let s = 0;
-        for (const e of byChunk.values())
+        for (const e of this.entriesOf(av))
             s += e.dataBytes;
         return s;
     }
 }
 // ─── IndexPool ─────────────────────────────────────────────────────────
 /**
- * Aval-keyed pool over the `IndexAllocator`. Two draws referencing
+ * Aval-keyed pool over the (attribute) arena. Two draws referencing
  * the same `Uint32Array` (or aval thereof) share an index range —
  * 19K instanced clones of the same mesh share one allocation, one
  * upload.
@@ -187,8 +273,48 @@ export class UniformPool {
  */
 export class IndexPool {
     /** Per-aval, per-chunk bookkeeping. Same aval acquired in two
-     *  chunks gets two entries (accepted §3 duplication). */
+     *  chunks gets two entries (accepted §3 duplication). Value is a
+     *  single binding (common case) or a Map<chunkIdx, binding> once
+     *  the aval spans chunks — same flat-form saving as UniformPool. */
     byAval = new Map();
+    getBinding(av, chunkIdx) {
+        const v = this.byAval.get(av);
+        if (v === undefined)
+            return undefined;
+        if (v instanceof Map)
+            return v.get(chunkIdx);
+        return v.entry.chunkIdx === chunkIdx ? v : undefined;
+    }
+    setBinding(av, b) {
+        const v = this.byAval.get(av);
+        if (v === undefined) {
+            this.byAval.set(av, b);
+            return;
+        }
+        if (v instanceof Map) {
+            v.set(b.entry.chunkIdx, b);
+            return;
+        }
+        const m = new Map();
+        m.set(v.entry.chunkIdx, v);
+        m.set(b.entry.chunkIdx, b);
+        this.byAval.set(av, m);
+    }
+    deleteBinding(av, chunkIdx) {
+        const v = this.byAval.get(av);
+        if (v === undefined)
+            return;
+        if (v instanceof Map) {
+            v.delete(chunkIdx);
+            if (v.size === 1)
+                this.byAval.set(av, v.values().next().value);
+            else if (v.size === 0)
+                this.byAval.delete(av);
+            return;
+        }
+        if (v.entry.chunkIdx === chunkIdx)
+            this.byAval.delete(av);
+    }
     /** Per-chunk constant-aval value-dedup (§5b in-chunk). */
     byValueKey = new Map();
     bufferIds = new WeakMap();
@@ -202,14 +328,15 @@ export class IndexPool {
         return id;
     }
     firstChunkContaining(av) {
-        const byChunk = this.byAval.get(av);
-        if (byChunk === undefined || byChunk.size === 0)
+        const v = this.byAval.get(av);
+        if (v === undefined)
             return undefined;
-        return byChunk.keys().next().value;
+        if (v instanceof Map)
+            return v.size > 0 ? v.keys().next().value : undefined;
+        return v.entry.chunkIdx;
     }
-    acquire(device, indices, av, chunkIdx, arr) {
-        let byChunk = this.byAval.get(av);
-        const bound = byChunk?.get(chunkIdx);
+    acquire(device, arena, av, chunkIdx, arr) {
+        const bound = this.getBinding(av, chunkIdx);
         if (bound !== undefined) {
             bound.perAvalCount++;
             bound.entry.totalRefcount++;
@@ -219,51 +346,77 @@ export class IndexPool {
         if (av.isConstant) {
             // Value-dedup is scoped per chunk — two constant avals in the
             // same chunk collapse to one allocation; two constant avals in
-            // DIFFERENT chunks each get their own (we can't share across
-            // chunks since the index range lives in the chunk's GPUBuffer).
+            // DIFFERENT chunks each get their own (the index range lives in
+            // the chunk's GPUBuffer).
             valueKey = `${chunkIdx}:${this.bufferIdOf(arr.buffer)}:${arr.byteOffset}:${arr.byteLength}`;
             const shared = this.byValueKey.get(valueKey);
             if (shared !== undefined) {
                 shared.totalRefcount++;
-                if (byChunk === undefined) {
-                    byChunk = new Map();
-                    this.byAval.set(av, byChunk);
-                }
-                byChunk.set(chunkIdx, { entry: shared, perAvalCount: 1 });
+                this.setBinding(av, { entry: shared, perAvalCount: 1 });
                 return { chunkIdx: shared.chunkIdx, firstIndex: shared.firstIndex, count: shared.count };
             }
         }
-        const r = indices.alloc(arr.length, chunkIdx);
-        indices.write(r.chunkIdx, r.off * 4, new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength));
+        // Index data lives in the SAME arena as attributes/uniforms (the heap VS
+        // storage-decodes indices — `indexStorage[_indexStart + i]` — so they need
+        // no separate index buffer). Allocate a normal header+data region; the
+        // raw u32 indices sit at `ref + 16`, so the element offset the drawTable
+        // stores is `(ref + 16) >> 2`. The header is unread by index gathers but
+        // kept for a uniform region layout (and so compaction treats it like any
+        // other region).
+        const byteLen = arr.byteLength;
+        const r = arena.alloc(byteLen, chunkIdx);
+        const dataOff = r.off + ALLOC_HEADER_PAD_TO;
+        const hdr = new Uint32Array([0, arr.length, 4, 0]); // (typeId, length, strideBytes, pad)
+        arena.write(r.chunkIdx, r.off, new Uint8Array(hdr.buffer));
+        arena.write(r.chunkIdx, dataOff, new Uint8Array(arr.buffer, arr.byteOffset, byteLen));
         void device;
+        const firstIndex = dataOff >>> 2;
         const entry = {
-            chunkIdx: r.chunkIdx, firstIndex: r.off, count: arr.length,
+            chunkIdx: r.chunkIdx, ref: r.off, firstIndex, count: arr.length,
             totalRefcount: 1, valueKey,
         };
-        if (byChunk === undefined) {
-            byChunk = new Map();
-            this.byAval.set(av, byChunk);
-        }
-        byChunk.set(r.chunkIdx, { entry, perAvalCount: 1 });
+        this.setBinding(av, { entry, perAvalCount: 1 });
         if (valueKey !== undefined)
             this.byValueKey.set(valueKey, entry);
-        return { chunkIdx: r.chunkIdx, firstIndex: r.off, count: arr.length };
+        return { chunkIdx: r.chunkIdx, firstIndex, count: arr.length };
+    }
+    /** The allocation's byte header offset (`ref`) of `av`'s entry in `chunkIdx`,
+     *  or undefined if not allocated there. The heap compaction pass looks the
+     *  region up in the arena remap by this ref to compute the draw's new
+     *  `_indexStart`. */
+    baseFor(av, chunkIdx) {
+        return this.getBinding(av, chunkIdx)?.entry.ref;
+    }
+    /** Re-seat every entry after a compaction relocated its region. `remap` maps
+     *  OLD→NEW byte header offset (`ref`); `firstIndex` is recomputed from the
+     *  new ref. Entries are shared by value-dedup, so each is visited once. */
+    remapRefs(chunkIdx, remap) {
+        if (remap.size === 0)
+            return;
+        const seen = new Set();
+        for (const v of this.byAval.values()) {
+            const bound = v instanceof Map ? v.get(chunkIdx) : (v.entry.chunkIdx === chunkIdx ? v : undefined);
+            if (bound === undefined || seen.has(bound.entry))
+                continue;
+            seen.add(bound.entry);
+            const nn = remap.get(bound.entry.ref);
+            if (nn !== undefined) {
+                bound.entry.ref = nn;
+                bound.entry.firstIndex = (nn + ALLOC_HEADER_PAD_TO) >>> 2;
+            }
+        }
     }
-    release(indices, av, chunkIdx) {
-        const byChunk = this.byAval.get(av);
-        const bound = byChunk?.get(chunkIdx);
+    release(arena, av, chunkIdx) {
+        const bound = this.getBinding(av, chunkIdx);
         if (bound === undefined)
             return;
         bound.perAvalCount--;
         bound.entry.totalRefcount--;
-        if (bound.perAvalCount === 0) {
-            byChunk.delete(chunkIdx);
-            if (byChunk.size === 0)
-                this.byAval.delete(av);
-        }
+        if (bound.perAvalCount === 0)
+            this.deleteBinding(av, chunkIdx);
         if (bound.entry.totalRefcount > 0)
             return;
-        indices.release(bound.entry.chunkIdx, bound.entry.firstIndex, bound.entry.count);
+        arena.release(bound.entry.chunkIdx, bound.entry.ref, bound.entry.count * 4);
         if (bound.entry.valueKey !== undefined) {
             this.byValueKey.delete(bound.entry.valueKey);
         }
@@ -320,52 +473,43 @@ export class DrawHeap {
  * onto a sorted free list with coalesce on insert.
  */
 export class AttributeArena {
+    device;
     buf;
     cursor = 0;
+    /** Sum of `allocBytes` over all live allocations. `cursor - liveBytes`
+     *  is the fragmentation waste below the high-water mark — what
+     *  `compact()` reclaims. */
+    liveBytes = 0;
     freelist = new Freelist();
     /** DEBUG: tracks every live allocation by start byte → size. Set
      *  on alloc, cleared on release. Used by `assertNoOverlap()` to
      *  detect allocator returning overlapping ranges. Enabled in
      *  development; cheap (one Map insert/delete per alloc). */
     liveAllocs = new Map();
-    /** CPU shadow of the entire GPU buffer; writes go here first then
-     *  flush() emits one writeBuffer per dirty contiguous range. A
-     *  single min..max span would re-upload nearly the whole arena on
-     *  scattered edits — see dirtyRanges.ts. */
-    shadow;
-    dirty = new DirtyRanges();
-    constructor(buf) {
+    // MIRROR-LESS: no CPU shadow of the arena. Writes go straight to
+    // `queue.writeBuffer` (queue-ordered with submits, so they serialize
+    // correctly against GrowBuffer's grow-copy and the compaction bounce —
+    // both of which preserve contents GPU-side). This halves the heap's
+    // host-memory footprint: the source-of-truth for values is the user's
+    // avals (they must stay alive — changeability is the point), and the
+    // GPU buffer is the render copy; a third full-size CPU mirror bought
+    // only dirty-range batching + debug readback comparisons.
+    constructor(device, buf) {
+        this.device = device;
         this.buf = buf;
-        this.shadow = new Uint8Array(buf.capacity);
-        buf.onResize(() => {
-            const grown = new Uint8Array(buf.capacity);
-            grown.set(this.shadow);
-            this.shadow = grown;
-        });
     }
     get buffer() { return this.buf.buffer; }
     get capacity() { return this.buf.capacity; }
     get usedBytes() { return this.cursor; }
-    /** Read 4 u32s from the CPU shadow starting at byte `off`. Used by
-     *  the validator to compare against the GPU's read-back values:
-     *  if CPU shadow is correct but GPU shows garbage → the corruption
-     *  came from a GPU-side write (a compute kernel writing to a wrong
-     *  byte). If both differ from what pool.acquire wrote → CPU-side
-     *  write path is the culprit. */
-    peekShadowU32(off, count) {
-        return new Uint32Array(this.shadow.buffer, this.shadow.byteOffset + off, count);
-    }
     write(dst, data) {
-        this.shadow.set(data, dst);
-        this.dirty.add(dst, dst + data.byteLength);
-    }
-    flush(device) {
-        if (this.dirty.isEmpty)
-            return;
-        this.dirty.drain((start, end) => {
-            device.queue.writeBuffer(this.buf.buffer, start, this.shadow.buffer, this.shadow.byteOffset + start, end - start);
-        });
+        // Immediate upload; Chrome's queue staging does the batching. The
+        // write targets the CURRENT buffer handle — a later grow copies it
+        // forward (queue-ordered), so ordering stays correct.
+        this.device.queue.writeBuffer(this.buf.buffer, dst, data);
     }
+    /** No-op — kept for call-site compatibility (mirror-less arena uploads
+     *  in `write`). */
+    flush(_device) { }
     /**
      * Allocate space for one attribute. Returns the byte ref (offset
      * to the header — data lives at ref + 16).
@@ -379,6 +523,7 @@ export class AttributeArena {
         const reused = this.freelist.alloc(allocBytes);
         if (reused !== undefined) {
             this.recordAlloc(reused, allocBytes, "freelist");
+            this.liveBytes += allocBytes;
             return reused;
         }
         const next = this.cursor + allocBytes;
@@ -389,6 +534,7 @@ export class AttributeArena {
         this.buf.setUsed(next);
         const ref = next - allocBytes;
         this.recordAlloc(ref, allocBytes, "bump");
+        this.liveBytes += allocBytes;
         return ref;
     }
     alloc(dataBytes) {
@@ -412,6 +558,7 @@ export class AttributeArena {
                 `Caller is releasing the wrong size; this WILL corrupt the freelist via over- or under-shrinking.`);
         }
         this.liveAllocs.delete(ref);
+        this.liveBytes -= allocBytes;
         this.freelist.release(ref, allocBytes);
         // §5: shrink the bump cursor back if release exposed a free
         // tail touching it (cascading — `freelist.release` may have
@@ -441,103 +588,92 @@ export class AttributeArena {
         }
         this.liveAllocs.set(off, size);
     }
-    onResize(cb) { return this.buf.onResize(cb); }
-    destroy() { this.buf.destroy(); }
-}
-// ─── IndexAllocator (element-bump) ─────────────────────────────────────
-/**
- * Element-bump allocator over an index GrowBuffer (units = u32). Each
- * draw's index range is allocated as one block; on release the block
- * is returned to a Freelist and can be reused best-fit.
- */
-export class IndexAllocator {
-    buf;
-    cursor = 0; // in u32s, not bytes
-    freelist = new Freelist();
-    /** DEBUG: live index allocations tracked by start element. */
-    liveAllocs = new Map();
-    shadow;
-    dirty = new DirtyRanges();
-    constructor(buf) {
-        this.buf = buf;
-        this.shadow = new Uint8Array(buf.capacity);
-        buf.onResize(() => {
-            const grown = new Uint8Array(buf.capacity);
-            grown.set(this.shadow);
-            this.shadow = grown;
-        });
-    }
-    get buffer() { return this.buf.buffer; }
-    get usedElements() { return this.cursor; }
-    write(dstByteOffset, data) {
-        this.shadow.set(data, dstByteOffset);
-        this.dirty.add(dstByteOffset, dstByteOffset + data.byteLength);
-    }
-    flush(device) {
-        if (this.dirty.isEmpty)
-            return;
-        this.dirty.drain((start, end) => {
-            device.queue.writeBuffer(this.buf.buffer, start, this.shadow.buffer, this.shadow.byteOffset + start, end - start);
-        });
-    }
-    /** Non-throwing alloc — returns `undefined` when the request
-     *  would exceed the underlying GrowBuffer's `maxCapacity` cap.
-     *  Used by `ChunkedIndexAllocator` to probe before spilling. */
-    tryAlloc(elements) {
-        const reused = this.freelist.alloc(elements);
-        if (reused !== undefined) {
-            this.recordAlloc(reused, elements, "freelist");
-            return reused;
+    /** Bytes the bump cursor can still grow into before hitting the chunk cap
+     *  (ignores freelist holes — a conservative lower bound on free space, used
+     *  by group placement to decide whether a draw's group fits here). */
+    get bumpHeadroom() { return this.buf.maxCapacity - this.cursor; }
+    /** Live bytes (sum of all live allocations, header+pad included). */
+    get liveByteCount() { return this.liveBytes; }
+    /** Fragmentation waste below the high-water mark: free bytes the tail-
+     *  reclaim couldn't recover because they sit between live allocations. */
+    get wasteBytes() { return this.cursor - this.liveBytes; }
+    /**
+     * Waste-triggered compaction. Relocates live allocations to the front of
+     * the buffer, eliminating the high-water ratchet that exact-size freelist
+     * reuse alone can't fix (a drifting allocation-size distribution never
+     * reuses its holes and grows toward the high-water forever).
+     *
+     * The byte move happens GPU-side via `copyBufferToBuffer` through a scratch
+     * buffer — no CPU→GPU re-upload — and is mirrored into the CPU shadow so it
+     * stays authoritative for future partial writes. Same-buffer copies can't
+     * overlap, hence the scratch round-trip.
+     *
+     * Returns a map of OLD→NEW byte offset for every allocation that moved; the
+     * caller must re-seat every cached ref (drawHeader cells, uniform-pool
+     * entries, derived-uniform handles, partition master refs). Returns an
+     * empty map when it declines to compact (waste below `wasteFloorBytes` or
+     * less than half the extent wasted).
+     *
+     * Precondition: the arena's pending shadow writes must already be flushed
+     * to the GPU buffer (the GPU copy reads the live buffer). O(live).
+     */
+    compact(device, wasteFloorBytes, force = false) {
+        const waste = this.cursor - this.liveBytes;
+        if (!force && (this.liveBytes * 2 >= this.cursor || waste < wasteFloorBytes)) {
+            return new Map();
         }
-        const nextElts = this.cursor + elements;
-        if (nextElts * 4 > this.buf.maxCapacity)
-            return undefined;
-        this.cursor = nextElts;
-        this.buf.ensureCapacity(nextElts * 4);
-        this.buf.setUsed(nextElts * 4);
-        const off = nextElts - elements;
-        this.recordAlloc(off, elements, "bump");
-        return off;
-    }
-    recordAlloc(off, size, source) {
-        if (DEBUG_ALLOC_OVERLAP) {
-            for (const [liveOff, liveSize] of this.liveAllocs) {
-                if (off < liveOff + liveSize && liveOff < off + size) {
-                    throw new Error(`IndexAllocator.tryAlloc(${source}): returned [${off},${off + size}) ` +
-                        `(size=${size}) overlaps live alloc at [${liveOff},${liveOff + liveSize}) ` +
-                        `(size=${liveSize}). Index allocator is handing out shared memory!`);
-                }
+        // Live allocations sorted by current offset.
+        const live = [...this.liveAllocs.entries()].sort((a, b) => a[0] - b[0]);
+        // Assign packed offsets (bump from 0); build the OLD→NEW remap and the
+        // source-contiguous runs to copy. A run is a maximal set of live blocks
+        // adjacent in the source; under the bump it lands dest-contiguous too, so
+        // the compacted prefix [0, newExtent) is fully covered by the runs.
+        const remap = new Map();
+        const runs = [];
+        let w = 0;
+        let cur;
+        for (const [off, size] of live) {
+            if (w !== off)
+                remap.set(off, w);
+            if (cur !== undefined && off === cur.srcStart + cur.len) {
+                cur.len += size;
             }
+            else {
+                cur = { srcStart: off, dstStart: w, len: size };
+                runs.push(cur);
+            }
+            w += size;
         }
-        this.liveAllocs.set(off, size);
-    }
-    alloc(elements) {
-        const r = this.tryAlloc(elements);
-        if (r === undefined) {
-            throw new Error(`IndexAllocator: allocation of ${elements} elements exceeds chunk cap`);
-        }
-        return r;
-    }
-    release(off, elements) {
-        const tracked = this.liveAllocs.get(off);
-        if (tracked === undefined) {
-            throw new Error(`IndexAllocator.release: off=${off} (elements=${elements}) was not in ` +
-                `liveAllocs — double-free or release for an alloc that never happened. ` +
-                `Live alloc count=${this.liveAllocs.size}.`);
-        }
-        if (tracked !== elements) {
-            throw new Error(`IndexAllocator.release: size mismatch at off=${off} — recorded=${tracked} ` +
-                `but release elements=${elements}. Will corrupt the freelist.`);
-        }
-        this.liveAllocs.delete(off);
-        this.freelist.release(off, elements);
-        while (true) {
-            const top = this.freelist.takeBlockEndingAt(this.cursor);
-            if (top === undefined)
-                break;
-            this.cursor = top.off;
-            this.buf.setUsed(this.cursor * 4);
+        const newExtent = w;
+        if (remap.size === 0)
+            return remap; // already tight
+        // GPU move: arena → scratch (compacted), then scratch → arena[0,newExtent).
+        // Both copies are between distinct buffers, so no overlap constraint.
+        const scratch = device.createBuffer({
+            label: "AttributeArena/compact-scratch",
+            size: newExtent,
+            usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+        });
+        const enc = device.createCommandEncoder({ label: "AttributeArena/compact" });
+        for (const r of runs) {
+            enc.copyBufferToBuffer(this.buf.buffer, r.srcStart, scratch, r.dstStart, r.len);
         }
+        enc.copyBufferToBuffer(scratch, 0, this.buf.buffer, 0, newExtent);
+        device.queue.submit([enc.finish()]);
+        scratch.destroy();
+        // Rebuild allocator bookkeeping: live allocs at their new offsets, no free
+        // blocks (everything is now contiguous), cursor at the new high-water.
+        // (Mirror-less: the GPU bounce above IS the move — nothing else to sync.)
+        const moved = [];
+        for (const [off, size] of live)
+            moved.push([remap.get(off) ?? off, size]);
+        this.liveAllocs.clear();
+        for (const [o, s] of moved)
+            this.liveAllocs.set(o, s);
+        this.freelist.clear();
+        this.cursor = newExtent;
+        this.buf.setUsed(newExtent);
+        return remap;
     }
     onResize(cb) { return this.buf.onResize(cb); }
     destroy() { this.buf.destroy(); }
@@ -551,12 +687,17 @@ export function buildArenaState(device, attrBytesHint, idxBytesHint, label, idxE
     // exercise multi-chunk routing).
     const adapterCap = device.limits.maxStorageBufferBindingSize;
     const cap = maxChunkBytes ?? Math.min(adapterCap, DEFAULT_MAX_BUFFER_BYTES);
-    const attrs = new ChunkedAttributeArena(device, `${label}/attrs`, GPUBufferUsage.STORAGE, attrBytesHint, cap);
-    const indices = new ChunkedIndexAllocator(device, `${label}/idx`, GPUBufferUsage.INDEX | idxExtraUsage, idxBytesHint, cap);
-    return { attrs, indices };
+    void idxBytesHint;
+    void idxExtraUsage; // legacy params (separate index buffer removed)
+    // Clamp the pre-size hint to the per-chunk cap: GrowBuffer RAISES its max
+    // to fit a larger initial size, which would mint an oversized page (and
+    // §7 derived-record handles cap page offsets at 2^29 B = 512 MB). A
+    // multi-page scene simply pre-sizes each page at the cap as it opens.
+    const attrs = new ChunkedAttributeArena(device, `${label}/arena`, GPUBufferUsage.STORAGE, Math.min(attrBytesHint, cap), cap);
+    return { attrs };
 }
 export function arenaBytes(arena) {
-    return arena.attrs.totalUsedBytes() + arena.indices.totalUsedElements() * 4;
+    return arena.attrs.totalUsedBytes();
 }
 /** Upload a single attribute — header (typeId, length) + data — into the arena at byte offset `ref`. */
 export function writeAttribute(device, buf, ref, typeId, length, data) {