@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/renderer/geometry/GPUGeometryManager.js

@@ -1,497 +1,591 @@
-import { assert } from "../../../core/assert.js";
-import { BufferDescriptor } from "../../descriptor/buffer/BufferDescriptor.js";
-import { write_gpu_typed_buffer } from "../shader/type/serde/write_gpu_typed_buffer.js";
-import { inspect_gpu_buffer_typed } from "../buffer/inspect_gpu_buffer_typed.js";
-import { GPUGeometryBVHManager } from "./bvh/GPUGeometryBVHManager.js";
-import { GEOMETRY_METADATA_STRUCT } from "./GEOMETRY_METADATA_STRUCT.js";
-import { GPUGeometryMetadata } from "./GPUGeometryMetadata.js";
-import { GPUMeshletManager } from "./meshlet/GPUMeshletManager.js";
-
-const WORDS_PER_MEGABYTE = 1024 * 1024 / 4;
-
-/**
- * Manages geometry for indirect draw
- * Context represents a collection of geometries that are resident on the GPU and are ready to be used in indirect draw to draw entire scenes
- * @see https://gpuweb.github.io/gpuweb/#dom-gpurendercommandsmixin-drawindexedindirect
- */
-export class GPUGeometryManager {
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
-    /**
-     * TODO make use of {@link GPUTypedTable} instead
-     * @type {GPUBuffer|null}
-     */
-    buffer_metadata = null;
-
-    /**
-     *
-     * @type {Map<MeshletGeometry, GPUGeometryMetadata>}
-     */
-    #geometries = new Map();
-
-    /**
-     * Per-instance geometry clones — same source as a regular registered
-     * geometry, but with their own GPU vertex/metadata range so a
-     * skinning pass can deform them independently. Stored separately
-     * from {@link #geometries} because multiple clones can share one
-     * source `MeshletGeometry`, which the Map's by-object keying can't
-     * represent.
-     *
-     * Each entry's `geometry` field still points at the source's CPU
-     * `MeshletGeometry` (so bounds and index_count come from the same
-     * place) but `meshlets` is a fresh
-     * {@link MeshletBatchAllocationRecord} produced by
-     * {@link GPUMeshletManager#clone_batch_allocation}. The two
-     * collections share the same `index` space — `__last_geometry_index`
-     * advances for both.
-     *
-     * @type {GPUGeometryMetadata[]}
-     */
-    #clone_metadata = [];
-
-    /**
-     * Do not modify. The data is managed by this class, access in read-only mode.
-     * @return {Map<Readonly<MeshletGeometry>, Readonly<GPUGeometryMetadata>>}
-     */
-    get managed() {
-        return this.#geometries;
-    }
-
-    /**
-     *
-     * @type {number}
-     * @private
-     */
-    __last_geometry_index = 0;
-
-    /**
-     *
-     * @type {boolean}
-     * @private
-     */
-    __needs_update = true;
-
-    /**
-     * @type {GPUMeshletManager}
-     */
-    #meshlets;
-
-    /**
-     *
-     * @return {GPUMeshletManager}
-     */
-    get meshlets() {
-        return this.#meshlets;
-    }
-
-    /**
-     * To support RTX, this needs to be enabled
-     * @type {boolean}
-     */
-    #enable_bvh = true;
-
-
-    /**
-     * Bottom-level acceleration structure (BVH for ray casting)
-     * @type {GPUGeometryBVHManager}
-     */
-    #blas
-
-    /**
-     *
-     * @returns {GPUGeometryBVHManager}
-     */
-    get blas() {
-        return this.#blas;
-    }
-
-
-    /**
-     *
-     * @return {GPUGeometrySDFManager}
-     */
-    get sdf() {
-        throw new Error("Not implemented");
-    }
-
-    /**
-     *
-     * @return {number} in bytes
-     */
-    get gpu_memory_usage() {
-        let r = 0;
-
-
-        if (this.buffer_metadata !== null) {
-            r += this.buffer_metadata.size;
-        }
-
-        if (this.#meshlets) {
-            r += this.#meshlets.gpu_memory_usage;
-        }
-
-        if (this.#blas) {
-            r += this.#blas.gpu_memory_usage;
-        }
-
-        return r;
-    }
-
-    /**
-     *
-     * @param {GPUDevice} device
-     */
-    constructor(device) {
-        this.#device = device;
-        this.#blas = new GPUGeometryBVHManager(device);
-        this.#meshlets = new GPUMeshletManager({ device });
-
-        this.buffer_metadata = device.createBuffer(BufferDescriptor.fromJSON({
-            label: "GPUGeometryContext/metadata",
-            size: 0,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
-        }));
-    }
-
-    /**
-     *
-     * @param {GPUGeometryMetadata} geometry
-     * @return {number}
-     */
-    getAddress(geometry) {
-        const metadata = this.#geometries.get(geometry);
-
-        return metadata.index;
-    }
-
-    /**
-     *
-     * @param {MeshletGeometry} geometry
-     * @return {boolean}
-     */
-    has(geometry) {
-        return this.#geometries.has(geometry);
-    }
-
-
-    /**
-     *
-     * @param {MeshletGeometry} geometry
-     * @returns {boolean}
-     */
-    add(geometry) {
-        assert.defined(geometry, 'geometry');
-        assert.equal(geometry.isMeshletGeometry, true, 'geometry.isMeshletGeometry !== true');
-
-        if (this.has(geometry)) {
-            return false;
-        }
-
-        const metadata = new GPUGeometryMetadata();
-
-        metadata.geometry = geometry;
-
-        metadata.allocated = false;
-        metadata.index = this.__last_geometry_index++;
-
-        const meshlets = geometry.meshlets;
-
-        metadata.meshlets = this.#meshlets.add_batch(meshlets);
-
-        // watch for data migration
-        metadata.meshlets.changed.add(() => {
-
-            // TODO need to handle this properly
-
-            console.warn('Meshlet GPU address changed.')
-
-        });
-
-        this.#geometries.set(geometry, metadata);
-
-        this.__needs_update = true;
-
-        // console.log(geometry, this.#meshlets.obtain(geometry));
-
-        return true;
-    }
-
-    /**
-     * Register a per-instance clone of `source_geometry`. The clone is
-     * a brand-new GPU geometry id that points at a fresh vertex /
-     * metadata range (allocated via
-     * {@link GPUMeshletManager#clone_batch_allocation}); the actual
-     * GPU-side memcpy + address-patch happens lazily on the next
-     * {@link update update(command_ctx)}.
-     *
-     * Use this when you need an instance to render against a *different
-     * copy* of the same mesh data — the canonical case being a
-     * `SkinnedMesh` whose vertex region needs to be deformed each frame
-     * without touching the source. Bounds and primitive count are
-     * inherited from `source_geometry`'s CPU object so they stay
-     * accurate under the initial copy; downstream passes refresh them
-     * once vertices actually move.
-     *
-     * Source registration is implicit — the source is `add()`-ed if it
-     * isn't already, so callers don't need to order things.
-     *
-     * @param {MeshletGeometry} source_geometry
-     * @returns {GPUGeometryMetadata} clone's metadata record. `.index`
-     *     is the geometry id to assign to an instance; `.meshlets`
-     *     carries the clone's GPU allocation (data + metadata offsets,
-     *     meshlet count) — needed by the skinning subsystem to wire
-     *     bindings against the right meshlet records.
-     */
-    add_clone(source_geometry) {
-        assert.defined(source_geometry, 'source_geometry');
-        assert.equal(source_geometry.isMeshletGeometry, true, 'source_geometry.isMeshletGeometry !== true');
-
-        // Idempotent — returns false if source is already registered.
-        // Either way, the source's metadata is in the map by the next
-        // line's lookup.
-        this.add(source_geometry);
-
-        const source_metadata = this.#geometries.get(source_geometry);
-
-        const clone_meshlets = this.#meshlets.clone_batch_allocation(source_metadata.meshlets);
-
-        const metadata = new GPUGeometryMetadata();
-        metadata.geometry = source_geometry;
-        metadata.allocated = false;
-        metadata.index = this.__last_geometry_index++;
-        metadata.meshlets = clone_meshlets;
-
-        this.#clone_metadata.push(metadata);
-
-        this.__needs_update = true;
-
-        return metadata;
-    }
-
-    /**
-     * Look up the source-side metadata record for a registered
-     * `MeshletGeometry`. Returns `undefined` if the geometry hasn't
-     * been registered.
-     *
-     * @param {MeshletGeometry} geometry
-     * @returns {GPUGeometryMetadata|undefined}
-     */
-    get_metadata(geometry) {
-        return this.#geometries.get(geometry);
-    }
-
-    /**
-     *
-     * @param {MeshletGeometry} geometry
-     * @returns {boolean}
-     */
-    remove(geometry) {
-        const metadata = this.#geometries.get(geometry);
-
-        if (metadata === undefined) {
-            return false;
-        }
-
-        this.#geometries.delete(geometry);
-
-        // reclaim the meshlet data + metadata allocation (compaction-deferred) and the BLAS
-        // slot. Safe to free before the table rebuild below: the allocators hand out disjoint
-        // slices so other geometries are unaffected, and the rebuild drops this geometry's
-        // metadata row so nothing references the freed ranges afterward.
-        if (metadata.meshlets !== undefined) {
-            this.#meshlets.remove_batch(metadata.meshlets);
-        }
-        this.#blas.remove(metadata);
-
-        // rebuild the GPU metadata table without this entry — without the dirty flag the
-        // removed geometry's row stayed addressable with stale data until an unrelated add()
-        this.__needs_update = true;
-
-        // TODO context indices need to be updated
-        // NOTE: the BLAS append-only data region is not compacted, so its bytes for this
-        //       geometry are unreferenced until a future BVH buffer rebuild (bounded residual).
-
-        return true;
-    }
-
-    destroy() {
-
-        if (this.buffer_metadata !== null) {
-            this.buffer_metadata.destroy();
-        }
-
-        this.#meshlets.destroy();
-
-        // TODO ensure BVH and others are destroyed
-
-        this.__needs_update = true;
-    }
-
-    /**
-     * @param {ShadeGPUCommandContext} [command_ctx] — required when there
-     *     are queued meshlet clones to flush; passed through to
-     *     {@link GPUMeshletManager#update}. Older call sites that don't
-     *     register clones can omit it (the meshlet flush is a no-op when
-     *     nothing's pending).
-     */
-    update(command_ctx) {
-        if (this.__needs_update) {
-            console.time('Geometry build');
-            this.build();
-            console.timeEnd('Geometry build');
-
-            console.time('BVH update');
-            this.#blas.update();
-            console.timeEnd('BVH update');
-
-            if (this.#enable_bvh) {
-                // after `#blas.update()`, which is what turns registrations into arena addresses
-                this.#publish_blas_lookup();
-            }
-
-            // this.#update_sdf(command_ctx);
-
-            this.__needs_update = false;
-        }
-
-        // Always drain — clones can be queued without `__needs_update`
-        // tripping (e.g. by direct callers of `meshlets.clone_batch_allocation`).
-        // No-op when the queue is empty.
-        if (command_ctx !== undefined) {
-            this.#meshlets.update(command_ctx);
-        }
-    }
-
-    /**
-     * Every geometry this manager has handed an id to — sources and per-instance clones alike —
-     * in index order.
-     *
-     * The two share the `__last_geometry_index` space, so every buffer laid out "by geometry id"
-     * is laid out over this one list: the geometry metadata rows, and the BLAS lookup. Having one
-     * answer to "what ids are there" is what keeps those two from drifting apart, which is exactly
-     * what happened while the BLAS lookup was indexed by a pool of its own.
-     *
-     * @returns {GPUGeometryMetadata[]}
-     */
-    #all_metadata_by_index() {
-        const all = [
-            ...this.#geometries.values(),
-            ...this.#clone_metadata,
-        ];
-
-        all.sort((a, b) => a.index - b.index);
-
-        return all;
-    }
-
-    /**
-     * Point every geometry id at the arena address of the tree it should trace against.
-     *
-     * One id, one tree, and the id is the key — which is the whole answer to a clone. A clone has a
-     * geometry id of its own because it has a vertex region of its own, and a tree of its own for
-     * the same reason: what deformation changes is its bounds, and those cannot be written into the
-     * tree every other instance is still tracing. What it does *not* need its own of is the shape,
-     * which the BLAS manager shares between them.
-     *
-     * Must run after {@link GPUGeometryBVHManager#update}, which is what makes addresses real.
-     */
-    #publish_blas_lookup() {
-        const all = this.#all_metadata_by_index();
-
-        const addresses = new Uint32Array(Math.max(1, this.__last_geometry_index));
-
-        for (const meta of all) {
-            const address = this.#blas.get_address(meta);
-
-            assert.defined(
-                address,
-                `geometry ${meta.index} has no BLAS; every geometry a ray can hit needs one`
-            );
-
-            addresses[meta.index] = address;
-        }
-
-        this.#blas.publish_lookup(addresses);
-    }
-
-    build() {
-        // release currently-held resources
-        this.buffer_metadata.destroy();
-
-        const device = this.#device;
-
-        const all_metadata = this.#all_metadata_by_index();
-
-        // One tree per geometry id, clones included — keyed by the metadata row rather than by the
-        // geometry, because a clone and its source share a `MeshletGeometry` and would otherwise
-        // collide on it. The nodes are duplicated per clone on purpose (they are what deformation
-        // rewrites); the shape behind them is not.
-        if (this.#enable_bvh) {
-            for (const meta of all_metadata) {
-                this.#blas.obtain(meta, meta.geometry);
-            }
-        }
-
-        this.buffer_metadata = device.createBuffer(BufferDescriptor.fromJSON({
-            label: this.buffer_metadata.label,
-            size: Math.max(1, this.__last_geometry_index) * GEOMETRY_METADATA_STRUCT.size,
-            usage: this.buffer_metadata.usage,
-            mappedAtCreation: true
-        }));
-
-        // TODO limit mapped range
-        // TODO consider using queue.writeBuffer
-        const metadata = new DataView(this.buffer_metadata.getMappedRange());
-
-        // write metadata
-        for (let i = 0; i < all_metadata.length; i++) {
-            this.#write_geometry_metadata(all_metadata[i], metadata);
-        }
-
-        this.buffer_metadata.unmap();
-    }
-
-    async debug_inspect_gpu_metadata() {
-        const data = await inspect_gpu_buffer_typed({
-            buffer: this.buffer_metadata,
-            device: this.#device,
-            type: GEOMETRY_METADATA_STRUCT,
-            count: this.#geometries.size,
-        });
-
-        return data;
-    }
-
-    /**
-     * Write one row of the geometry metadata buffer. Works for both
-     * source geometries and clones — `g_meta.geometry` always points
-     * at the source's CPU `MeshletGeometry` (clones share it for bounds
-     * + primitive_count), while `g_meta.meshlets` carries the clone's
-     * own GPU allocation when this is a clone.
-     *
-     * @param {GPUGeometryMetadata} g_meta
-     * @param {DataView} metadata
-     */
-    #write_geometry_metadata(g_meta, metadata) {
-        const geometry = g_meta.geometry;
-
-        const idx = g_meta.index;
-
-        const offset = idx * GEOMETRY_METADATA_STRUCT.size;
-
-        // TODO fix this, assumes triangles currently
-        const indexCount = geometry.primitive_count * 3;
-
-        write_gpu_typed_buffer({
-            index_count: indexCount,
-            bounding_sphere: geometry.bounding_sphere,
-            bounding_box: geometry.bounding_box,
-            meshlets_address: g_meta.meshlets.metadata.offset,
-            meshlets_count: g_meta.meshlets.meshlet_count,
-        }, GEOMETRY_METADATA_STRUCT, metadata.buffer, offset);
-
-    }
-}
+import { HashMap } from "../../../core/collection/map/HashMap.js";
+import { BLAS_EMPTY_TREE_ADDRESS } from "./bvh/GPUGeometryBVHManager.js";
+import { assert } from "../../../core/assert.js";
+import { BufferDescriptor } from "../../descriptor/buffer/BufferDescriptor.js";
+import { write_gpu_typed_buffer } from "../shader/type/serde/write_gpu_typed_buffer.js";
+import { inspect_gpu_buffer_typed } from "../buffer/inspect_gpu_buffer_typed.js";
+import { GPUGeometryBVHManager } from "./bvh/GPUGeometryBVHManager.js";
+import { GEOMETRY_METADATA_STRUCT } from "./GEOMETRY_METADATA_STRUCT.js";
+import { GPUGeometryMetadata } from "./GPUGeometryMetadata.js";
+import { GPUMeshletManager } from "./meshlet/GPUMeshletManager.js";
+
+const WORDS_PER_MEGABYTE = 1024 * 1024 / 4;
+
+/**
+ * Manages geometry for indirect draw
+ * Context represents a collection of geometries that are resident on the GPU and are ready to be used in indirect draw to draw entire scenes
+ * @see https://gpuweb.github.io/gpuweb/#dom-gpurendercommandsmixin-drawindexedindirect
+ */
+export class GPUGeometryManager {
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * TODO make use of {@link GPUTypedTable} instead
+     * @type {GPUBuffer|null}
+     */
+    buffer_metadata = null;
+
+    /**
+     *
+     * @type {Map<MeshletGeometry, GPUGeometryMetadata>}
+     */
+    #geometries = new Map();
+
+    /**
+     * The source records by what their geometry *is*: keyed by meshlet content ({@link MeshletGeometry#hash}
+     * and {@link MeshletGeometry#equals}), holding every record with those meshlets — more than one
+     * only when the same meshlets arrived under trees of different sizes, which do not share.
+     *
+     * {@link #geometries} answers "is this object registered"; this answers "is this *geometry*
+     * registered, under any object". A character loaded from a file N times is N parses, each with
+     * its own `MeshletGeometry` of the same bytes; by object they were N rows, N vertex regions and
+     * N trees in the arena, and by content they are one record with N names.
+     *
+     * @type {HashMap<MeshletGeometry, GPUGeometryMetadata[]>}
+     */
+    #records_by_content = new HashMap();
+
+    /**
+     * Per-instance geometry clones — same source as a regular registered
+     * geometry, but with their own GPU vertex/metadata range so a
+     * skinning pass can deform them independently. Stored separately
+     * from {@link #geometries} because multiple clones can share one
+     * source `MeshletGeometry`, which the Map's by-object keying can't
+     * represent.
+     *
+     * Each entry's `geometry` field still points at the source's CPU
+     * `MeshletGeometry` (so bounds and index_count come from the same
+     * place) but `meshlets` is a fresh
+     * {@link MeshletBatchAllocationRecord} produced by
+     * {@link GPUMeshletManager#clone_batch_allocation}. The two
+     * collections share the same `index` space — `__last_geometry_index`
+     * advances for both.
+     *
+     * @type {GPUGeometryMetadata[]}
+     */
+    #clone_metadata = [];
+
+    /**
+     * Do not modify. The data is managed by this class, access in read-only mode.
+     * @return {Map<Readonly<MeshletGeometry>, Readonly<GPUGeometryMetadata>>}
+     */
+    get managed() {
+        return this.#geometries;
+    }
+
+    /**
+     *
+     * @type {number}
+     * @private
+     */
+    __last_geometry_index = 0;
+
+    /**
+     *
+     * @type {boolean}
+     * @private
+     */
+    __needs_update = true;
+
+    /**
+     * @type {GPUMeshletManager}
+     */
+    #meshlets;
+
+    /**
+     *
+     * @return {GPUMeshletManager}
+     */
+    get meshlets() {
+        return this.#meshlets;
+    }
+
+    /**
+     * To support RTX, this needs to be enabled
+     * @type {boolean}
+     */
+    #enable_bvh = true;
+
+    /**
+     * The BLAS manager's {@link GPUGeometryBVHManager#residency_version} the lookup was last
+     * published at. The lookup names an arena address per geometry id, and those change exactly
+     * when that version moves — on a scene edit, and on a tree arriving after its geometry did.
+     *
+     * @type {number}
+     */
+    #published_residency_version = -1;
+
+
+    /**
+     * Bottom-level acceleration structure (BVH for ray casting)
+     * @type {GPUGeometryBVHManager}
+     */
+    #blas
+
+    /**
+     *
+     * @returns {GPUGeometryBVHManager}
+     */
+    get blas() {
+        return this.#blas;
+    }
+
+
+    /**
+     *
+     * @return {GPUGeometrySDFManager}
+     */
+    get sdf() {
+        throw new Error("Not implemented");
+    }
+
+    /**
+     *
+     * @return {number} in bytes
+     */
+    get gpu_memory_usage() {
+        let r = 0;
+
+
+        if (this.buffer_metadata !== null) {
+            r += this.buffer_metadata.size;
+        }
+
+        if (this.#meshlets) {
+            r += this.#meshlets.gpu_memory_usage;
+        }
+
+        if (this.#blas) {
+            r += this.#blas.gpu_memory_usage;
+        }
+
+        return r;
+    }
+
+    /**
+     *
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        this.#device = device;
+        this.#blas = new GPUGeometryBVHManager(device);
+        this.#meshlets = new GPUMeshletManager({ device });
+
+        this.buffer_metadata = device.createBuffer(BufferDescriptor.fromJSON({
+            label: "GPUGeometryContext/metadata",
+            size: 0,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        }));
+    }
+
+    /**
+     *
+     * @param {GPUGeometryMetadata} geometry
+     * @return {number}
+     */
+    getAddress(geometry) {
+        const metadata = this.#geometries.get(geometry);
+
+        return metadata.index;
+    }
+
+    /**
+     *
+     * @param {MeshletGeometry} geometry
+     * @return {boolean}
+     */
+    has(geometry) {
+        return this.#geometries.has(geometry);
+    }
+
+
+    /**
+     *
+     * @param {MeshletGeometry} geometry
+     * @returns {boolean}
+     */
+    add(geometry) {
+        assert.defined(geometry, 'geometry');
+        assert.equal(geometry.isMeshletGeometry, true, 'geometry.isMeshletGeometry !== true');
+
+        if (this.has(geometry)) {
+            return false;
+        }
+
+        // Another object with the same meshlets under a tree of the same size is the same geometry
+        // as far as the GPU is concerned: one row, one vertex region, one tree in the arena — and
+        // this object becomes one more name for that record. The tree is measured, not compared:
+        // equal meshlets from one builder give one tree, and what must not share is the same
+        // meshlets with a tree and without one, which trace differently.
+        let bucket = this.#records_by_content.get(geometry);
+
+        if (bucket !== undefined) {
+            const tree_bytes = geometry.bvh?.byteLength ?? 0;
+
+            const shared = bucket.find(record => (record.geometry.bvh?.byteLength ?? 0) === tree_bytes);
+
+            if (shared !== undefined) {
+                shared.references += 1;
+
+                this.#geometries.set(geometry, shared);
+
+                return true;
+            }
+        }
+
+        const metadata = new GPUGeometryMetadata();
+
+        metadata.geometry = geometry;
+        metadata.references = 1;
+
+        metadata.allocated = false;
+        metadata.index = this.__last_geometry_index++;
+
+        const meshlets = geometry.meshlets;
+
+        metadata.meshlets = this.#meshlets.add_batch(meshlets);
+
+        // watch for data migration
+        metadata.meshlets.changed.add(() => {
+
+            // TODO need to handle this properly
+
+            console.warn('Meshlet GPU address changed.')
+
+        });
+
+        this.#geometries.set(geometry, metadata);
+
+        if (bucket === undefined) {
+            bucket = [];
+
+            this.#records_by_content.set(geometry, bucket);
+        }
+
+        bucket.push(metadata);
+
+        this.__needs_update = true;
+
+        return true;
+    }
+
+    /**
+     * Register a per-instance clone of `source_geometry`. The clone is
+     * a brand-new GPU geometry id that points at a fresh vertex /
+     * metadata range (allocated via
+     * {@link GPUMeshletManager#clone_batch_allocation}); the actual
+     * GPU-side memcpy + address-patch happens lazily on the next
+     * {@link update update(command_ctx)}.
+     *
+     * Use this when you need an instance to render against a *different
+     * copy* of the same mesh data — the canonical case being a
+     * `SkinnedMesh` whose vertex region needs to be deformed each frame
+     * without touching the source. Bounds and primitive count are
+     * inherited from `source_geometry`'s CPU object so they stay
+     * accurate under the initial copy; downstream passes refresh them
+     * once vertices actually move.
+     *
+     * Source registration is implicit — the source is `add()`-ed if it
+     * isn't already, so callers don't need to order things.
+     *
+     * @param {MeshletGeometry} source_geometry
+     * @returns {GPUGeometryMetadata} clone's metadata record. `.index`
+     *     is the geometry id to assign to an instance; `.meshlets`
+     *     carries the clone's GPU allocation (data + metadata offsets,
+     *     meshlet count) — needed by the skinning subsystem to wire
+     *     bindings against the right meshlet records.
+     */
+    add_clone(source_geometry) {
+        assert.defined(source_geometry, 'source_geometry');
+        assert.equal(source_geometry.isMeshletGeometry, true, 'source_geometry.isMeshletGeometry !== true');
+
+        // Idempotent — returns false if source is already registered.
+        // Either way, the source's metadata is in the map by the next
+        // line's lookup.
+        this.add(source_geometry);
+
+        const source_metadata = this.#geometries.get(source_geometry);
+
+        const clone_meshlets = this.#meshlets.clone_batch_allocation(source_metadata.meshlets);
+
+        const metadata = new GPUGeometryMetadata();
+        // The record's geometry, not the object the caller passed: the two are equal in content,
+        // but the BLAS manager keys a tree's *shape* by geometry object, and every clone of one
+        // record sharing one shape is what keeps N dancers from deriving and uploading N copies of it.
+        metadata.geometry = source_metadata.geometry;
+        metadata.allocated = false;
+        metadata.index = this.__last_geometry_index++;
+        metadata.meshlets = clone_meshlets;
+
+        this.#clone_metadata.push(metadata);
+
+        this.__needs_update = true;
+
+        return metadata;
+    }
+
+    /**
+     * Look up the source-side metadata record for a registered
+     * `MeshletGeometry`. Returns `undefined` if the geometry hasn't
+     * been registered.
+     *
+     * @param {MeshletGeometry} geometry
+     * @returns {GPUGeometryMetadata|undefined}
+     */
+    get_metadata(geometry) {
+        return this.#geometries.get(geometry);
+    }
+
+    /**
+     *
+     * @param {MeshletGeometry} geometry
+     * @returns {boolean}
+     */
+    remove(geometry) {
+        const metadata = this.#geometries.get(geometry);
+
+        if (metadata === undefined) {
+            return false;
+        }
+
+        this.#geometries.delete(geometry);
+
+        metadata.references -= 1;
+
+        if (metadata.references > 0) {
+            // other objects still name this record; nothing on the GPU changes
+            return true;
+        }
+
+        this.#forget_content(metadata);
+
+        // reclaim the meshlet data + metadata allocation (compaction-deferred) and the BLAS
+        // slot. Safe to free before the table rebuild below: the allocators hand out disjoint
+        // slices so other geometries are unaffected, and the rebuild drops this geometry's
+        // metadata row so nothing references the freed ranges afterward.
+        if (metadata.meshlets !== undefined) {
+            this.#meshlets.remove_batch(metadata.meshlets);
+        }
+        this.#blas.remove(metadata);
+
+        // rebuild the GPU metadata table without this entry — without the dirty flag the
+        // removed geometry's row stayed addressable with stale data until an unrelated add()
+        this.__needs_update = true;
+
+        // TODO context indices need to be updated
+        // NOTE: the BLAS append-only data region is not compacted, so its bytes for this
+        //       geometry are unreferenced until a future BVH buffer rebuild (bounded residual).
+
+        return true;
+    }
+
+    /**
+     * Take a record out of the by-content index, once nothing names it any more.
+     *
+     * @param {GPUGeometryMetadata} metadata
+     */
+    #forget_content(metadata) {
+        const bucket = this.#records_by_content.get(metadata.geometry);
+
+        if (bucket === undefined) {
+            return;
+        }
+
+        const index = bucket.indexOf(metadata);
+
+        if (index !== -1) {
+            bucket.splice(index, 1);
+        }
+
+        if (bucket.length === 0) {
+            this.#records_by_content.delete(metadata.geometry);
+        }
+    }
+
+    destroy() {
+
+        if (this.buffer_metadata !== null) {
+            this.buffer_metadata.destroy();
+        }
+
+        this.#meshlets.destroy();
+
+        // TODO ensure BVH and others are destroyed
+
+        this.__needs_update = true;
+    }
+
+    /**
+     * @param {ShadeGPUCommandContext} [command_ctx] — required when there
+     *     are queued meshlet clones to flush; passed through to
+     *     {@link GPUMeshletManager#update}. Older call sites that don't
+     *     register clones can omit it (the meshlet flush is a no-op when
+     *     nothing's pending).
+     */
+    update(command_ctx) {
+        const rebuilt = this.__needs_update;
+
+        if (rebuilt) {
+            console.time('Geometry build');
+            this.build();
+            console.timeEnd('Geometry build');
+
+            // this.#update_sdf(command_ctx);
+
+            this.__needs_update = false;
+        }
+
+        // Every call, not only after a scene edit: a tree whose bytes arrived after its geometry was
+        // registered uploads here, and the lookup follows it. Cheap when nothing is pending — a walk
+        // over the shapes and a look at the queue.
+        this.#blas.update();
+
+        // The lookup has a row per geometry id and an arena address in each, so it is republished
+        // when the ids changed (a rebuild) and when the addresses did (the residency version).
+        if (this.#enable_bvh && (rebuilt || this.#published_residency_version !== this.#blas.residency_version)) {
+            // after `#blas.update()`, which is what turns registrations into arena addresses
+            this.#publish_blas_lookup();
+
+            this.#published_residency_version = this.#blas.residency_version;
+        }
+
+        // Always drain — clones can be queued without `__needs_update`
+        // tripping (e.g. by direct callers of `meshlets.clone_batch_allocation`).
+        // No-op when the queue is empty.
+        if (command_ctx !== undefined) {
+            this.#meshlets.update(command_ctx);
+        }
+    }
+
+    /**
+     * Every geometry this manager has handed an id to — sources and per-instance clones alike —
+     * in index order.
+     *
+     * The two share the `__last_geometry_index` space, so every buffer laid out "by geometry id"
+     * is laid out over this one list: the geometry metadata rows, and the BLAS lookup. Having one
+     * answer to "what ids are there" is what keeps those two from drifting apart, which is exactly
+     * what happened while the BLAS lookup was indexed by a pool of its own.
+     *
+     * @returns {GPUGeometryMetadata[]}
+     */
+    #all_metadata_by_index() {
+        // a record with several names is one record, and one row
+        const all = [
+            ...new Set(this.#geometries.values()),
+            ...this.#clone_metadata,
+        ];
+
+        all.sort((a, b) => a.index - b.index);
+
+        return all;
+    }
+
+    /**
+     * Point every geometry id at the arena address of the tree it should trace against.
+     *
+     * One id, one tree, and the id is the key — which is the whole answer to a clone. A clone has a
+     * geometry id of its own because it has a vertex region of its own, and a tree of its own for
+     * the same reason: what deformation changes is its bounds, and those cannot be written into the
+     * tree every other instance is still tracing. What it does *not* need its own of is the shape,
+     * which the BLAS manager shares between them.
+     *
+     * Must run after {@link GPUGeometryBVHManager#update}, which is what makes addresses real.
+     */
+    #publish_blas_lookup() {
+        const all = this.#all_metadata_by_index();
+
+        const addresses = new Uint32Array(Math.max(1, this.__last_geometry_index));
+
+        for (const meta of all) {
+            // A geometry whose tree is not resident yet — registered before its bytes existed —
+            // traces the empty tree until it is. Every traversal starts walking from whatever the
+            // lookup names, so "no tree" has to be a tree, and not the one at the arena's end.
+            addresses[meta.index] = this.#blas.get_address(meta) ?? BLAS_EMPTY_TREE_ADDRESS;
+        }
+
+        this.#blas.publish_lookup(addresses);
+    }
+
+    build() {
+        // release currently-held resources
+        this.buffer_metadata.destroy();
+
+        const device = this.#device;
+
+        const all_metadata = this.#all_metadata_by_index();
+
+        // One tree per geometry id, clones included — keyed by the metadata row rather than by the
+        // geometry, because a clone and its source share a `MeshletGeometry` and would otherwise
+        // collide on it. The nodes are duplicated per clone on purpose (they are what deformation
+        // rewrites); the shape behind them is not.
+        if (this.#enable_bvh) {
+            for (const meta of all_metadata) {
+                this.#blas.obtain(meta, meta.geometry);
+            }
+        }
+
+        this.buffer_metadata = device.createBuffer(BufferDescriptor.fromJSON({
+            label: this.buffer_metadata.label,
+            size: Math.max(1, this.__last_geometry_index) * GEOMETRY_METADATA_STRUCT.size,
+            usage: this.buffer_metadata.usage,
+            mappedAtCreation: true
+        }));
+
+        // TODO limit mapped range
+        // TODO consider using queue.writeBuffer
+        const metadata = new DataView(this.buffer_metadata.getMappedRange());
+
+        // write metadata
+        for (let i = 0; i < all_metadata.length; i++) {
+            this.#write_geometry_metadata(all_metadata[i], metadata);
+        }
+
+        this.buffer_metadata.unmap();
+    }
+
+    async debug_inspect_gpu_metadata() {
+        const data = await inspect_gpu_buffer_typed({
+            buffer: this.buffer_metadata,
+            device: this.#device,
+            type: GEOMETRY_METADATA_STRUCT,
+            // one row per geometry id — sources and clones — not one per registered object, of
+            // which a record may have several
+            count: this.__last_geometry_index,
+        });
+
+        return data;
+    }
+
+    /**
+     * Write one row of the geometry metadata buffer. Works for both
+     * source geometries and clones — `g_meta.geometry` always points
+     * at the source's CPU `MeshletGeometry` (clones share it for bounds
+     * + primitive_count), while `g_meta.meshlets` carries the clone's
+     * own GPU allocation when this is a clone.
+     *
+     * @param {GPUGeometryMetadata} g_meta
+     * @param {DataView} metadata
+     */
+    #write_geometry_metadata(g_meta, metadata) {
+        const geometry = g_meta.geometry;
+
+        const idx = g_meta.index;
+
+        const offset = idx * GEOMETRY_METADATA_STRUCT.size;
+
+        // TODO fix this, assumes triangles currently
+        const indexCount = geometry.primitive_count * 3;
+
+        write_gpu_typed_buffer({
+            index_count: indexCount,
+            bounding_sphere: geometry.bounding_sphere,
+            bounding_box: geometry.bounding_box,
+            meshlets_address: g_meta.meshlets.metadata.offset,
+            meshlets_count: g_meta.meshlets.meshlet_count,
+        }, GEOMETRY_METADATA_STRUCT, metadata.buffer, offset);
+
+    }
+}