@woosh/meep-engine 3.11.3 → 3.12.0

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.js

@@ -1,775 +1,775 @@
-import { assert } from "../../../../core/assert.js";
-import { ALLOCATOR_NO_SPACE, OffsetAllocator } from "../../../../core/binary/allocator/OffsetAllocator.js";
-import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
-import { platform_compute_endianness } from "../../../../core/binary/platform_compute_endianness.js";
-import Signal from "../../../../core/events/signal/Signal.js";
-import { MEGABYTE } from "../../../../core/science/units/memory/MEGABYTE.js";
-import { read_wgsl_type_value } from "../../shader/type/serde/read_gpu_typed_buffer.js";
-import { write_wgsl_type_value } from "../../shader/type/serde/write_gpu_typed_buffer.js";
-import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { inspect_gpu_buffer_typed } from "../../buffer/inspect_gpu_buffer_typed.js";
-import {
-    BUFFER_INTRA_COPY_REGION_STRUCT,
-    shader_buffer_intra_copy_regions
-} from "../../buffer/util/shader_buffer_intra_copy_regions.js";
-import { MESHLET_METADATA_STRUCT } from "./encoding/MESHLET_METADATA_STRUCT.js";
-import { shader_meshlet_metadata_address_patch } from "./shader_meshlet_metadata_address_patch.js";
-
-/**
- * In meshlets
- * @type {number}
- */
-const DEFAULT_METADATA_CAPACITY = 128 * 1024;
-
-/**
- * In bytes
- * @type {number}
- */
-const DEFAULT_DATA_CAPACITY = 32 * MEGABYTE;
-
-class MeshletBatchAllocationRecord {
-    /**
-     * @type {Allocation}
-     */
-    metadata
-    /**
-     * @type {Allocation}
-     */
-    data
-
-    /**
-     * Number of words
-     * @type {number}
-     */
-    data_size = 0;
-
-    /**
-     * Meshlet count
-     * @type {number}
-     */
-    meshlet_count = 0;
-
-    /**
-     *
-     * @type {ArrayBuffer}
-     */
-    metadata_buffer_original;
-
-    /**
-     *
-     * @type {Signal<>}
-     */
-    changed = new Signal()
-}
-
-export class GPUMeshletManager {
-
-    /**
-     * Allocation sizes in words of 4 bytes
-     * @type {OffsetAllocator}
-     */
-    #allocator_data = new OffsetAllocator(1024);
-
-    /**
-     * Allocation sizes in meshlets
-     * @type {OffsetAllocator}
-     */
-    #allocator_metadata = new OffsetAllocator(1024);
-
-    /**
-     * @type {GPUBuffer}
-     */
-    #meshlet_data_buffer;
-
-    get buffer_data() {
-        return this.#meshlet_data_buffer;
-    }
-
-    /**
-     * @type {GPUBuffer}
-     */
-    #meshlet_metadata_buffer;
-
-    get buffer_metadata() {
-        return this.#meshlet_metadata_buffer;
-    }
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
-    /**
-     *
-     * @type {number}
-     */
-    #deallocations_since_last_rebuild = 0;
-
-    /**
-     *
-     * @type {MeshletBatchAllocationRecord[]}
-     */
-    #records = [];
-
-    /**
-     * Queue of GPU-side clones that have been allocated but not yet
-     * copied + patched. Drained by {@link update}. Each entry holds the
-     * minimum bookkeeping needed to issue two `copyBufferToBuffer`
-     * commands and N `(record_index, address_delta)` patch entries.
-     *
-     * Entries name the two records, not the addresses they held when the
-     * clone was queued: a {@link compact} or {@link grow} in between
-     * migrates both, and {@link update} reads where they ended up. What
-     * an entry does require is that neither record is handed back to
-     * {@link remove_batch} before the flush.
-     *
-     * @type {{
-     *   source: MeshletBatchAllocationRecord,
-     *   clone: MeshletBatchAllocationRecord,
-     * }[]}
-     */
-    #pending_clones = [];
-
-    /**
-     *
-     * @param {GPUDevice} device
-     * @param {number} [initial_data_capacity] in bytes
-     * @param {number} [initial_metadata_capacity] in meshlets
-     */
-    constructor({
-                    device,
-                    initial_data_capacity = DEFAULT_DATA_CAPACITY,
-                    initial_metadata_capacity = DEFAULT_METADATA_CAPACITY,
-                }) {
-        assert.defined(device, 'device');
-
-        assert.isNonNegativeInteger(initial_data_capacity, 'initial_data_capacity');
-        assert.isNonNegativeInteger(initial_metadata_capacity, 'initial_metadata_capacity');
-
-        assert.greaterThan(initial_data_capacity, 0, 'initial_data_capacity');
-        assert.greaterThan(initial_metadata_capacity, 0, 'initial_data_capacity');
-
-        this.#device = device;
-
-        const data_buffer_size_words = Math.ceil(initial_data_capacity / 4);
-
-        // TODO manage max-allocations as well
-        this.#allocator_data = new OffsetAllocator(data_buffer_size_words);
-        this.#allocator_metadata = new OffsetAllocator(initial_metadata_capacity);
-
-        this.#meshlet_data_buffer = device.createBuffer({
-            label: 'GPUMeshletManager/data',
-            size: data_buffer_size_words * 4,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
-        });
-
-        this.#meshlet_metadata_buffer = device.createBuffer({
-            label: 'GPUMeshletManager/metadata',
-            size: initial_metadata_capacity * MESHLET_METADATA_STRUCT.aligned_size,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
-        });
-
-    }
-
-    compact() {
-        this.#rebuild(
-            this.#meshlet_data_buffer.size >>> 2,
-            Math.ceil(this.#meshlet_metadata_buffer.size / MESHLET_METADATA_STRUCT.aligned_size)
-        );
-    }
-
-    /**
-     *
-     * @param {number} extra_data_size in words (4 bytes)
-     * @param {number} extra_metadata_size in metadata elements
-     */
-    grow(extra_data_size, extra_metadata_size) {
-        assert.isNonNegativeInteger(extra_data_size, 'extra_data_size');
-        assert.isNonNegativeInteger(extra_metadata_size, 'extra_metadata_size');
-
-        if (extra_data_size === 0 && extra_metadata_size === 0) {
-            // nothing to do
-            return;
-        }
-
-        const current_data_buffer_size_bytes = this.#meshlet_data_buffer.size;
-        const current_metadata_buffer_size = this.#meshlet_metadata_buffer.size;
-
-        const current_buffer_size_words = current_data_buffer_size_bytes >> 2;
-        const current_metadata_buffer_size_elements = Math.ceil(current_metadata_buffer_size / MESHLET_METADATA_STRUCT.aligned_size);
-
-        const DATA_GROWTH_STEP = 16 * 1024;
-        const METADATA_GROWTH_STEP = 256;
-        const GROWTH_MULTIPLIER = 1.25;
-
-        let new_data_size;
-        if (extra_data_size === 0) {
-            new_data_size = current_buffer_size_words;
-        } else {
-            // grow
-            new_data_size = Math.max(
-                current_buffer_size_words + extra_data_size,
-                current_buffer_size_words + DATA_GROWTH_STEP,
-                Math.ceil(current_buffer_size_words * GROWTH_MULTIPLIER)
-            );
-        }
-
-        let new_metadata_size;
-        if (extra_metadata_size === 0) {
-            new_metadata_size = current_metadata_buffer_size_elements;
-        } else {
-            // grow
-            new_metadata_size = Math.max(
-                current_metadata_buffer_size_elements + extra_metadata_size,
-                current_metadata_buffer_size_elements + METADATA_GROWTH_STEP,
-                current_metadata_buffer_size_elements * GROWTH_MULTIPLIER
-            );
-        }
-
-        this.#rebuild(
-            new_data_size,
-            new_metadata_size
-        );
-    }
-
-    /**
-     * Helper to patch pointers in metadata and upload to GPU
-     * @param {ArrayBuffer} source_array_buffer
-     * @param {number} meshlet_count
-     * @param {number} data_offset_words
-     * @param {number} metadata_offset_index
-     * @param {GPUBuffer} target_buffer
-     */
-    #write_patched_metadata(
-        source_array_buffer,
-        meshlet_count,
-        data_offset_words,
-        metadata_offset_index,
-        target_buffer
-    ) {
-        const temp_writer = BinaryBuffer.fromEndianness(platform_compute_endianness());
-        temp_writer.setCapacity(meshlet_count * MESHLET_METADATA_STRUCT.size); // pre-allocate to avoid resizing
-
-        const source_reader = BinaryBuffer.fromArrayBuffer(source_array_buffer);
-        source_reader.endianness = platform_compute_endianness();
-
-        // Iterate over meshlets in the batch, patch the address, and write to temp buffer
-        for (let i = 0; i < meshlet_count; i++) {
-            const header = read_wgsl_type_value(source_reader, MESHLET_METADATA_STRUCT);
-
-            // PATCH: Add the allocation offset to the relative address
-            header.address += data_offset_words;
-
-            write_wgsl_type_value(header, temp_writer, MESHLET_METADATA_STRUCT);
-        }
-
-        // Upload
-        this.#device.queue.writeBuffer(
-            target_buffer,
-            metadata_offset_index * MESHLET_METADATA_STRUCT.aligned_size,
-            temp_writer.data,
-            0,
-            meshlet_count * MESHLET_METADATA_STRUCT.aligned_size
-        );
-    }
-
-    /**
-     *
-     * @param {number} new_data_size
-     * @param {number} new_metadata_size
-     */
-    #rebuild(
-        new_data_size,
-        new_metadata_size
-    ) {
-
-        assert.isNonNegativeInteger(new_data_size, 'new_data_size');
-        assert.isNonNegativeInteger(new_metadata_size, 'new_metadata_size');
-
-        // Outstanding clone work survives this. A queued clone names its
-        // source and destination records, both of which are migrated
-        // below, and the flush reads their addresses when it runs — so a
-        // rebuild moves the copy rather than invalidating it.
-
-        // console.warn('GPUMeshletManager/rebuild');
-
-        const device = this.#device;
-
-        const records = this.#records;
-        const record_count = records.length;
-        const new_allocator_data = new OffsetAllocator(
-            new_data_size,
-            Math.max(record_count * 2, 128 * 1024)
-        );
-
-        const old_buffer_data = this.#meshlet_data_buffer;
-        const new_buffer_data = device.createBuffer({
-            label: old_buffer_data.label,
-            usage: old_buffer_data.usage,
-            size: new_data_size * 4,
-        });
-
-        const new_allocator_metadata = new OffsetAllocator(
-            new_metadata_size,
-            Math.max(record_count * 2, 128 * 1024)
-        );
-
-        const old_buffer_metadata = this.#meshlet_metadata_buffer;
-        const new_buffer_metadata = device.createBuffer({
-            label: old_buffer_metadata.label,
-            usage: old_buffer_metadata.usage,
-            size: new_metadata_size * MESHLET_METADATA_STRUCT.aligned_size,
-        });
-
-        const encoder = device.createCommandEncoder({
-            label: "GPUMeshletManager/rebuild",
-        });
-
-        const moved_records = [];
-
-        // move data
-        for (let i = 0; i < record_count; i++) {
-            const record = records[i];
-
-            const new_allocation_data = new_allocator_data.allocate(record.data_size);
-            const new_allocation_metadata = new_allocator_metadata.allocate(record.meshlet_count);
-
-            assert.notEqual(new_allocation_data.offset, ALLOCATOR_NO_SPACE);
-            assert.notEqual(new_allocation_metadata.offset, ALLOCATOR_NO_SPACE);
-
-            encoder.copyBufferToBuffer(
-                old_buffer_data, record.data.offset * 4,
-                new_buffer_data, new_allocation_data.offset * 4,
-                record.data_size * 4
-            );
-
-            const metadata_record_moved = record.data.offset !== new_allocation_data.offset;
-
-            // B. Patch Metadata (CPU -> GPU Write)
-            // Metadata contains `address` which points to the Data offset.
-            // Since the Data offset changed, we must re-calculate and upload the metadata.
-            // We reuse the helper to avoid code duplication.
-            this.#write_patched_metadata(
-                record.metadata_buffer_original,
-                record.meshlet_count,
-                new_allocation_data.offset, // The NEW data offset
-                new_allocation_metadata.offset, // The NEW metadata location
-                new_buffer_metadata
-            );
-
-            // update record
-            record.data = new_allocation_data;
-            record.metadata = new_allocation_metadata;
-
-            if (metadata_record_moved) {
-                moved_records.push(record);
-            }
-        }
-
-        for (const record of moved_records) {
-            // notify
-            record.changed.send0();
-        }
-
-        const command_buffer = encoder.finish();
-
-        device.queue.submit([command_buffer]);
-
-        old_buffer_data.destroy();
-        old_buffer_metadata.destroy();
-
-        this.#meshlet_data_buffer = new_buffer_data;
-        this.#meshlet_metadata_buffer = new_buffer_metadata;
-
-        this.#allocator_data = new_allocator_data;
-        this.#allocator_metadata = new_allocator_metadata;
-
-        // reset count
-        this.#deallocations_since_last_rebuild = 0;
-    }
-
-    /**
-     * Allocate `data_size_words` in the data buffer and `meshlet_count`
-     * in the metadata buffer, retrying with compact-then-grow on failure.
-     * Throws if the third attempt still can't satisfy both. The two
-     * allocations are kept in lockstep — partial successes are released
-     * before retrying so we never leak.
-     *
-     * Compaction triggers a full {@link #rebuild} which migrates every
-     * existing allocation to a new buffer pair. Queued clone work is
-     * carried through it — {@link #pending_clones} names records, not
-     * addresses — so an allocation made while a clone is pending is safe.
-     *
-     * @param {number} data_size_words
-     * @param {number} meshlet_count
-     * @returns {{data: Allocation, metadata: Allocation}}
-     */
-    #allocate_data_and_metadata(data_size_words, meshlet_count) {
-        let data_allocation;
-        let metadata_allocation;
-
-        for (let try_index = 0; try_index < 3; try_index++) {
-
-            data_allocation = this.#allocator_data.allocate(data_size_words);
-            metadata_allocation = this.#allocator_metadata.allocate(meshlet_count);
-
-            const data_ok = data_allocation.offset !== ALLOCATOR_NO_SPACE;
-            const metadata_ok = metadata_allocation.offset !== ALLOCATOR_NO_SPACE;
-
-            if (data_ok && metadata_ok) {
-                break;
-            }
-
-            // release partial allocation
-            if (data_ok) {
-                this.#allocator_data.free(data_allocation);
-
-                data_allocation.offset = ALLOCATOR_NO_SPACE;
-                data_allocation.metadata = ALLOCATOR_NO_SPACE;
-            }
-            if (metadata_ok) {
-                this.#allocator_metadata.free(metadata_allocation);
-
-                metadata_allocation.offset = ALLOCATOR_NO_SPACE;
-                metadata_allocation.metadata = ALLOCATOR_NO_SPACE;
-            }
-
-            if (this.#deallocations_since_last_rebuild > 0) {
-                // try compaction
-                this.compact();
-                continue;
-            }
-
-            let grow_data_size = data_ok ? 0 : data_size_words;
-            let grow_metadata_size = metadata_ok ? 0 : meshlet_count;
-
-            this.grow(grow_data_size, grow_metadata_size);
-
-        }
-
-        if (data_allocation.offset === ALLOCATOR_NO_SPACE || metadata_allocation.offset === ALLOCATOR_NO_SPACE) {
-            throw new Error('Failed to allocate GPU memory for meshlet batch');
-        }
-
-        return { data: data_allocation, metadata: metadata_allocation };
-    }
-
-    /**
-     *
-     * @param {MeshletBatch} batch
-     * @returns {MeshletBatchAllocationRecord}
-     */
-    #allocate_for_batch(batch) {
-        assert.defined(batch, 'batch');
-
-        const data_buffer = batch.data_buffer;
-
-        const data_size_words = Math.ceil(data_buffer.byteLength / 4);
-
-        const meshlet_count = batch.count;
-
-        const { data, metadata } = this.#allocate_data_and_metadata(data_size_words, meshlet_count);
-
-        const record = new MeshletBatchAllocationRecord();
-
-        record.data = data;
-        record.metadata = metadata;
-
-        record.meshlet_count = meshlet_count;
-        record.data_size = data_size_words;
-
-        record.metadata_buffer_original = batch.metadata_buffer;
-
-        this.#records.push(record);
-
-        return record;
-    }
-
-    /**
-     * Release a batch allocation back to the data and metadata allocators. The GPU bytes are
-     * not cleared — the freed slices are reclaimed lazily by the next {@link compact} (a
-     * deallocation bumps the compaction counter the allocator consults under pressure).
-     * Other batches' allocations are unaffected (the OffsetAllocator frees disjoint slices),
-     * so callers only need to ensure nothing still references this batch's metadata rows
-     * (the geometry table rebuild in {@link GPUGeometryManager} handles that).
-     *
-     * @param {MeshletBatchAllocationRecord} record a record returned by {@link add_batch} or
-     *        {@link clone_batch_allocation}
-     * @returns {boolean} true if the record was owned and freed
-     */
-    remove_batch(record) {
-        assert.defined(record, 'record');
-
-        const index = this.#records.indexOf(record);
-        if (index === -1) {
-            return false;
-        }
-
-        this.#allocator_data.free(record.data);
-        this.#allocator_metadata.free(record.metadata);
-
-        this.#records.splice(index, 1);
-        this.#deallocations_since_last_rebuild++;
-
-        return true;
-    }
-
-    /**
-     * Allocate a fresh (data, metadata) pair sized to mirror `source`,
-     * and queue a GPU-side clone: the source's data and metadata are
-     * copied into the new ranges via `copyBufferToBuffer`, then a
-     * compute pass patches the cloned metadata records' `address`
-     * fields to point at the new data range. Both the copies and the
-     * patch dispatch land when the host next calls
-     * {@link update update(cmd_ctx)}.
-     *
-     * The returned record can be wired into the geometry table
-     * immediately — its `data.offset` and `metadata.offset` are valid
-     * the moment this call returns. The GPU bytes at those addresses
-     * just aren't populated yet; downstream passes that consume the
-     * clone must run after the next `update`. Those addresses may still
-     * move before the flush, which is why nothing outside the record is
-     * allowed to remember them.
-     *
-     * Sharing the source's `metadata_buffer_original` lets a future
-     * compaction patch the clone's metadata from the same un-patched
-     * CPU bytes the source uses — the post-patch state on the GPU is
-     * identical to the source aside from the data offset.
-     *
-     * @param {MeshletBatchAllocationRecord} source
-     * @returns {MeshletBatchAllocationRecord}
-     */
-    clone_batch_allocation(source) {
-        assert.defined(source, 'source');
-        assert.greaterThan(source.meshlet_count, 0, 'source.meshlet_count');
-
-        const { data, metadata } = this.#allocate_data_and_metadata(source.data_size, source.meshlet_count);
-
-        const record = new MeshletBatchAllocationRecord();
-
-        record.data = data;
-        record.metadata = metadata;
-
-        record.meshlet_count = source.meshlet_count;
-        record.data_size = source.data_size;
-
-        // Share the un-patched CPU bytes so a future compact rewrites
-        // the clone's metadata correctly under its new data offset.
-        record.metadata_buffer_original = source.metadata_buffer_original;
-
-        this.#records.push(record);
-
-        // The queue names the two records rather than the addresses they
-        // hold right now. Both are in `#records`, so a rebuild between
-        // this call and the flush moves them and the flush still reads
-        // where they went — which is what lets a clone be queued in the
-        // same frame as the growth another geometry's arrival forces.
-        this.#pending_clones.push({ source, clone: record });
-
-        return record;
-    }
-
-    /**
-     * Flush any pending clone work into `cmd_ctx`. For each queued
-     * clone, emits two `copyBufferToBuffer` commands (one for vertex
-     * data, one for metadata records). After every queued clone's
-     * copies are recorded, dispatches a single batched patch shader
-     * pass that walks a flat `(record_index, address_delta)` table
-     * — N clones → 1 patch dispatch, total threads = sum of clone
-     * meshlet counts.
-     *
-     * Idempotent and cheap when nothing's queued.
-     *
-     * @param {ShadeGPUCommandContext} cmd_ctx
-     */
-    update(cmd_ctx) {
-        const pending = this.#pending_clones;
-        if (pending.length === 0) {
-            return;
-        }
-
-        const data_buffer = this.#meshlet_data_buffer;
-        const metadata_buffer = this.#meshlet_metadata_buffer;
-        const metadata_stride = MESHLET_METADATA_STRUCT.aligned_size;
-        const metadata_stride_words = metadata_stride / 4;
-
-        // WebGPU forbids `copyBufferToBuffer` with src === dst even when
-        // ranges don't overlap (the validation check is buffer-identity,
-        // not range-overlap), so we relocate via a small compute-shader
-        // memcpy bound to the buffer once as `read_write`. Two dispatches
-        // — one over the data-buffer regions, one over the metadata-buffer
-        // regions — handle every queued clone in a batched pass.
-        //
-        // Region (src, dst) ranges are non-overlapping by construction:
-        // the OffsetAllocator hands out fresh disjoint slices, so the
-        // memcpy shader can safely skip the per-thread overlap check.
-        const region_size_bytes = BUFFER_INTRA_COPY_REGION_STRUCT.aligned_size;
-
-        const data_regions_array = new Uint32Array(pending.length * (region_size_bytes / 4));
-        const metadata_regions_array = new Uint32Array(pending.length * (region_size_bytes / 4));
-
-        let total_records = 0;
-        for (let i = 0; i < pending.length; i++) {
-            const { source, clone } = pending[i];
-
-            // Region struct is just three u32s — write directly. Order
-            // matches the field declaration: src_offset, dst_offset,
-            // word_count.
-            const region_words = i * 3;
-            data_regions_array[region_words]     = source.data.offset;
-            data_regions_array[region_words + 1] = clone.data.offset;
-            data_regions_array[region_words + 2] = clone.data_size;
-
-            metadata_regions_array[region_words]     = source.metadata.offset * metadata_stride_words;
-            metadata_regions_array[region_words + 1] = clone.metadata.offset * metadata_stride_words;
-            metadata_regions_array[region_words + 2] = clone.meshlet_count * metadata_stride_words;
-
-            total_records += clone.meshlet_count;
-        }
-
-        const data_regions_buffer = cmd_ctx.allocateTransientBufferAndLoad(
-            data_regions_array.buffer,
-            GPUBufferUsage.STORAGE,
-        );
-        shader_buffer_intra_copy_regions.dispatch({
-            encoder: cmd_ctx,
-            group_count_x: pending.length,
-            bindings: {
-                buffer: data_buffer,
-                regions: data_regions_buffer,
-            },
-        });
-
-        const metadata_regions_buffer = cmd_ctx.allocateTransientBufferAndLoad(
-            metadata_regions_array.buffer,
-            GPUBufferUsage.STORAGE,
-        );
-        shader_buffer_intra_copy_regions.dispatch({
-            encoder: cmd_ctx,
-            group_count_x: pending.length,
-            bindings: {
-                buffer: metadata_buffer,
-                regions: metadata_regions_buffer,
-            },
-        });
-
-        // Build the flat (record_index, address_delta) table. One pair
-        // per cloned meshlet record. Uploaded as a transient storage
-        // buffer the patch shader binds for one dispatch.
-        const patches_array = new Uint32Array(total_records * 2);
-        let p = 0;
-        for (let i = 0; i < pending.length; i++) {
-            const { source, clone } = pending[i];
-
-            // Address delta is in u32 word units. When the clone's offset
-            // is below the source's, the unsigned subtraction wraps — the
-            // patch shader does the matching wrapping add, so the final
-            // per-record `address` lands at the right absolute word offset
-            // either way.
-            const address_delta = (clone.data.offset - source.data.offset) >>> 0;
-
-            for (let m = 0; m < clone.meshlet_count; m++) {
-                patches_array[p++] = clone.metadata.offset + m;
-                patches_array[p++] = address_delta;
-            }
-        }
-
-        const patches_buffer = cmd_ctx.allocateTransientBufferAndLoad(
-            patches_array.buffer,
-            GPUBufferUsage.STORAGE,
-        );
-
-        // patch_count uniform is a bare u32 — see
-        // shader_meshlet_metadata_address_patch.
-        const patch_count_buffer = cmd_ctx.allocateTransientValueBuffer(
-            u32,
-            total_records,
-        );
-
-        shader_meshlet_metadata_address_patch.dispatchLinear({
-            encoder: cmd_ctx,
-            element_count: total_records,
-            bindings: {
-                meshlet_metadata: metadata_buffer,
-                patches: patches_buffer,
-                patch_count: patch_count_buffer,
-            },
-        });
-
-        pending.length = 0;
-    }
-
-    destroy() {
-        this.#meshlet_data_buffer.destroy();
-        this.#meshlet_metadata_buffer.destroy();
-    }
-
-    /**
-     *
-     * @param {MeshletBatch} batch
-     * @returns {MeshletBatchAllocationRecord}
-     */
-    add_batch(batch) {
-        assert.defined(batch, 'batch');
-        assert.notNull(batch, 'batch');
-        assert.equal(batch.isMeshletBatch, true, 'batch.isMeshletBatch !== true');
-
-        const record = this.#allocate_for_batch(batch);
-
-        // plonk data
-        const data_buffer = batch.data_buffer;
-        const data_allocation = record.data;
-
-        this.#device.queue.writeBuffer(
-            this.#meshlet_data_buffer,
-            data_allocation.offset << 2, // allocator works in words of 4 bytes
-            data_buffer
-        );
-
-        // Write Metadata (Patch & Upload)
-        this.#write_patched_metadata(
-            record.metadata_buffer_original,
-            record.meshlet_count,
-            record.data.offset,
-            record.metadata.offset,
-            this.#meshlet_metadata_buffer
-        );
-
-        return record;
-    }
-
-    async debug_dump_metadata() {
-        const device = this.#device;
-
-        return await inspect_gpu_buffer_typed({
-            buffer: this.#meshlet_metadata_buffer,
-            device,
-            type: MESHLET_METADATA_STRUCT,
-            count: Math.floor(this.#meshlet_metadata_buffer.size / MESHLET_METADATA_STRUCT.aligned_size),
-        });
-    }
-
-    get gpu_memory_usage_occupied() {
-        let result = 0;
-
-        for (const record of this.#records) {
-            result += record.data_size * 4;
-        }
-
-        return result;
-    }
-
-    get gpu_memory_usage() {
-        let result = 0;
-
-        if (this.#meshlet_data_buffer) {
-            result += this.#meshlet_data_buffer.size;
-        }
-
-        if (this.#meshlet_metadata_buffer) {
-            result += this.#meshlet_metadata_buffer.size;
-        }
-
-        return result;
-    }
+import { assert } from "../../../../core/assert.js";
+import { ALLOCATOR_NO_SPACE, OffsetAllocator } from "../../../../core/binary/allocator/OffsetAllocator.js";
+import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { platform_compute_endianness } from "../../../../core/binary/platform_compute_endianness.js";
+import Signal from "../../../../core/events/signal/Signal.js";
+import { MEGABYTE } from "../../../../core/science/units/memory/MEGABYTE.js";
+import { read_wgsl_type_value } from "../../shader/type/serde/read_gpu_typed_buffer.js";
+import { write_wgsl_type_value } from "../../shader/type/serde/write_gpu_typed_buffer.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { inspect_gpu_buffer_typed } from "../../buffer/inspect_gpu_buffer_typed.js";
+import {
+    BUFFER_INTRA_COPY_REGION_STRUCT,
+    shader_buffer_intra_copy_regions
+} from "../../buffer/util/shader_buffer_intra_copy_regions.js";
+import { MESHLET_METADATA_STRUCT } from "./encoding/MESHLET_METADATA_STRUCT.js";
+import { shader_meshlet_metadata_address_patch } from "./shader_meshlet_metadata_address_patch.js";
+
+/**
+ * In meshlets
+ * @type {number}
+ */
+const DEFAULT_METADATA_CAPACITY = 128 * 1024;
+
+/**
+ * In bytes
+ * @type {number}
+ */
+const DEFAULT_DATA_CAPACITY = 32 * MEGABYTE;
+
+class MeshletBatchAllocationRecord {
+    /**
+     * @type {Allocation}
+     */
+    metadata
+    /**
+     * @type {Allocation}
+     */
+    data
+
+    /**
+     * Number of words
+     * @type {number}
+     */
+    data_size = 0;
+
+    /**
+     * Meshlet count
+     * @type {number}
+     */
+    meshlet_count = 0;
+
+    /**
+     *
+     * @type {ArrayBuffer}
+     */
+    metadata_buffer_original;
+
+    /**
+     *
+     * @type {Signal<>}
+     */
+    changed = new Signal()
+}
+
+export class GPUMeshletManager {
+
+    /**
+     * Allocation sizes in words of 4 bytes
+     * @type {OffsetAllocator}
+     */
+    #allocator_data = new OffsetAllocator(1024);
+
+    /**
+     * Allocation sizes in meshlets
+     * @type {OffsetAllocator}
+     */
+    #allocator_metadata = new OffsetAllocator(1024);
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #meshlet_data_buffer;
+
+    get buffer_data() {
+        return this.#meshlet_data_buffer;
+    }
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #meshlet_metadata_buffer;
+
+    get buffer_metadata() {
+        return this.#meshlet_metadata_buffer;
+    }
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     *
+     * @type {number}
+     */
+    #deallocations_since_last_rebuild = 0;
+
+    /**
+     *
+     * @type {MeshletBatchAllocationRecord[]}
+     */
+    #records = [];
+
+    /**
+     * Queue of GPU-side clones that have been allocated but not yet
+     * copied + patched. Drained by {@link update}. Each entry holds the
+     * minimum bookkeeping needed to issue two `copyBufferToBuffer`
+     * commands and N `(record_index, address_delta)` patch entries.
+     *
+     * Entries name the two records, not the addresses they held when the
+     * clone was queued: a {@link compact} or {@link grow} in between
+     * migrates both, and {@link update} reads where they ended up. What
+     * an entry does require is that neither record is handed back to
+     * {@link remove_batch} before the flush.
+     *
+     * @type {{
+     *   source: MeshletBatchAllocationRecord,
+     *   clone: MeshletBatchAllocationRecord,
+     * }[]}
+     */
+    #pending_clones = [];
+
+    /**
+     *
+     * @param {GPUDevice} device
+     * @param {number} [initial_data_capacity] in bytes
+     * @param {number} [initial_metadata_capacity] in meshlets
+     */
+    constructor({
+                    device,
+                    initial_data_capacity = DEFAULT_DATA_CAPACITY,
+                    initial_metadata_capacity = DEFAULT_METADATA_CAPACITY,
+                }) {
+        assert.defined(device, 'device');
+
+        assert.isNonNegativeInteger(initial_data_capacity, 'initial_data_capacity');
+        assert.isNonNegativeInteger(initial_metadata_capacity, 'initial_metadata_capacity');
+
+        assert.greaterThan(initial_data_capacity, 0, 'initial_data_capacity');
+        assert.greaterThan(initial_metadata_capacity, 0, 'initial_data_capacity');
+
+        this.#device = device;
+
+        const data_buffer_size_words = Math.ceil(initial_data_capacity / 4);
+
+        // TODO manage max-allocations as well
+        this.#allocator_data = new OffsetAllocator(data_buffer_size_words);
+        this.#allocator_metadata = new OffsetAllocator(initial_metadata_capacity);
+
+        this.#meshlet_data_buffer = device.createBuffer({
+            label: 'GPUMeshletManager/data',
+            size: data_buffer_size_words * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
+        });
+
+        this.#meshlet_metadata_buffer = device.createBuffer({
+            label: 'GPUMeshletManager/metadata',
+            size: initial_metadata_capacity * MESHLET_METADATA_STRUCT.aligned_size,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
+        });
+
+    }
+
+    compact() {
+        this.#rebuild(
+            this.#meshlet_data_buffer.size >>> 2,
+            Math.ceil(this.#meshlet_metadata_buffer.size / MESHLET_METADATA_STRUCT.aligned_size)
+        );
+    }
+
+    /**
+     *
+     * @param {number} extra_data_size in words (4 bytes)
+     * @param {number} extra_metadata_size in metadata elements
+     */
+    grow(extra_data_size, extra_metadata_size) {
+        assert.isNonNegativeInteger(extra_data_size, 'extra_data_size');
+        assert.isNonNegativeInteger(extra_metadata_size, 'extra_metadata_size');
+
+        if (extra_data_size === 0 && extra_metadata_size === 0) {
+            // nothing to do
+            return;
+        }
+
+        const current_data_buffer_size_bytes = this.#meshlet_data_buffer.size;
+        const current_metadata_buffer_size = this.#meshlet_metadata_buffer.size;
+
+        const current_buffer_size_words = current_data_buffer_size_bytes >> 2;
+        const current_metadata_buffer_size_elements = Math.ceil(current_metadata_buffer_size / MESHLET_METADATA_STRUCT.aligned_size);
+
+        const DATA_GROWTH_STEP = 16 * 1024;
+        const METADATA_GROWTH_STEP = 256;
+        const GROWTH_MULTIPLIER = 1.25;
+
+        let new_data_size;
+        if (extra_data_size === 0) {
+            new_data_size = current_buffer_size_words;
+        } else {
+            // grow
+            new_data_size = Math.max(
+                current_buffer_size_words + extra_data_size,
+                current_buffer_size_words + DATA_GROWTH_STEP,
+                Math.ceil(current_buffer_size_words * GROWTH_MULTIPLIER)
+            );
+        }
+
+        let new_metadata_size;
+        if (extra_metadata_size === 0) {
+            new_metadata_size = current_metadata_buffer_size_elements;
+        } else {
+            // grow
+            new_metadata_size = Math.max(
+                current_metadata_buffer_size_elements + extra_metadata_size,
+                current_metadata_buffer_size_elements + METADATA_GROWTH_STEP,
+                current_metadata_buffer_size_elements * GROWTH_MULTIPLIER
+            );
+        }
+
+        this.#rebuild(
+            new_data_size,
+            new_metadata_size
+        );
+    }
+
+    /**
+     * Helper to patch pointers in metadata and upload to GPU
+     * @param {ArrayBuffer} source_array_buffer
+     * @param {number} meshlet_count
+     * @param {number} data_offset_words
+     * @param {number} metadata_offset_index
+     * @param {GPUBuffer} target_buffer
+     */
+    #write_patched_metadata(
+        source_array_buffer,
+        meshlet_count,
+        data_offset_words,
+        metadata_offset_index,
+        target_buffer
+    ) {
+        const temp_writer = BinaryBuffer.fromEndianness(platform_compute_endianness());
+        temp_writer.setCapacity(meshlet_count * MESHLET_METADATA_STRUCT.size); // pre-allocate to avoid resizing
+
+        const source_reader = BinaryBuffer.fromArrayBuffer(source_array_buffer);
+        source_reader.endianness = platform_compute_endianness();
+
+        // Iterate over meshlets in the batch, patch the address, and write to temp buffer
+        for (let i = 0; i < meshlet_count; i++) {
+            const header = read_wgsl_type_value(source_reader, MESHLET_METADATA_STRUCT);
+
+            // PATCH: Add the allocation offset to the relative address
+            header.address += data_offset_words;
+
+            write_wgsl_type_value(header, temp_writer, MESHLET_METADATA_STRUCT);
+        }
+
+        // Upload
+        this.#device.queue.writeBuffer(
+            target_buffer,
+            metadata_offset_index * MESHLET_METADATA_STRUCT.aligned_size,
+            temp_writer.data,
+            0,
+            meshlet_count * MESHLET_METADATA_STRUCT.aligned_size
+        );
+    }
+
+    /**
+     *
+     * @param {number} new_data_size
+     * @param {number} new_metadata_size
+     */
+    #rebuild(
+        new_data_size,
+        new_metadata_size
+    ) {
+
+        assert.isNonNegativeInteger(new_data_size, 'new_data_size');
+        assert.isNonNegativeInteger(new_metadata_size, 'new_metadata_size');
+
+        // Outstanding clone work survives this. A queued clone names its
+        // source and destination records, both of which are migrated
+        // below, and the flush reads their addresses when it runs — so a
+        // rebuild moves the copy rather than invalidating it.
+
+        // console.warn('GPUMeshletManager/rebuild');
+
+        const device = this.#device;
+
+        const records = this.#records;
+        const record_count = records.length;
+        const new_allocator_data = new OffsetAllocator(
+            new_data_size,
+            Math.max(record_count * 2, 128 * 1024)
+        );
+
+        const old_buffer_data = this.#meshlet_data_buffer;
+        const new_buffer_data = device.createBuffer({
+            label: old_buffer_data.label,
+            usage: old_buffer_data.usage,
+            size: new_data_size * 4,
+        });
+
+        const new_allocator_metadata = new OffsetAllocator(
+            new_metadata_size,
+            Math.max(record_count * 2, 128 * 1024)
+        );
+
+        const old_buffer_metadata = this.#meshlet_metadata_buffer;
+        const new_buffer_metadata = device.createBuffer({
+            label: old_buffer_metadata.label,
+            usage: old_buffer_metadata.usage,
+            size: new_metadata_size * MESHLET_METADATA_STRUCT.aligned_size,
+        });
+
+        const encoder = device.createCommandEncoder({
+            label: "GPUMeshletManager/rebuild",
+        });
+
+        const moved_records = [];
+
+        // move data
+        for (let i = 0; i < record_count; i++) {
+            const record = records[i];
+
+            const new_allocation_data = new_allocator_data.allocate(record.data_size);
+            const new_allocation_metadata = new_allocator_metadata.allocate(record.meshlet_count);
+
+            assert.notEqual(new_allocation_data.offset, ALLOCATOR_NO_SPACE);
+            assert.notEqual(new_allocation_metadata.offset, ALLOCATOR_NO_SPACE);
+
+            encoder.copyBufferToBuffer(
+                old_buffer_data, record.data.offset * 4,
+                new_buffer_data, new_allocation_data.offset * 4,
+                record.data_size * 4
+            );
+
+            const metadata_record_moved = record.data.offset !== new_allocation_data.offset;
+
+            // B. Patch Metadata (CPU -> GPU Write)
+            // Metadata contains `address` which points to the Data offset.
+            // Since the Data offset changed, we must re-calculate and upload the metadata.
+            // We reuse the helper to avoid code duplication.
+            this.#write_patched_metadata(
+                record.metadata_buffer_original,
+                record.meshlet_count,
+                new_allocation_data.offset, // The NEW data offset
+                new_allocation_metadata.offset, // The NEW metadata location
+                new_buffer_metadata
+            );
+
+            // update record
+            record.data = new_allocation_data;
+            record.metadata = new_allocation_metadata;
+
+            if (metadata_record_moved) {
+                moved_records.push(record);
+            }
+        }
+
+        for (const record of moved_records) {
+            // notify
+            record.changed.send0();
+        }
+
+        const command_buffer = encoder.finish();
+
+        device.queue.submit([command_buffer]);
+
+        old_buffer_data.destroy();
+        old_buffer_metadata.destroy();
+
+        this.#meshlet_data_buffer = new_buffer_data;
+        this.#meshlet_metadata_buffer = new_buffer_metadata;
+
+        this.#allocator_data = new_allocator_data;
+        this.#allocator_metadata = new_allocator_metadata;
+
+        // reset count
+        this.#deallocations_since_last_rebuild = 0;
+    }
+
+    /**
+     * Allocate `data_size_words` in the data buffer and `meshlet_count`
+     * in the metadata buffer, retrying with compact-then-grow on failure.
+     * Throws if the third attempt still can't satisfy both. The two
+     * allocations are kept in lockstep — partial successes are released
+     * before retrying so we never leak.
+     *
+     * Compaction triggers a full {@link #rebuild} which migrates every
+     * existing allocation to a new buffer pair. Queued clone work is
+     * carried through it — {@link #pending_clones} names records, not
+     * addresses — so an allocation made while a clone is pending is safe.
+     *
+     * @param {number} data_size_words
+     * @param {number} meshlet_count
+     * @returns {{data: Allocation, metadata: Allocation}}
+     */
+    #allocate_data_and_metadata(data_size_words, meshlet_count) {
+        let data_allocation;
+        let metadata_allocation;
+
+        for (let try_index = 0; try_index < 3; try_index++) {
+
+            data_allocation = this.#allocator_data.allocate(data_size_words);
+            metadata_allocation = this.#allocator_metadata.allocate(meshlet_count);
+
+            const data_ok = data_allocation.offset !== ALLOCATOR_NO_SPACE;
+            const metadata_ok = metadata_allocation.offset !== ALLOCATOR_NO_SPACE;
+
+            if (data_ok && metadata_ok) {
+                break;
+            }
+
+            // release partial allocation
+            if (data_ok) {
+                this.#allocator_data.free(data_allocation);
+
+                data_allocation.offset = ALLOCATOR_NO_SPACE;
+                data_allocation.metadata = ALLOCATOR_NO_SPACE;
+            }
+            if (metadata_ok) {
+                this.#allocator_metadata.free(metadata_allocation);
+
+                metadata_allocation.offset = ALLOCATOR_NO_SPACE;
+                metadata_allocation.metadata = ALLOCATOR_NO_SPACE;
+            }
+
+            if (this.#deallocations_since_last_rebuild > 0) {
+                // try compaction
+                this.compact();
+                continue;
+            }
+
+            let grow_data_size = data_ok ? 0 : data_size_words;
+            let grow_metadata_size = metadata_ok ? 0 : meshlet_count;
+
+            this.grow(grow_data_size, grow_metadata_size);
+
+        }
+
+        if (data_allocation.offset === ALLOCATOR_NO_SPACE || metadata_allocation.offset === ALLOCATOR_NO_SPACE) {
+            throw new Error('Failed to allocate GPU memory for meshlet batch');
+        }
+
+        return { data: data_allocation, metadata: metadata_allocation };
+    }
+
+    /**
+     *
+     * @param {MeshletBatch} batch
+     * @returns {MeshletBatchAllocationRecord}
+     */
+    #allocate_for_batch(batch) {
+        assert.defined(batch, 'batch');
+
+        const data_buffer = batch.data_buffer;
+
+        const data_size_words = Math.ceil(data_buffer.byteLength / 4);
+
+        const meshlet_count = batch.count;
+
+        const { data, metadata } = this.#allocate_data_and_metadata(data_size_words, meshlet_count);
+
+        const record = new MeshletBatchAllocationRecord();
+
+        record.data = data;
+        record.metadata = metadata;
+
+        record.meshlet_count = meshlet_count;
+        record.data_size = data_size_words;
+
+        record.metadata_buffer_original = batch.metadata_buffer;
+
+        this.#records.push(record);
+
+        return record;
+    }
+
+    /**
+     * Release a batch allocation back to the data and metadata allocators. The GPU bytes are
+     * not cleared — the freed slices are reclaimed lazily by the next {@link compact} (a
+     * deallocation bumps the compaction counter the allocator consults under pressure).
+     * Other batches' allocations are unaffected (the OffsetAllocator frees disjoint slices),
+     * so callers only need to ensure nothing still references this batch's metadata rows
+     * (the geometry table rebuild in {@link GPUGeometryManager} handles that).
+     *
+     * @param {MeshletBatchAllocationRecord} record a record returned by {@link add_batch} or
+     *        {@link clone_batch_allocation}
+     * @returns {boolean} true if the record was owned and freed
+     */
+    remove_batch(record) {
+        assert.defined(record, 'record');
+
+        const index = this.#records.indexOf(record);
+        if (index === -1) {
+            return false;
+        }
+
+        this.#allocator_data.free(record.data);
+        this.#allocator_metadata.free(record.metadata);
+
+        this.#records.splice(index, 1);
+        this.#deallocations_since_last_rebuild++;
+
+        return true;
+    }
+
+    /**
+     * Allocate a fresh (data, metadata) pair sized to mirror `source`,
+     * and queue a GPU-side clone: the source's data and metadata are
+     * copied into the new ranges via `copyBufferToBuffer`, then a
+     * compute pass patches the cloned metadata records' `address`
+     * fields to point at the new data range. Both the copies and the
+     * patch dispatch land when the host next calls
+     * {@link update update(cmd_ctx)}.
+     *
+     * The returned record can be wired into the geometry table
+     * immediately — its `data.offset` and `metadata.offset` are valid
+     * the moment this call returns. The GPU bytes at those addresses
+     * just aren't populated yet; downstream passes that consume the
+     * clone must run after the next `update`. Those addresses may still
+     * move before the flush, which is why nothing outside the record is
+     * allowed to remember them.
+     *
+     * Sharing the source's `metadata_buffer_original` lets a future
+     * compaction patch the clone's metadata from the same un-patched
+     * CPU bytes the source uses — the post-patch state on the GPU is
+     * identical to the source aside from the data offset.
+     *
+     * @param {MeshletBatchAllocationRecord} source
+     * @returns {MeshletBatchAllocationRecord}
+     */
+    clone_batch_allocation(source) {
+        assert.defined(source, 'source');
+        assert.greaterThan(source.meshlet_count, 0, 'source.meshlet_count');
+
+        const { data, metadata } = this.#allocate_data_and_metadata(source.data_size, source.meshlet_count);
+
+        const record = new MeshletBatchAllocationRecord();
+
+        record.data = data;
+        record.metadata = metadata;
+
+        record.meshlet_count = source.meshlet_count;
+        record.data_size = source.data_size;
+
+        // Share the un-patched CPU bytes so a future compact rewrites
+        // the clone's metadata correctly under its new data offset.
+        record.metadata_buffer_original = source.metadata_buffer_original;
+
+        this.#records.push(record);
+
+        // The queue names the two records rather than the addresses they
+        // hold right now. Both are in `#records`, so a rebuild between
+        // this call and the flush moves them and the flush still reads
+        // where they went — which is what lets a clone be queued in the
+        // same frame as the growth another geometry's arrival forces.
+        this.#pending_clones.push({ source, clone: record });
+
+        return record;
+    }
+
+    /**
+     * Flush any pending clone work into `cmd_ctx`. For each queued
+     * clone, emits two `copyBufferToBuffer` commands (one for vertex
+     * data, one for metadata records). After every queued clone's
+     * copies are recorded, dispatches a single batched patch shader
+     * pass that walks a flat `(record_index, address_delta)` table
+     * — N clones → 1 patch dispatch, total threads = sum of clone
+     * meshlet counts.
+     *
+     * Idempotent and cheap when nothing's queued.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     */
+    update(cmd_ctx) {
+        const pending = this.#pending_clones;
+        if (pending.length === 0) {
+            return;
+        }
+
+        const data_buffer = this.#meshlet_data_buffer;
+        const metadata_buffer = this.#meshlet_metadata_buffer;
+        const metadata_stride = MESHLET_METADATA_STRUCT.aligned_size;
+        const metadata_stride_words = metadata_stride / 4;
+
+        // WebGPU forbids `copyBufferToBuffer` with src === dst even when
+        // ranges don't overlap (the validation check is buffer-identity,
+        // not range-overlap), so we relocate via a small compute-shader
+        // memcpy bound to the buffer once as `read_write`. Two dispatches
+        // — one over the data-buffer regions, one over the metadata-buffer
+        // regions — handle every queued clone in a batched pass.
+        //
+        // Region (src, dst) ranges are non-overlapping by construction:
+        // the OffsetAllocator hands out fresh disjoint slices, so the
+        // memcpy shader can safely skip the per-thread overlap check.
+        const region_size_bytes = BUFFER_INTRA_COPY_REGION_STRUCT.aligned_size;
+
+        const data_regions_array = new Uint32Array(pending.length * (region_size_bytes / 4));
+        const metadata_regions_array = new Uint32Array(pending.length * (region_size_bytes / 4));
+
+        let total_records = 0;
+        for (let i = 0; i < pending.length; i++) {
+            const { source, clone } = pending[i];
+
+            // Region struct is just three u32s — write directly. Order
+            // matches the field declaration: src_offset, dst_offset,
+            // word_count.
+            const region_words = i * 3;
+            data_regions_array[region_words]     = source.data.offset;
+            data_regions_array[region_words + 1] = clone.data.offset;
+            data_regions_array[region_words + 2] = clone.data_size;
+
+            metadata_regions_array[region_words]     = source.metadata.offset * metadata_stride_words;
+            metadata_regions_array[region_words + 1] = clone.metadata.offset * metadata_stride_words;
+            metadata_regions_array[region_words + 2] = clone.meshlet_count * metadata_stride_words;
+
+            total_records += clone.meshlet_count;
+        }
+
+        const data_regions_buffer = cmd_ctx.allocateTransientBufferAndLoad(
+            data_regions_array.buffer,
+            GPUBufferUsage.STORAGE,
+        );
+        shader_buffer_intra_copy_regions.dispatch({
+            encoder: cmd_ctx,
+            group_count_x: pending.length,
+            bindings: {
+                buffer: data_buffer,
+                regions: data_regions_buffer,
+            },
+        });
+
+        const metadata_regions_buffer = cmd_ctx.allocateTransientBufferAndLoad(
+            metadata_regions_array.buffer,
+            GPUBufferUsage.STORAGE,
+        );
+        shader_buffer_intra_copy_regions.dispatch({
+            encoder: cmd_ctx,
+            group_count_x: pending.length,
+            bindings: {
+                buffer: metadata_buffer,
+                regions: metadata_regions_buffer,
+            },
+        });
+
+        // Build the flat (record_index, address_delta) table. One pair
+        // per cloned meshlet record. Uploaded as a transient storage
+        // buffer the patch shader binds for one dispatch.
+        const patches_array = new Uint32Array(total_records * 2);
+        let p = 0;
+        for (let i = 0; i < pending.length; i++) {
+            const { source, clone } = pending[i];
+
+            // Address delta is in u32 word units. When the clone's offset
+            // is below the source's, the unsigned subtraction wraps — the
+            // patch shader does the matching wrapping add, so the final
+            // per-record `address` lands at the right absolute word offset
+            // either way.
+            const address_delta = (clone.data.offset - source.data.offset) >>> 0;
+
+            for (let m = 0; m < clone.meshlet_count; m++) {
+                patches_array[p++] = clone.metadata.offset + m;
+                patches_array[p++] = address_delta;
+            }
+        }
+
+        const patches_buffer = cmd_ctx.allocateTransientBufferAndLoad(
+            patches_array.buffer,
+            GPUBufferUsage.STORAGE,
+        );
+
+        // patch_count uniform is a bare u32 — see
+        // shader_meshlet_metadata_address_patch.
+        const patch_count_buffer = cmd_ctx.allocateTransientValueBuffer(
+            u32,
+            total_records,
+        );
+
+        shader_meshlet_metadata_address_patch.dispatchThreads({
+            encoder: cmd_ctx,
+            thread_count_x: total_records,
+            bindings: {
+                meshlet_metadata: metadata_buffer,
+                patches: patches_buffer,
+                patch_count: patch_count_buffer,
+            },
+        });
+
+        pending.length = 0;
+    }
+
+    destroy() {
+        this.#meshlet_data_buffer.destroy();
+        this.#meshlet_metadata_buffer.destroy();
+    }
+
+    /**
+     *
+     * @param {MeshletBatch} batch
+     * @returns {MeshletBatchAllocationRecord}
+     */
+    add_batch(batch) {
+        assert.defined(batch, 'batch');
+        assert.notNull(batch, 'batch');
+        assert.equal(batch.isMeshletBatch, true, 'batch.isMeshletBatch !== true');
+
+        const record = this.#allocate_for_batch(batch);
+
+        // plonk data
+        const data_buffer = batch.data_buffer;
+        const data_allocation = record.data;
+
+        this.#device.queue.writeBuffer(
+            this.#meshlet_data_buffer,
+            data_allocation.offset << 2, // allocator works in words of 4 bytes
+            data_buffer
+        );
+
+        // Write Metadata (Patch & Upload)
+        this.#write_patched_metadata(
+            record.metadata_buffer_original,
+            record.meshlet_count,
+            record.data.offset,
+            record.metadata.offset,
+            this.#meshlet_metadata_buffer
+        );
+
+        return record;
+    }
+
+    async debug_dump_metadata() {
+        const device = this.#device;
+
+        return await inspect_gpu_buffer_typed({
+            buffer: this.#meshlet_metadata_buffer,
+            device,
+            type: MESHLET_METADATA_STRUCT,
+            count: Math.floor(this.#meshlet_metadata_buffer.size / MESHLET_METADATA_STRUCT.aligned_size),
+        });
+    }
+
+    get gpu_memory_usage_occupied() {
+        let result = 0;
+
+        for (const record of this.#records) {
+            result += record.data_size * 4;
+        }
+
+        return result;
+    }
+
+    get gpu_memory_usage() {
+        let result = 0;
+
+        if (this.#meshlet_data_buffer) {
+            result += this.#meshlet_data_buffer.size;
+        }
+
+        if (this.#meshlet_metadata_buffer) {
+            result += this.#meshlet_metadata_buffer.size;
+        }
+
+        return result;
+    }
 }