@woosh/meep-engine 3.21.0 → 3.23.0

package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation} Allocation
+ */
 export class GPUGeometryMeshletsBVH {
     /**
      * The tree's bytes as they were copied into the arena, once they have been. Not taken at
@@ -14,6 +17,14 @@ export class GPUGeometryMeshletsBVH {
      * @type {number}
      */
     address: number;
+    /**
+     * The arena region {@link address} names, as the allocator handed it out — kept so the
+     * region can be given back when this tree is released. `null` until the nodes are
+     * resident, and again once they have been released.
+     *
+     * @type {Allocation|null}
+     */
+    allocation: Allocation | null;
     /**
      * The shape of this tree — parents and leaf positions — shared with every other copy of the same
      * geometry, because a copy differs only in where its bounds are.
@@ -46,4 +57,5 @@ export class GPUGeometryMeshletsBVH {
      */
     released: boolean;
 }
+export type Allocation = import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation;
 //# sourceMappingURL=GPUGeometryMeshletsBVH.d.ts.map

package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryMeshletsBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js"],"names":[],"mappings":"AAAA;IAEI;;;;;;OAMG;IACH,KAFU,WAAW,GAAC,SAAS,CAE3B;IAEJ;;;;;OAKG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,UAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,sBAFU,MAAM,CAES;IAEzB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;CACpB"}
+{"version":3,"file":"GPUGeometryMeshletsBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;IAEI;;;;;;OAMG;IACH,KAFU,WAAW,GAAC,SAAS,CAE3B;IAEJ;;;;;OAKG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;;OAMG;IACH,YAFU,UAAU,GAAC,IAAI,CAEP;IAElB;;;;;OAKG;IACH,UAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,sBAFU,MAAM,CAES;IAEzB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;CACpB;yBAjEY,OAAO,sDAAsD,EAAE,UAAU"}

package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation} Allocation
+ */
+
 export class GPUGeometryMeshletsBVH {
 
     /**
@@ -17,6 +21,15 @@ export class GPUGeometryMeshletsBVH {
      */
     address = 0;
 
+    /**
+     * The arena region {@link address} names, as the allocator handed it out — kept so the
+     * region can be given back when this tree is released. `null` until the nodes are
+     * resident, and again once they have been released.
+     *
+     * @type {Allocation|null}
+     */
+    allocation = null;
+
     /**
      * The shape of this tree — parents and leaf positions — shared with every other copy of the same
      * geometry, because a copy differs only in where its bounds are.

package/src/shade/renderer/geometry/bvh/bvh_to_gpu_buffer.d.ts

@@ -1,9 +1,15 @@
 /**
  * Writes ROOT node as u32 at the start, followed by node array
- * @param {GPUDevice} device
- * @param {BVH} bvh
- * @param {number|GPUBufferUsage} usage
- * @param {string} [label]
+ * @param {Object} options
+ * @param {GPUDevice} options.device
+ * @param {BVH} options.bvh
+ * @param {number|GPUBufferUsage} options.usage
+ * @param {string} [options.label]
  */
-export function bvh_to_gpu_buffer({ device, bvh, usage, label, }: GPUDevice): any;
+export function bvh_to_gpu_buffer({ device, bvh, usage, label, }: {
+    device: GPUDevice;
+    bvh: BVH;
+    usage: number | GPUBufferUsage;
+    label?: string;
+}): any;
 //# sourceMappingURL=bvh_to_gpu_buffer.d.ts.map

package/src/shade/renderer/geometry/bvh/bvh_to_gpu_buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bvh_to_gpu_buffer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/bvh_to_gpu_buffer.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,kFAkCC"}
+{"version":3,"file":"bvh_to_gpu_buffer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/bvh_to_gpu_buffer.js"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH;IAL8B,MAAM;IACZ,GAAG;IACe,KAAK,EAApC,MAAM,iBAAe;IACJ,KAAK,GAAtB,MAAM;QAoChB"}

package/src/shade/renderer/geometry/bvh/bvh_to_gpu_buffer.js

@@ -4,10 +4,11 @@ import { BVH2_NODE_STRUCT } from "../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
 
 /**
  * Writes ROOT node as u32 at the start, followed by node array
- * @param {GPUDevice} device
- * @param {BVH} bvh
- * @param {number|GPUBufferUsage} usage
- * @param {string} [label]
+ * @param {Object} options
+ * @param {GPUDevice} options.device
+ * @param {BVH} options.bvh
+ * @param {number|GPUBufferUsage} options.usage
+ * @param {string} [options.label]
  */
 export function bvh_to_gpu_buffer({
                                       device,

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts

@@ -1,15 +1,37 @@
 export class GPUMeshletManager {
     /**
      *
-     * @param {GPUDevice} device
-     * @param {number} [initial_data_capacity] in bytes
-     * @param {number} [initial_metadata_capacity] in meshlets
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {number} [options.initial_data_capacity] in bytes
+     * @param {number} [options.initial_metadata_capacity] in meshlets
      */
-    constructor({ device, initial_data_capacity, initial_metadata_capacity, }: GPUDevice);
+    constructor({ device, initial_data_capacity, initial_metadata_capacity, }: {
+        device: GPUDevice;
+        initial_data_capacity?: number;
+        initial_metadata_capacity?: number;
+    });
     get buffer_data(): GPUBuffer;
     get buffer_metadata(): GPUBuffer;
     compact(): void;
     /**
+     * Enlarge the data and metadata arenas, leaving every batch exactly where it is.
+     *
+     * Growth appends. {@link OffsetAllocator#grow} files the new tail as free space and moves
+     * nothing, and each buffer's old contents go into the larger one at offset 0 in a single copy —
+     * so no record's `data.offset` or `metadata.offset` changes, no meshlet's `address` field needs
+     * re-patching, and no {@link MeshletBatchAllocationRecord#changed} fires. Compare {@link compact},
+     * which makes room by re-packing instead, and pays all three of those for every record it moves.
+     *
+     * Growing closes no holes, which is why it leaves {@link #deallocations_since_last_rebuild}
+     * alone: the holes it did not close are still there for a later {@link compact} to close.
+     *
+     * The arena an allocator is asked for is a little larger than the shortfall, because the bins
+     * round free runs down and requests up, up to 9/8 apart — room for exactly `extra_data_size`
+     * can still be refused the allocation that asked for it. And no larger than
+     * `maxBufferSize`: growth stops at what the device will hand out, so an arena that cannot
+     * hold the request reports that through the caller's failed allocation rather than through a
+     * buffer that is not there.
      *
      * @param {number} extra_data_size in words (4 bytes)
      * @param {number} extra_metadata_size in metadata elements
@@ -80,6 +102,9 @@ export class GPUMeshletManager {
     get gpu_memory_usage(): number;
     #private;
 }
+export type Allocation = import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation;
+export type ShadeGPUCommandContext = import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
+export type MeshletBatch = import("./MeshletBatch.js").MeshletBatch;
 declare class MeshletBatchAllocationRecord {
     /**
      * @type {Allocation}

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AA+DA;IAoEI;;;;;OAKG;IACH,sFAiCC;IAxFD,6BAEC;IAOD,iCAEC;IA+ED,gBAKC;IAED;;;;OAIG;IACH,sBAHW,MAAM,uBACN,MAAM,QAiDhB;IA+PD;;;;;;;;;;;OAWG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAiBnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CA8BxC;IAED;;;;;;;;;;;;OAYG;IACH,8CA4GC;IAED,gBAGC;IAED;;;;OAIG;IACH,gCAFa,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED,+BAYC;;CACJ;AAluBD;IACI;;OAEG;IACH,qBAAQ;IACR;;OAEG;IACH,iBAAI;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;OAGG;IACH,aAAsB;CACzB"}
+{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AAmFA;IAqEI;;;;;;OAMG;IACH;QAJ8B,MAAM;QACR,qBAAqB,GAAtC,MAAM;QACW,yBAAyB,GAA1C,MAAM;OAkChB;IAzFD,6BAEC;IAOD,iCAEC;IAgFD,gBAKC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,sBAHW,MAAM,uBACN,MAAM,QAuHhB;IAqRD;;;;;;;;;;;OAWG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAmBnB;IAgCD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CA8BxC;IAED;;;;;;;;;;;;OAYG;IACH,gBAFW,sBAAsB,QA8GhC;IAED,gBAGC;IAED;;;;OAIG;IACH,iBAHW,YAAY,GACV,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED,+BAYC;;CACJ;yBA/4BY,OAAO,sDAAsD,EAAE,UAAU;qCACzE,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;AA6BrD;IACI;;OAEG;IACH,UAFU,UAAU,CAEZ;IACR;;OAEG;IACH,MAFU,UAAU,CAEhB;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;OAGG;IACH,aAAsB;CACzB"}

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

@@ -14,6 +14,12 @@ import {
 import { MESHLET_METADATA_STRUCT } from "./encoding/MESHLET_METADATA_STRUCT.js";
 import { shader_meshlet_metadata_address_patch } from "./shader_meshlet_metadata_address_patch.js";
 
+/**
+ * @typedef {import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation} Allocation
+ * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ * @typedef {import("./MeshletBatch.js").MeshletBatch} MeshletBatch
+ */
+
 /**
  * In meshlets
  * @type {number}
@@ -26,6 +32,20 @@ const DEFAULT_METADATA_CAPACITY = 128 * 1024;
  */
 const DEFAULT_DATA_CAPACITY = 32 * MEGABYTE;
 
+/**
+ * Node budget both allocators are built with — the ceiling on how many ranges either can be
+ * describing at once, live allocations and free holes together.
+ *
+ * {@link OffsetAllocator#grow} cannot raise it: the node table cannot be enlarged in place, and the
+ * allocation count a caller needs does not follow from the arena's size anyway. So a manager that
+ * grows keeps whatever it was constructed with, where one that rebuilt got the number re-picked
+ * every time. It loses nothing by that — {@link #rebuild} re-picks the larger of this and twice the
+ * live batch count, which only exceeds this past 65,536 batches.
+ *
+ * @type {number}
+ */
+const ALLOCATION_LIMIT = 128 * 1024;
+
 class MeshletBatchAllocationRecord {
     /**
      * @type {Allocation}
@@ -117,10 +137,11 @@ export class GPUMeshletManager {
      * 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.
+     * clone was queued: a {@link compact} in between migrates both, and
+     * {@link update} reads where they ended up. ({@link grow} moves
+     * nothing, so it needs nothing of them.) What an entry does require
+     * is that neither record is handed back to {@link remove_batch}
+     * before the flush.
      *
      * @type {{
      *   source: MeshletBatchAllocationRecord,
@@ -131,9 +152,10 @@ export class GPUMeshletManager {
 
     /**
      *
-     * @param {GPUDevice} device
-     * @param {number} [initial_data_capacity] in bytes
-     * @param {number} [initial_metadata_capacity] in meshlets
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {number} [options.initial_data_capacity] in bytes
+     * @param {number} [options.initial_metadata_capacity] in meshlets
      */
     constructor({
                     device,
@@ -152,9 +174,8 @@ export class GPUMeshletManager {
 
         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.#allocator_data = new OffsetAllocator(data_buffer_size_words, ALLOCATION_LIMIT);
+        this.#allocator_metadata = new OffsetAllocator(initial_metadata_capacity, ALLOCATION_LIMIT);
 
         this.#meshlet_data_buffer = device.createBuffer({
             label: 'GPUMeshletManager/data',
@@ -178,6 +199,23 @@ export class GPUMeshletManager {
     }
 
     /**
+     * Enlarge the data and metadata arenas, leaving every batch exactly where it is.
+     *
+     * Growth appends. {@link OffsetAllocator#grow} files the new tail as free space and moves
+     * nothing, and each buffer's old contents go into the larger one at offset 0 in a single copy —
+     * so no record's `data.offset` or `metadata.offset` changes, no meshlet's `address` field needs
+     * re-patching, and no {@link MeshletBatchAllocationRecord#changed} fires. Compare {@link compact},
+     * which makes room by re-packing instead, and pays all three of those for every record it moves.
+     *
+     * Growing closes no holes, which is why it leaves {@link #deallocations_since_last_rebuild}
+     * alone: the holes it did not close are still there for a later {@link compact} to close.
+     *
+     * The arena an allocator is asked for is a little larger than the shortfall, because the bins
+     * round free runs down and requests up, up to 9/8 apart — room for exactly `extra_data_size`
+     * can still be refused the allocation that asked for it. And no larger than
+     * `maxBufferSize`: growth stops at what the device will hand out, so an arena that cannot
+     * hold the request reports that through the caller's failed allocation rather than through a
+     * buffer that is not there.
      *
      * @param {number} extra_data_size in words (4 bytes)
      * @param {number} extra_metadata_size in metadata elements
@@ -191,11 +229,13 @@ export class GPUMeshletManager {
             return;
         }
 
-        const current_data_buffer_size_bytes = this.#meshlet_data_buffer.size;
-        const current_metadata_buffer_size = this.#meshlet_metadata_buffer.size;
+        const device = this.#device;
+
+        const old_buffer_data = this.#meshlet_data_buffer;
+        const old_buffer_metadata = this.#meshlet_metadata_buffer;
 
-        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 current_buffer_size_words = old_buffer_data.size >> 2;
+        const current_metadata_buffer_size_elements = Math.ceil(old_buffer_metadata.size / MESHLET_METADATA_STRUCT.aligned_size);
 
         const DATA_GROWTH_STEP = 16 * 1024;
         const METADATA_GROWTH_STEP = 256;
@@ -207,7 +247,7 @@ export class GPUMeshletManager {
         } else {
             // grow
             new_data_size = Math.max(
-                current_buffer_size_words + extra_data_size,
+                current_buffer_size_words + Math.ceil(extra_data_size * 9 / 8),
                 current_buffer_size_words + DATA_GROWTH_STEP,
                 Math.ceil(current_buffer_size_words * GROWTH_MULTIPLIER)
             );
@@ -219,16 +259,84 @@ export class GPUMeshletManager {
         } else {
             // grow
             new_metadata_size = Math.max(
-                current_metadata_buffer_size_elements + extra_metadata_size,
+                current_metadata_buffer_size_elements + Math.ceil(extra_metadata_size * 9 / 8),
                 current_metadata_buffer_size_elements + METADATA_GROWTH_STEP,
-                current_metadata_buffer_size_elements * GROWTH_MULTIPLIER
+                Math.ceil(current_metadata_buffer_size_elements * GROWTH_MULTIPLIER)
             );
         }
 
-        this.#rebuild(
-            new_data_size,
-            new_metadata_size
+        // `createBuffer` answers a size past the device's limit with an *invalid* buffer rather than
+        // an exception. Swapping one of those in would destroy the arena, leave the allocator sized
+        // for space that does not exist, and throw nothing on the way. Capping means a growth gets
+        // as far as the device allows, which is often still enough — and when it is not, the caller's
+        // allocation is what fails.
+        const max_buffer_size = device.limits.maxBufferSize;
+
+        new_data_size = Math.min(new_data_size, Math.floor(max_buffer_size / 4));
+        new_metadata_size = Math.min(
+            new_metadata_size,
+            Math.floor(max_buffer_size / MESHLET_METADATA_STRUCT.aligned_size)
         );
+
+        // A buffer is left alone when its arena did not change, so growing one of the two costs
+        // nothing on the other — and an arena already at the cap is left alone by the same test.
+        const grows_data = new_data_size > current_buffer_size_words;
+        const grows_metadata = new_metadata_size > current_metadata_buffer_size_elements;
+
+        if (!grows_data && !grows_metadata) {
+            // both are as large as this device will allow
+            return;
+        }
+
+        // Buffers first. `OffsetAllocator#grow` cannot be undone, so nothing irreversible happens
+        // until the space it is about to describe exists.
+        const new_buffer_data = grows_data
+            ? device.createBuffer({
+                label: old_buffer_data.label,
+                usage: old_buffer_data.usage,
+                size: new_data_size * 4,
+            })
+            : null;
+
+        const new_buffer_metadata = grows_metadata
+            ? device.createBuffer({
+                label: old_buffer_metadata.label,
+                usage: old_buffer_metadata.usage,
+                size: new_metadata_size * MESHLET_METADATA_STRUCT.aligned_size,
+            })
+            : null;
+
+        const encoder = device.createCommandEncoder({
+            label: "GPUMeshletManager/grow",
+        });
+
+        if (new_buffer_data !== null) {
+            this.#allocator_data.grow(new_data_size);
+
+            // One copy of the whole arena at offset 0. No offset moved, so the bytes land back under
+            // the addresses the records already hold — and the metadata addressing them stays right.
+            encoder.copyBufferToBuffer(old_buffer_data, 0, new_buffer_data, 0, old_buffer_data.size);
+        }
+
+        if (new_buffer_metadata !== null) {
+            this.#allocator_metadata.grow(new_metadata_size);
+
+            encoder.copyBufferToBuffer(old_buffer_metadata, 0, new_buffer_metadata, 0, old_buffer_metadata.size);
+        }
+
+        device.queue.submit([encoder.finish()]);
+
+        if (new_buffer_data !== null) {
+            old_buffer_data.destroy();
+
+            this.#meshlet_data_buffer = new_buffer_data;
+        }
+
+        if (new_buffer_metadata !== null) {
+            old_buffer_metadata.destroy();
+
+            this.#meshlet_metadata_buffer = new_buffer_metadata;
+        }
     }
 
     /**
@@ -298,7 +406,7 @@ export class GPUMeshletManager {
         const record_count = records.length;
         const new_allocator_data = new OffsetAllocator(
             new_data_size,
-            Math.max(record_count * 2, 128 * 1024)
+            Math.max(record_count * 2, ALLOCATION_LIMIT)
         );
 
         const old_buffer_data = this.#meshlet_data_buffer;
@@ -310,7 +418,7 @@ export class GPUMeshletManager {
 
         const new_allocator_metadata = new OffsetAllocator(
             new_metadata_size,
-            Math.max(record_count * 2, 128 * 1024)
+            Math.max(record_count * 2, ALLOCATION_LIMIT)
         );
 
         const old_buffer_metadata = this.#meshlet_metadata_buffer;
@@ -389,15 +497,21 @@ export class GPUMeshletManager {
 
     /**
      * 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
+     * in the metadata buffer, growing or compacting on failure and trying
+     * again. 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.
+     * Which of the two a failure gets is decided by what the failure is.
+     * {@link grow} appends a contiguous run and moves nothing, so it is
+     * the cheap and complete answer to an arena that is merely full.
+     * {@link compact} adds no space at all — it closes holes — and pays a
+     * migration of every allocation, a CPU metadata rewrite each and a
+     * `changed` for every moved address to do it, so it is reserved for
+     * the failure it is the only answer to: the room is already there and
+     * merely scattered. Queued clone work is carried through either —
+     * {@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
@@ -433,14 +547,30 @@ export class GPUMeshletManager {
                 metadata_allocation.metadata = ALLOCATOR_NO_SPACE;
             }
 
-            if (this.#deallocations_since_last_rebuild > 0) {
-                // try compaction
+            // An allocator holding enough free space for the request it just refused is one whose
+            // space is scattered, and closing the holes is the only thing that helps. Anything else
+            // is a shortfall, which growth covers by appending. The margin is the bins': a free run
+            // the allocator rounds down can still be refused a request it rounds up, so "enough"
+            // has to mean 9/8 of it, or a compaction could hand back a single run and still refuse.
+            const data_is_fragmented = !data_ok
+                && this.#allocator_data.freeStorage >= Math.ceil(data_size_words * 9 / 8);
+
+            const metadata_is_fragmented = !metadata_ok
+                && this.#allocator_metadata.freeStorage >= Math.ceil(meshlet_count * 9 / 8);
+
+            // #rebuild zeroes the counter, so a compaction that does not free the request through
+            // leaves the next pass to grow — the loop always makes progress
+            if (
+                this.#deallocations_since_last_rebuild > 0
+                && (data_is_fragmented || metadata_is_fragmented)
+            ) {
                 this.compact();
+
                 continue;
             }
 
-            let grow_data_size = data_ok ? 0 : data_size_words;
-            let grow_metadata_size = metadata_ok ? 0 : meshlet_count;
+            const grow_data_size = data_ok ? 0 : data_size_words;
+            const grow_metadata_size = metadata_ok ? 0 : meshlet_count;
 
             this.grow(grow_data_size, grow_metadata_size);
 
@@ -504,6 +634,8 @@ export class GPUMeshletManager {
             return false;
         }
 
+        this.#cancel_pending_clones_naming(record);
+
         this.#allocator_data.free(record.data);
         this.#allocator_metadata.free(record.metadata);
 
@@ -513,6 +645,36 @@ export class GPUMeshletManager {
         return true;
     }
 
+    /**
+     * Drop the queued clone copies that name `record`, because it is about to stop owning the
+     * ranges they were going to read from or write to.
+     *
+     * A queued copy holds records, not addresses, precisely so a rebuild can move them under it —
+     * but a *released* record keeps the offsets it had while the allocator hands those same
+     * ranges to whoever asks next. Flushing such a copy writes a stale source over a live batch's
+     * vertices, or copies a live batch's vertices into a clone, with nothing to say it happened.
+     * This was unreachable while nothing released a clone; it became reachable the moment
+     * {@link GPUGeometryManager#remove_clone} did.
+     *
+     * Cancelling by source as well as by clone gives up the copy rather than reading a region the
+     * source no longer owns. The clone is left holding its ranges with nothing written into them,
+     * which renders as whatever those bytes were — wrong, but bounded, and it is what removing a
+     * geometry out from under a clone of it already asks for.
+     *
+     * @param {MeshletBatchAllocationRecord} record
+     */
+    #cancel_pending_clones_naming(record) {
+        const pending = this.#pending_clones;
+
+        for (let i = pending.length - 1; i >= 0; i--) {
+            const entry = pending[i];
+
+            if (entry.clone === record || entry.source === record) {
+                pending.splice(i, 1);
+            }
+        }
+    }
+
     /**
      * Allocate a fresh (data, metadata) pair sized to mirror `source`,
      * and queue a GPU-side clone: the source's data and metadata are
@@ -562,7 +724,7 @@ export class GPUMeshletManager {
         // 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.
+        // same frame as the compaction another geometry's arrival forces.
         this.#pending_clones.push({ source, clone: record });
 
         return record;

package/src/shade/renderer/geometry/meshlet/MeshletBatch.d.ts

@@ -78,4 +78,5 @@ export class MeshletBatch {
     readonly isMeshletBatch: boolean;
     #private;
 }
+export type Geometry = import("../Geometry.js").Geometry;
 //# sourceMappingURL=MeshletBatch.d.ts.map

package/src/shade/renderer/geometry/meshlet/MeshletBatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshletBatch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/MeshletBatch.js"],"names":[],"mappings":"AA8DA;;GAEG;AACH;IAiBI;;;OAGG;IACH,oCAGC;IAXD,+BAEC;IA6BD;;;OAGG;IACH,wCAGC;IAfD;;;OAGG;IACH,mCAEC;IAqBD;;;OAGG;IACH,yBAEC;IAdD;;;OAGG;IACH,oBAEC;IAUD;;;OAGG;IACH,QAFa,MAAM,CASlB;IAED;;;OAGG;IACH,cAFW,YAAY,WAQtB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAoFlB;IAED;;;OAGG;IACH,iBAEC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACL,EAAE,CAeb;IAED;;;OAGG;IACH,yBAFW,MAAM;;;;MAgChB;IA4LD,qBA+BC;IAED;;;OAGG;IACH,gCAOC;IAIL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC"}
+{"version":3,"file":"MeshletBatch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/MeshletBatch.js"],"names":[],"mappings":"AAkEA;;GAEG;AACH;IAiBI;;;OAGG;IACH,oCAGC;IAXD,+BAEC;IA6BD;;;OAGG;IACH,wCAGC;IAfD;;;OAGG;IACH,mCAEC;IAqBD;;;OAGG;IACH,yBAEC;IAdD;;;OAGG;IACH,oBAEC;IAUD;;;OAGG;IACH,QAFa,MAAM,CASlB;IAED;;;OAGG;IACH,cAFW,YAAY,WAQtB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAoFlB;IAED;;;OAGG;IACH,iBAEC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACL,EAAE,CAeb;IAED;;;OAGG;IACH,yBAFW,MAAM;;;;MAgChB;IA4LD,qBA+BC;IAED;;;OAGG;IACH,gBAFW,QAAQ,QASlB;IAIL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;uBA1gBY,OAAO,gBAAgB,EAAE,QAAQ"}

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

@@ -25,6 +25,10 @@ import { meshlet_data_index_section_size } from "./meshlet_data_index_section_si
 import { meshlet_encode_attribute } from "./meshlet_encode_attribute.js";
 import { meshlet_get_attribute_offset } from "./meshlet_get_attribute_offset.js";
 
+/**
+ * @typedef {import("../Geometry.js").Geometry} Geometry
+ */
+
 
 const ENCODED_ATTRIBUTE_DEFAULT_VALUES = {
     [StandardAttributes.Color]: 0xFFFFFFFF,

package/src/shade/renderer/geometry/meshlet_batch_to_bvh.d.ts

@@ -1,10 +1,17 @@
 /**
  *
- * @param {BVH} bvh
- * @param {MeshletBatch} meshlets
- * @param {Float32Array} bounding_box
- * @param {number} primitive_count
- * @param {number} [optimization]
+ * @param {Object} options
+ * @param {BVH} options.bvh
+ * @param {MeshletBatch} options.meshlets
+ * @param {Float32Array} options.bounding_box
+ * @param {number} options.primitive_count
+ * @param {number} [options.optimization]
  */
-export function meshlet_batch_to_bvh({ bvh, meshlets, bounding_box, primitive_count, optimization }: BVH): void;
+export function meshlet_batch_to_bvh({ bvh, meshlets, bounding_box, primitive_count, optimization }: {
+    bvh: BVH;
+    meshlets: MeshletBatch;
+    bounding_box: Float32Array;
+    primitive_count: number;
+    optimization?: number;
+}): void;
 //# sourceMappingURL=meshlet_batch_to_bvh.d.ts.map

package/src/shade/renderer/geometry/meshlet_batch_to_bvh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meshlet_batch_to_bvh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/meshlet_batch_to_bvh.js"],"names":[],"mappings":"AAUA;;;;;;;GAOG;AACH,gHA0NC"}
+{"version":3,"file":"meshlet_batch_to_bvh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/meshlet_batch_to_bvh.js"],"names":[],"mappings":"AAUA;;;;;;;;GAQG;AACH;IANwB,GAAG;IACM,QAAQ;IACR,YAAY,EAAlC,YAAY;IACI,eAAe,EAA/B,MAAM;IACW,YAAY,GAA7B,MAAM;SA4NhB"}

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

@@ -10,11 +10,12 @@ import { GEOMETRY_MESHLET_TRIANGLE_LIMIT } from "./meshlet/GEOMETRY_MESHLET_TRIA
 
 /**
  *
- * @param {BVH} bvh
- * @param {MeshletBatch} meshlets
- * @param {Float32Array} bounding_box
- * @param {number} primitive_count
- * @param {number} [optimization]
+ * @param {Object} options
+ * @param {BVH} options.bvh
+ * @param {MeshletBatch} options.meshlets
+ * @param {Float32Array} options.bounding_box
+ * @param {number} options.primitive_count
+ * @param {number} [options.optimization]
  */
 export function meshlet_batch_to_bvh({
                                          bvh,

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.d.ts

@@ -59,5 +59,7 @@ export class GPUGeometrySDFManager {
     download_slot(slot: number): Promise<Float32Array>;
     #private;
 }
+export type ShadeGPUCommandContext = import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
+export type GPUGeometryManager = import("../GPUGeometryManager.js").GPUGeometryManager;
 import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
 //# sourceMappingURL=GPUGeometrySDFManager.d.ts.map

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometrySDFManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js"],"names":[],"mappings":"AAmBA;IAoKI;;;OAGG;IACH,+BAqBC;IAhLD;;;OAGG;IACH,iCAEC;IAQD;;;OAGG;IACH,8BAEC;IAQD,0CAEC;IAED;;;OAGG;IACH,+BAFY,MAAM,CAMjB;IAED;;;OAGG;IACH,sBAFY,MAAM,CA6BjB;IAED;;;OAGG;IACH,6BAFW,MAAM,QAoChB;IAED,uBAEC;IAED;;;OAGG;IACH,mBAFW,MAAM,QA4BhB;IA6BD,gBAEC;IAGD;;;;;OAKG;IACH,+DAHW,MAAM,EAAE,wCAwDlB;IAED;;;;OAIG;IACH,0BAHW,MAAM,GACL,MAAM,EAAE,CAgBnB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACL,QAAQ,YAAY,CAAC,CAiBhC;;CACJ;kCA5TiC,oCAAoC"}
+{"version":3,"file":"GPUGeometrySDFManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js"],"names":[],"mappings":"AAwBA;IAoKI;;;OAGG;IACH,+BAqBC;IAhLD;;;OAGG;IACH,iCAEC;IAQD;;;OAGG;IACH,8BAEC;IAQD,0CAEC;IAED;;;OAGG;IACH,+BAFY,MAAM,CAMjB;IAED;;;OAGG;IACH,sBAFY,MAAM,CA6BjB;IAED;;;OAGG;IACH,6BAFW,MAAM,QAoChB;IAED,uBAEC;IAED;;;OAGG;IACH,mBAFW,MAAM,QA4BhB;IA6BD,gBAEC;IAGD;;;;;OAKG;IACH,yBAJW,sBAAsB,gBACtB,MAAM,EAAE,cACR,kBAAkB,QAuD5B;IAED;;;;OAIG;IACH,0BAHW,MAAM,GACL,MAAM,EAAE,CAgBnB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACL,QAAQ,YAAY,CAAC,CAiBhC;;CACJ;qCA5TY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,0BAA0B,EAAE,kBAAkB;kCANhC,oCAAoC"}

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js

@@ -5,6 +5,11 @@ import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
 import { SFD_BUILD_WORKGROUP_SIZE } from "./SFD_BUILD_WORKGROUP_SIZE.js";
 import { shader_build_sdf } from "./shader_build_sdf.js";
 
+/**
+ * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ * @typedef {import("../GPUGeometryManager.js").GPUGeometryManager} GPUGeometryManager
+ */
+
 
 const INITIAL_CAPACITY = 16;
 

package/src/shade/renderer/geometry/sdf/shader_sdf_visualize.d.ts

@@ -1,12 +1,19 @@
 /**
  *
- * @param {FrameGraph} graph
- * @param {GPUViewContext} view
- * @param {number} input_depth
- * @param {number} input_normals
- * @param {number} input_viz_mesh
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUViewContext} options.view
+ * @param {number} options.input_depth
+ * @param {number} options.input_normals
+ * @param {number} options.input_viz_mesh
  * @param settings
  * @returns {number} texture with shadows
  */
-export function graph_draw_sdf_normals({ graph, view, input_depth, input_normals, input_viz_mesh, }: FrameGraph): number;
+export function graph_draw_sdf_normals({ graph, view, input_depth, input_normals, input_viz_mesh, }: {
+    graph: FrameGraph;
+    view: GPUViewContext;
+    input_depth: number;
+    input_normals: number;
+    input_viz_mesh: number;
+}): number;
 //# sourceMappingURL=shader_sdf_visualize.d.ts.map

package/src/shade/renderer/geometry/sdf/shader_sdf_visualize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_sdf_visualize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/shader_sdf_visualize.js"],"names":[],"mappings":"AAmKA;;;;;;;;;GASG;AACH,kHAFa,MAAM,CAsGlB"}
+{"version":3,"file":"shader_sdf_visualize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/shader_sdf_visualize.js"],"names":[],"mappings":"AAmKA;;;;;;;;;;GAUG;AACH;IAR+B,KAAK;IACD,IAAI;IACZ,WAAW,EAA3B,MAAM;IACU,aAAa,EAA7B,MAAM;IACU,cAAc,EAA9B,MAAM;IAEJ,MAAM,CAsGlB"}