@woosh/meep-engine 3.30.0 → 3.32.0

package/src/shade/renderer/animation/skinning/shader_skin_matrix_prep.js

@@ -1,104 +1,107 @@
-import { mat4x4f, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { ANIMATION_DATABASE_SPEC } from "../ANIMATION_DATABASE_SPEC.js";
-
-const SKIN_JOINT_BLOCK_TABLE = ANIMATION_DATABASE_SPEC.get('animation_skin_joint_blocks');
-
-/**
- * Workgroup size for the skin-matrix-prep pass. Exported so dispatchers
- * can pair it with
- * `animation_skin_joint_blocks.dispatch_group_count(WORKGROUP_SIZE)` —
- * the page iterator's slot-to-workgroup mapping is computed against
- * this value, so the two must agree.
- */
-export const WORKGROUP_SIZE = 64;
-
-const PG_PREFIX = SKIN_JOINT_BLOCK_TABLE.page_iterator_symbol_prefix(WORKGROUP_SIZE);
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addStorageBuffer('animation_database', WebGPUArray.from(u32), false)
-    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
-    .addStorageBuffer('skin_matrices', WebGPUArray.from(mat4x4f), true);
-
-// One thread per joint-block slot — page iterator handles allocation/
-// occupancy. Each thread loads its block, then walks its inline joints
-// in a bounded inner loop. The block carries the absolute write
-// offset into `skin_matrices` (baked at registration time), so there's
-// no indirection back through the skin record.
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@compute @workgroup_size(${WORKGROUP_SIZE},1,1)
-fn main(
-    @builtin(workgroup_id) wg_id: vec3<u32>,
-    @builtin(local_invocation_index) local_id: u32,
-) {
-    if !${PG_PREFIX}_setup(&animation_database, wg_id.x, local_id) {
-        return;
-    }
-
-    let slot_in_page = ${PG_PREFIX}_slot_in_page(local_id);
-
-    if slot_in_page >= ${PG_PREFIX}_ELEMENTS_PER_PAGE {
-        return;
-    }
-    if !${PG_PREFIX}_is_occupied(slot_in_page) {
-        return;
-    }
-
-    let block = ${PG_PREFIX}_read(&animation_database, slot_in_page);
-
-    // Per-joint skin matrix is just joint-world × inverse-bind. The
-    // inverse-bind already takes a vertex from mesh-local space into
-    // joint-bind-local, so joint.global brings the deformed vertex
-    // back into world. The rasterizer then re-applies
-    // mesh.transform_global to the clone vertex (same path used for
-    // every other mesh's vertices, see chunk_mesh_resolve_vertex_
-    // position_world.js) — so any mesh-node factor in this formula
-    // would double-cancel against that re-application and shrink the
-    // rig back to mesh-local coordinates rendered as world. Keeping
-    // the formula minimal lets the SkinnedMesh sit at any transform
-    // in the scene graph and still render correctly via the standard
-    // mesh transform path.
-
-    for(var i = 0u; i < block.count; i++){
-        let joint = block.joints[i];
-        let node = scene_read_node(&scene_database, joint.node);
-
-        skin_matrices[block.skin_matrix_offset + i] =
-            node.global * joint.inverse_bind;
-    }
-}
-`, [
-        SKIN_JOINT_BLOCK_TABLE.chunk_iterate(WORKGROUP_SIZE),
-        chunk_scene_database_access,
-    ]
-);
-
-/**
- * Compute shader that walks the `animation_skin_joint_blocks` table —
- * one thread per joint-block slot via the page iterator — and writes
- * each joint's per-frame skinning matrix `node.global * inverse_bind`
- * to the shared `skin_matrices` scratch buffer at the block's pre-baked
- * absolute offset.
- *
- * Run after `graph_scene_update_transform_hierarchy` (so each joint's
- * `node.global` is up to date) and before any pass that consumes the
- * skin matrices (the pre-skinning compute pass).
- *
- * Dispatch via
- * `shader_skin_matrix_prep.dispatch({ group_count_x: animation_skin_joint_blocks.dispatch_group_count(WORKGROUP_SIZE), ... })`.
- * Skip the dispatch when `group_count_x === 0` — no skins registered
- * means the iterator has no work and `skin_matrices_buffer` may be
- * `null` on the manager.
- */
-export const shader_skin_matrix_prep = ComputeShader.from({
-    label: "Animation/SkinMatrixPrep",
-    body,
-    resources,
-});
+import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
+import { mat4x4f, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ANIMATION_DATABASE_SPEC } from "../ANIMATION_DATABASE_SPEC.js";
+
+const SKIN_JOINT_TABLE = ANIMATION_DATABASE_SPEC.get('animation_skin_joints');
+
+/**
+ * Workgroup size for the skin-matrix-prep pass. Exported so dispatchers
+ * can pair it with
+ * `animation_skin_joints.dispatch_group_count(WORKGROUP_SIZE)` —
+ * the page iterator's slot-to-workgroup mapping is computed against
+ * this value, so the two must agree.
+ */
+export const WORKGROUP_SIZE = 64;
+
+const PG_PREFIX = SKIN_JOINT_TABLE.page_iterator_symbol_prefix(WORKGROUP_SIZE);
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addStorageBuffer('animation_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('skin_matrices', WebGPUArray.from(mat4x4f), true);
+
+// One thread per joint slot — page iterator handles allocation/occupancy. A joint's matrix lives at
+// the joint's own row, so there is no offset to look up and no indirection back through the skin.
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${WORKGROUP_SIZE},1,1)
+fn main(
+    @builtin(workgroup_id) wg_id: vec3<u32>,
+    @builtin(local_invocation_index) local_id: u32,
+) {
+    if !${PG_PREFIX}_setup(&animation_database, wg_id.x, local_id) {
+        return;
+    }
+
+    let slot_in_page = ${PG_PREFIX}_slot_in_page(local_id);
+
+    if slot_in_page >= ${PG_PREFIX}_ELEMENTS_PER_PAGE {
+        return;
+    }
+    if !${PG_PREFIX}_is_occupied(slot_in_page) {
+        return;
+    }
+
+    let joint = ${PG_PREFIX}_read(&animation_database, slot_in_page);
+
+    // A joint of a skin still waiting for its joints' rows names no node yet, and gets no matrix.
+    if joint.node == ${GPU_DATABASE_NULL}u {
+        return;
+    }
+
+    // Per-joint skin matrix is just joint-world × inverse-bind. The
+    // inverse-bind already takes a vertex from mesh-local space into
+    // joint-bind-local, so joint.global brings the deformed vertex
+    // back into world. The rasterizer then re-applies
+    // mesh.transform_global to the clone vertex (same path used for
+    // every other mesh's vertices, see chunk_mesh_resolve_vertex_
+    // position_world.js) — so any mesh-node factor in this formula
+    // would double-cancel against that re-application and shrink the
+    // rig back to mesh-local coordinates rendered as world. Keeping
+    // the formula minimal lets the SkinnedMesh sit at any transform
+    // in the scene graph and still render correctly via the standard
+    // mesh transform path.
+    let node = scene_read_node(&scene_database, joint.node);
+
+    skin_matrices[${PG_PREFIX}_slot_to_index(slot_in_page)] = node.global * joint.inverse_bind;
+}
+`, [
+        SKIN_JOINT_TABLE.chunk_iterate(WORKGROUP_SIZE),
+        chunk_scene_database_access,
+    ]
+);
+
+/**
+ * Compute shader that walks the `animation_skin_joints` table — one
+ * thread per joint slot via the page iterator — and writes each joint's
+ * per-frame skinning matrix `node.global * inverse_bind` to the shared
+ * `skin_matrices` scratch buffer at the joint's row. A skin's joints are
+ * a run of rows, so its matrices are the same run of the buffer, starting
+ * at its `joints_first`. A joint with no node yet is skipped.
+ *
+ * Run after `graph_scene_update_transform_hierarchy` (so each joint's
+ * `node.global` is up to date) and before any pass that consumes the
+ * skin matrices (the pre-skinning compute pass).
+ *
+ * One thread per joint rather than one per block of eight. Measured 2026-09-25, the 21,060 joints
+ * of 324 skins on an RTX 4090, paired launches against the block version: 5.1 µs a frame where it
+ * took 9.2, and the matrices read back within 2e-6 of the block version's.
+ *
+ * Dispatch via
+ * `shader_skin_matrix_prep.dispatch({ group_count_x: animation_skin_joints.dispatch_group_count(WORKGROUP_SIZE), ... })`.
+ * Skip the dispatch when `group_count_x === 0` — no skins registered
+ * means the iterator has no work and `skin_matrices_buffer` may be
+ * `null` on the manager.
+ */
+export const shader_skin_matrix_prep = ComputeShader.from({
+    label: "Animation/SkinMatrixPrep",
+    body,
+    resources,
+});

package/src/shade/renderer/binding/BindingResource.d.ts

@@ -1,10 +1,45 @@
+/**
+ * An engine-level description of one thing a bind group entry can point at, over the engine's own
+ * resource wrappers rather than the raw WebGPU objects.
+ *
+ * ## This is not what the bind-group cache uses
+ *
+ * `BindGroupDescriptor` hashes and compares its entries through its own module-private
+ * `get_resource_buffer_hash` / equality, directly over the native `GPUBindGroupEntry` resources — a
+ * `{buffer, offset, size}` record, a `GPUSampler`, a `GPUTextureView`. That is a different question from
+ * the one this hierarchy answers: it keys on engine wrappers (`GPUBufferContext` and its id), the cache
+ * keys on a `WeakMap` id of the raw `GPUBuffer`.
+ *
+ * The two are deliberately not merged. Routing the cache through these classes would mean allocating a
+ * wrapper per entry on every bind-group lookup, which is per-draw work, and the cache's inputs are native
+ * objects it does not own. So treat this as the descriptive layer and `BindGroupDescriptor`'s private
+ * functions as the cache's own key — and do not read one as the intended replacement for the other,
+ * which the names invite.
+ *
+ * Kept because `@woosh/meep-engine` publishes raw `src`, so an unreferenced export is public surface.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
 export class BindingResource {
-    toGPU(): void;
+    /**
+     * @returns {GPUBindingResource}
+     */
+    toGPU(): GPUBindingResource;
+    /**
+     * @returns {number}
+     */
     hash(): number;
     /**
+     * Whether `other` points at the same thing.
+     *
+     * This used to `return false` unconditionally, so a subclass that forgot to override it reported that
+     * it was not equal to itself — a silently wrong answer from a method whose whole job is identity. It
+     * throws now, like {@link toGPU}: a subclass either answers the question or says it cannot.
      *
      * @param {BindingResource} other
      * @returns {boolean}
+     * @throws {Error} when the subclass has not overridden it
      */
     equals(other: BindingResource): boolean;
 }

package/src/shade/renderer/binding/BindingResource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BindingResource.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BindingResource.js"],"names":[],"mappings":"AAAA;IAEI,cAEC;IAED,eAEC;IAGD;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CAInB;CACJ"}
+{"version":3,"file":"BindingResource.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BindingResource.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAEI;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,QAFa,MAAM,CAIlB;IAED;;;;;;;;;;OAUG;IACH,cAJW,eAAe,GACb,OAAO,CAKnB;CACJ"}

package/src/shade/renderer/binding/BindingResource.js

@@ -1,21 +1,54 @@
+/**
+ * An engine-level description of one thing a bind group entry can point at, over the engine's own
+ * resource wrappers rather than the raw WebGPU objects.
+ *
+ * ## This is not what the bind-group cache uses
+ *
+ * `BindGroupDescriptor` hashes and compares its entries through its own module-private
+ * `get_resource_buffer_hash` / equality, directly over the native `GPUBindGroupEntry` resources — a
+ * `{buffer, offset, size}` record, a `GPUSampler`, a `GPUTextureView`. That is a different question from
+ * the one this hierarchy answers: it keys on engine wrappers (`GPUBufferContext` and its id), the cache
+ * keys on a `WeakMap` id of the raw `GPUBuffer`.
+ *
+ * The two are deliberately not merged. Routing the cache through these classes would mean allocating a
+ * wrapper per entry on every bind-group lookup, which is per-draw work, and the cache's inputs are native
+ * objects it does not own. So treat this as the descriptive layer and `BindGroupDescriptor`'s private
+ * functions as the cache's own key — and do not read one as the intended replacement for the other,
+ * which the names invite.
+ *
+ * Kept because `@woosh/meep-engine` publishes raw `src`, so an unreferenced export is public surface.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
 export class BindingResource {
 
+    /**
+     * @returns {GPUBindingResource}
+     */
     toGPU() {
         throw new Error('Not Implemented');
     }
 
+    /**
+     * @returns {number}
+     */
     hash() {
         return 0;
     }
 
-
     /**
+     * Whether `other` points at the same thing.
+     *
+     * This used to `return false` unconditionally, so a subclass that forgot to override it reported that
+     * it was not equal to itself — a silently wrong answer from a method whose whole job is identity. It
+     * throws now, like {@link toGPU}: a subclass either answers the question or says it cannot.
      *
      * @param {BindingResource} other
      * @returns {boolean}
+     * @throws {Error} when the subclass has not overridden it
      */
     equals(other) {
-        return false;
+        throw new Error('Not Implemented');
     }
 }
-

package/src/shade/renderer/binding/BufferBinding.d.ts

@@ -1,4 +1,11 @@
 /**
+ * A range of one buffer, as a bind group entry would point at it.
+ *
+ * `size === -1` means "the whole buffer from `offset`", which {@link actual_size} resolves. That is this
+ * class own convention and is *not* the one the bind-group cache uses: `BindGroupDescriptor` reads a
+ * missing size as `0`, because it is hashing a native `GPUBindGroupEntry` where absent means
+ * "implementation default". See {@link BindingResource} for why the two are not merged.
+ *
  * @see https://www.w3.org/TR/webgpu/#dictdef-gpubufferbinding
  */
 export class BufferBinding extends BindingResource {
@@ -17,6 +24,7 @@ export class BufferBinding extends BindingResource {
      */
     size: number;
     /**
+     * Resolved size in bytes: `size`, or the rest of the buffer when `size` is -1.
      *
      * @returns {number}
      */

package/src/shade/renderer/binding/BufferBinding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BufferBinding.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BufferBinding.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IAEI;;OAEG;IACH,yBAAO;IAEP;;;OAGG;IACH,QAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEN;IAcV;;;OAGG;IACH,0BAEC;IAED;;;;OAIG;IACH,cAHW,aAAa,GACX,OAAO,CA0BnB;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CANtC;gCA1E+B,sBAAsB"}
+{"version":3,"file":"BufferBinding.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BufferBinding.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH;IAEI;;OAEG;IACH,yBAAO;IAEP;;;OAGG;IACH,QAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEN;IA2BV;;;;OAIG;IACH,0BAEC;IAED;;;;OAIG;IACH,cAHW,aAAa,GACX,OAAO,CA0BnB;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CANtC;gCA/F+B,sBAAsB"}

package/src/shade/renderer/binding/BufferBinding.js

@@ -2,6 +2,13 @@ import { combine_hash } from "../../../core/collection/array/combine_hash.js";
 import { BindingResource } from "./BindingResource.js";
 
 /**
+ * A range of one buffer, as a bind group entry would point at it.
+ *
+ * `size === -1` means "the whole buffer from `offset`", which {@link actual_size} resolves. That is this
+ * class own convention and is *not* the one the bind-group cache uses: `BindGroupDescriptor` reads a
+ * missing size as `0`, because it is hashing a native `GPUBindGroupEntry` where absent means
+ * "implementation default". See {@link BindingResource} for why the two are not merged.
+ *
  * @see https://www.w3.org/TR/webgpu/#dictdef-gpubufferbinding
  */
 export class BufferBinding extends BindingResource {
@@ -36,6 +43,20 @@ export class BufferBinding extends BindingResource {
     }
 
     /**
+     * The native entry this describes.
+     *
+     * @returns {GPUBufferBinding}
+     */
+    toGPU() {
+        return {
+            buffer: this.buffer.gpu_buffer,
+            offset: this.offset,
+            size: this.actual_size
+        };
+    }
+
+    /**
+     * Resolved size in bytes: `size`, or the rest of the buffer when `size` is -1.
      *
      * @returns {number}
      */

package/src/shade/renderer/buffer/GPUBufferStagingAllocator.d.ts

@@ -1,6 +1,11 @@
 /**
- * Provides staging buffers for pushing data from CPU to GPU.
+ * Mapped `MAP_WRITE | COPY_SRC` buffers for pushing data from the CPU to the GPU, one per upload.
  *
+ * A buffer comes out mapped; its holder fills it, unmaps it, copies out of it and gives it back, and
+ * the pool maps it again — a round trip through the GPU — before it can come out again. For bytes
+ * that is the cheaper road; for thousands of small writes a frame the round trips are the cost, which
+ * is why a {@link ShadeGPUCommandContext} brings only its large writes here (see
+ * `MAPPED_UPLOAD_THRESHOLD`).
  */
 export class GPUBufferStagingAllocator {
     /**
@@ -9,6 +14,8 @@ export class GPUBufferStagingAllocator {
      */
     constructor(device: GPUDevice);
     /**
+     * Bytes in every buffer this pool has made and not destroyed: free, handed out, or on the way
+     * back.
      *
      * @returns {number}
      */
@@ -22,8 +29,10 @@ export class GPUBufferStagingAllocator {
     /**
      *
      * @param {GPUBuffer} buffer
+     * @returns {boolean} whether it was taken back: false for a buffer given back already, or one
+     * this pool did not hand out
      */
-    release(buffer: GPUBuffer): void;
+    release(buffer: GPUBuffer): boolean;
     destroy(): void;
     #private;
 }

package/src/shade/renderer/buffer/GPUBufferStagingAllocator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUBufferStagingAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferStagingAllocator.js"],"names":[],"mappings":"AASA;;;GAGG;AACH;IAaI;;;OAGG;IACH,+BAIC;IAED;;;OAGG;IACH,+BAQC;IAGD;;;;OAIG;IACH,oBAHW,MAAM,aAiChB;IAgCD;;;OAGG;IACH,iCAiBC;IAED,gBAOC;;CACJ"}
+{"version":3,"file":"GPUBufferStagingAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferStagingAllocator.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IA8CI;;;OAGG;IACH,+BAIC;IAED;;;;;OAKG;IACH,+BAEC;IAGD;;;;OAIG;IACH,oBAHW,MAAM,aAsChB;IAkCD;;;;;OAKG;IACH,4BAHa,OAAO,CA0BnB;IAgCD,gBAUC;;CACJ"}

package/src/shade/renderer/buffer/GPUBufferStagingAllocator.js

@@ -8,8 +8,13 @@ import { binarySearchHighIndex } from "../../../core/collection/array/binarySear
 let id_count = 0;
 
 /**
- * Provides staging buffers for pushing data from CPU to GPU.
+ * Mapped `MAP_WRITE | COPY_SRC` buffers for pushing data from the CPU to the GPU, one per upload.
  *
+ * A buffer comes out mapped; its holder fills it, unmaps it, copies out of it and gives it back, and
+ * the pool maps it again — a round trip through the GPU — before it can come out again. For bytes
+ * that is the cheaper road; for thousands of small writes a frame the round trips are the cost, which
+ * is why a {@link ShadeGPUCommandContext} brings only its large writes here (see
+ * `MAPPED_UPLOAD_THRESHOLD`).
  */
 export class GPUBufferStagingAllocator {
 
@@ -24,6 +29,39 @@ export class GPUBufferStagingAllocator {
      */
     #ready = [];
 
+    /**
+     * Bytes in {@link #ready}.
+     *
+     * @type {number}
+     */
+    #ready_byte_size = 0;
+
+    /**
+     * Bytes in buffers handed out and not back in {@link #ready} yet: with their holder, or on their
+     * way back through a mapping. They are memory like any other, and a GPU running behind holds a
+     * frame's worth of them for every frame it is behind.
+     *
+     * @type {number}
+     */
+    #held_byte_size = 0;
+
+    /**
+     * Buffers handed out and not given back yet. Only these are taken back: a buffer given back
+     * twice, or one this pool never made, would otherwise go into {@link #ready} twice and come out
+     * to two holders at once.
+     *
+     * @type {Set<GPUBuffer>}
+     */
+    #held = new Set();
+
+    /**
+     * Set by {@link destroy}. A buffer whose mapping comes back after that is destroyed, not pooled —
+     * the pool it would go into is gone.
+     *
+     * @type {boolean}
+     */
+    #destroyed = false;
+
     /**
      *
      * @param {GPUDevice} device
@@ -35,17 +73,13 @@ export class GPUBufferStagingAllocator {
     }
 
     /**
+     * Bytes in every buffer this pool has made and not destroyed: free, handed out, or on the way
+     * back.
      *
      * @returns {number}
      */
     get gpu_memory_usage() {
-        let r = 0;
-
-        for (const b of this.#ready) {
-            r += b.size;
-        }
-
-        return r;
+        return this.#ready_byte_size + this.#held_byte_size;
     }
 
 
@@ -78,8 +112,13 @@ export class GPUBufferStagingAllocator {
                 mappedAtCreation: true,
             });
 
+        } else {
+            this.#ready_byte_size -= result.size;
         }
 
+        this.#held_byte_size += result.size;
+        this.#held.add(result);
+
         assert.greaterThanOrEqual(result.size, min_size_bytes, 'result.size < min_size_bytes');
         assert.equal(result.mapState, "mapped", 'result.mapState !== "mapped"');
 
@@ -113,38 +152,81 @@ export class GPUBufferStagingAllocator {
 
         this.#ready.splice(index, 0, buffer);
 
+        this.#ready_byte_size += buffer.size;
+
         return true;
     }
 
     /**
      *
      * @param {GPUBuffer} buffer
+     * @returns {boolean} whether it was taken back: false for a buffer given back already, or one
+     * this pool did not hand out
      */
     release(buffer) {
+        if (!this.#held.delete(buffer)) {
+            return false;
+        }
+
         const state = buffer.mapState;
 
-        // TODO have a cleanup mechanism to prevent memory leak
+        // TODO the ready list never shrinks: a burst's buffers stay until destroy()
 
         if (state === "mapped") {
             // release directly
-            this.#add_to_ready(buffer);
+            this.#take_back(buffer);
         } else if (state === "unmapped") {
             buffer.mapAsync(GPUMapMode.WRITE)
                 .then(
-                    () => this.#add_to_ready(buffer),
-                    console.error
+                    () => this.#take_back(buffer),
+                    () => this.#give_up(buffer)
                 );
         } else {
             throw new Error(`Invalid map state: ${state}`);
         }
+
+        return true;
+    }
+
+    /**
+     * A buffer back and mapped, to be handed out again.
+     *
+     * @param {GPUBuffer} buffer
+     */
+    #take_back(buffer) {
+        this.#held_byte_size -= buffer.size;
+
+        if (this.#destroyed) {
+            buffer.destroy();
+
+            return;
+        }
+
+        this.#add_to_ready(buffer);
+    }
+
+    /**
+     * A mapping that failed — the buffer or its device is gone — brings nothing back to reuse. It
+     * used to be logged and dropped: never destroyed, so whatever was left of it waited for the
+     * garbage collector.
+     *
+     * @param {GPUBuffer} buffer
+     */
+    #give_up(buffer) {
+        this.#held_byte_size -= buffer.size;
+
+        buffer.destroy();
     }
 
     destroy() {
+        this.#destroyed = true;
+
         for (const b of this.#ready) {
             b.destroy();
         }
 
         // drop data
         this.#ready.splice(0, this.#ready.length);
+        this.#ready_byte_size = 0;
     }
-}
+}