@woosh/meep-engine 3.21.0 → 3.22.0

package/src/shade/renderer/animation/ShadeAnimationChannel.d.ts

@@ -183,6 +183,8 @@ export class ShadeAnimationChannel {
     readonly isShadeAnimationChannel: boolean;
     #private;
 }
+export type AnimationCurve = import("../../../engine/animation/curve/AnimationCurve.js").AnimationCurve;
+export type Node3D = import("../scene/Node3D.js").Node3D;
 /**
  * Per-component curves keyed by the GPU track's `(x, y, z, w)`
  * channels. Slots omitted (or set to `undefined`) leave that

package/src/shade/renderer/animation/ShadeAnimationChannel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadeAnimationChannel.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ShadeAnimationChannel.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA6BI;;;;;;;OAOG;IACH,0CAPW;QACV,MAAY,SAAS;QACrB,QAAc,EAAE,MAAM,CAAC;QACvB,MAAY,EAAE,aAAa,CAAC;KACzB,GACS,qBAAqB,CAsBjC;IAvDD;;;;;;OAMG;IACH,eAAc;IAEd;;;;;;;OAOG;IACH,UAFU,MAAM,CAEH;IAEb;;;;;OAKG;IACH,QAFU,aAAa,CAEX;IAgCZ;;;;;;;;;;;OAWG;IACH,YAFW,qBAAqB,QAa/B;IAED;;;;;;OAMG;IACH,SAFa,qBAAqB,CAMjC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAFW,MAAM,QA4ChB;IAED;;;;;;;;;OASG;IACH,0BAQC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACH,YALa,MAAM,CAmElB;IAiBL;;;OAGG;IACH,kCAFU,OAAO,CAEsC;;CANtD"}
+{"version":3,"file":"ShadeAnimationChannel.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ShadeAnimationChannel.js"],"names":[],"mappings":"AAmEA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA6BI;;;;;;;OAOG;IACH,0CAPW;QACV,MAAY,EAAE,MAAM,CAAC;QACrB,QAAc,EAAE,MAAM,CAAC;QACvB,MAAY,EAAE,aAAa,CAAC;KACzB,GACS,qBAAqB,CAsBjC;IAvDD;;;;;;OAMG;IACH,QAFU,MAAM,CAEF;IAEd;;;;;;;OAOG;IACH,UAFU,MAAM,CAEH;IAEb;;;;;OAKG;IACH,QAFU,aAAa,CAEX;IAgCZ;;;;;;;;;;;OAWG;IACH,YAFW,qBAAqB,QAa/B;IAED;;;;;;OAMG;IACH,SAFa,qBAAqB,CAMjC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAFW,MAAM,QA4ChB;IAED;;;;;;;;;OASG;IACH,0BAQC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACH,YALa,MAAM,CAmElB;IAiBL;;;OAGG;IACH,kCAFU,OAAO,CAEsC;;CANtD;6BA/YY,OAAO,mDAAmD,EAAE,cAAc;qBAC1E,OAAO,oBAAoB,EAAE,MAAM;;;;;;;;QA4DlC,cAAc;QACd,cAAc;QACd,cAAc;QACd,cAAc"}

package/src/shade/renderer/animation/ShadeAnimationChannel.js

@@ -10,6 +10,11 @@ import {
 } from "../../../engine/ecs/transform/Transform64.js";
 import { Node3DProperty } from "../object_property/Node3DProperty.js";
 
+/**
+ * @typedef {import("../../../engine/animation/curve/AnimationCurve.js").AnimationCurve} AnimationCurve
+ * @typedef {import("../scene/Node3D.js").Node3D} Node3D
+ */
+
 /**
  * Somewhere to normalise a quaternion before it lands on a transform — {@link Transform64} takes a
  * unit quaternion and does not normalise for you, and {@link Quaternion} already knows how.

package/src/shade/renderer/animation/ShadeAnimationClip.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("./ShadeAnimationChannel.js").ShadeAnimationChannel} ShadeAnimationChannel
+ */
 /**
  * A bundle of {@link ShadeAnimationChannel}s sharing one playback
  * clock — the GPU-driven equivalent of an animation "clip". Each
@@ -124,4 +127,5 @@ export class ShadeAnimationClip {
      */
     readonly isShadeAnimationClip: boolean;
 }
+export type ShadeAnimationChannel = import("./ShadeAnimationChannel.js").ShadeAnimationChannel;
 //# sourceMappingURL=ShadeAnimationClip.d.ts.map

package/src/shade/renderer/animation/ShadeAnimationClip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadeAnimationClip.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ShadeAnimationClip.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA+DI;;;OAGG;IACH,gCAHW;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,uBAAuB,CAAA;KAAE,GAClD,kBAAkB,CAU9B;IAzED;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,UAFU,uBAAuB,CAEnB;IAEd;;;;;OAKG;IACH,yBAWC;IAED;;;;;OAKG;IACH,uBAWC;IAED;;OAEG;IACH,uBAEC;IAgBD;;;;;;;;;;;;;;OAcG;IACH,YAFW,kBAAkB,QAY5B;IAED;;;;;OAKG;IACH,SAFa,kBAAkB,CAM9B;IAED;;;;;;;;;;;;;;OAcG;IACH,SAFW,MAAM,QAQhB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAWC;IAGL;;;OAGG;IACH,+BAFU,OAAO,CAEgC;CANhD"}
+{"version":3,"file":"ShadeAnimationClip.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ShadeAnimationClip.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA+DI;;;OAGG;IACH,gCAHW;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,qBAAqB,EAAE,CAAA;KAAE,GAClD,kBAAkB,CAU9B;IAzED;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,UAFU,qBAAqB,EAAE,CAEnB;IAEd;;;;;OAKG;IACH,yBAWC;IAED;;;;;OAKG;IACH,uBAWC;IAED;;OAEG;IACH,uBAEC;IAgBD;;;;;;;;;;;;;;OAcG;IACH,YAFW,kBAAkB,QAY5B;IAED;;;;;OAKG;IACH,SAFa,kBAAkB,CAM9B;IAED;;;;;;;;;;;;;;OAcG;IACH,SAFW,MAAM,QAQhB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAWC;IAGL;;;OAGG;IACH,+BAFU,OAAO,CAEgC;CANhD;oCAjMY,OAAO,4BAA4B,EAAE,qBAAqB"}

package/src/shade/renderer/animation/ShadeAnimationClip.js

@@ -1,5 +1,9 @@
 import { assert } from "../../../core/assert.js";
 
+/**
+ * @typedef {import("./ShadeAnimationChannel.js").ShadeAnimationChannel} ShadeAnimationChannel
+ */
+
 /**
  * A bundle of {@link ShadeAnimationChannel}s sharing one playback
  * clock — the GPU-driven equivalent of an animation "clip". Each

package/src/shade/renderer/animation/Skin.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import("../scene/Node3D.js").Node3D} Node3D
+ * @typedef {import("../scene/SkinnedMesh.js").SkinnedMesh} SkinnedMesh
+ */
 /**
  * CPU-side description of a skin: the joint nodes that drive
  * deformation, the inverse-bind matrices that take vertices from mesh
@@ -107,4 +111,6 @@ export class Skin {
      */
     readonly isSkin: boolean;
 }
+export type Node3D = import("../scene/Node3D.js").Node3D;
+export type SkinnedMesh = import("../scene/SkinnedMesh.js").SkinnedMesh;
 //# sourceMappingURL=Skin.d.ts.map

package/src/shade/renderer/animation/Skin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Skin.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/Skin.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA8CI;;;;;;;;;;;OAWG;IACH,6DARW;QACV,IAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAY,EAAE,QAAQ,CAAC;QACvB,qBAA2B,EAAE,YAAY,CAAC;QAC1C,MAAY,CAAC,EAAE,aAAa,CAAC;KAC1B,GACS,IAAI,CAiBhB;IAvED;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;OAOG;IACH,QAFU,QAAQ,CAEN;IAEZ;;;;;;;;;;;;;OAaG;IACH,uBAFU,YAAY,CAEsB;IAE5C;;;;;;;;OAQG;IACH,QAFU,aAAa,CAEX;IA+BZ;;;;;;;;;;OAUG;IACH,YAFW,IAAI,QASd;IAED;;;;;;;OAOG;IACH,SAFa,IAAI,CAMhB;IAGL;;;OAGG;IACH,iBAFU,OAAO,CAEI;CANpB"}
+{"version":3,"file":"Skin.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/Skin.js"],"names":[],"mappings":"AAEA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA8CI;;;;;;;;;;;OAWG;IACH,6DARW;QACV,IAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAY,EAAE,MAAM,EAAE,CAAC;QACvB,qBAA2B,EAAE,YAAY,CAAC;QAC1C,MAAY,CAAC,EAAE,WAAW,EAAE,CAAC;KAC1B,GACS,IAAI,CAiBhB;IAvED;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;OAOG;IACH,QAFU,MAAM,EAAE,CAEN;IAEZ;;;;;;;;;;;;;OAaG;IACH,uBAFU,YAAY,CAEsB;IAE5C;;;;;;;;OAQG;IACH,QAFU,WAAW,EAAE,CAEX;IA+BZ;;;;;;;;;;OAUG;IACH,YAFW,IAAI,QASd;IAED;;;;;;;OAOG;IACH,SAFa,IAAI,CAMhB;IAGL;;;OAGG;IACH,iBAFU,OAAO,CAEI;CANpB;qBAvIY,OAAO,oBAAoB,EAAE,MAAM;0BACnC,OAAO,yBAAyB,EAAE,WAAW"}

package/src/shade/renderer/animation/Skin.js

@@ -1,5 +1,10 @@
 import { assert } from "../../../core/assert.js";
 
+/**
+ * @typedef {import("../scene/Node3D.js").Node3D} Node3D
+ * @typedef {import("../scene/SkinnedMesh.js").SkinnedMesh} SkinnedMesh
+ */
+
 /**
  * CPU-side description of a skin: the joint nodes that drive
  * deformation, the inverse-bind matrices that take vertices from mesh

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.d.ts

@@ -43,6 +43,15 @@ export class GPUMeshSkinningContext {
      * @returns {GPUBuffer|null}
      */
     get prev_positions_buffer(): any;
+    /**
+     * Vertex slots {@link prev_positions_buffer} has to address: the high-water mark, which
+     * covers every live binding plus any slice sitting on the free list between them.
+     * Not a count of live skinned vertices — a dropped binding leaves its slice addressable
+     * for the next binding of its size.
+     *
+     * @returns {number}
+     */
+    get prev_position_vertex_count(): number;
     /**
      * The binding records the skinning pass reads — one {@link SKINNING_BINDING_STRUCT} per bound
      * {@link SkinnedMesh}, in {@link #bindings} order. `null` until the first binding has been
@@ -126,6 +135,39 @@ export class GPUMeshSkinningContext {
      * @param {number} skin_id
      */
     unbind_all_by_skin(skin_id: number): void;
+    /**
+     * Give back everything a {@link SkinnedMesh} was holding on the GPU: its binding, its
+     * prev-position slice, and the per-instance geometry clone it rendered.
+     *
+     * **Called when the mesh leaves the scene, not when it unbinds.** A clone is named by the
+     * meshes-table row of the instance that renders it, so it lives exactly as long as that
+     * row does — {@link GPUSceneContext} calls this from the same place it gives the row
+     * back. Unbinding is a different event: an unbound mesh keeps rendering its clone frozen
+     * at the last pose the skinning pass wrote, and freeing there would hand a live renderer
+     * a vertex region that has since gone to somebody else.
+     *
+     * The binding record goes first, and for its own reason: it names the clone's meshlet
+     * rows, and the skinning pass would deform whatever took their place.
+     *
+     * **Which skin the mesh belongs to is not forgotten.** A mesh may leave the scene and
+     * come back — the row it gets is not even the row it had — and the engine's answer to
+     * that is {@link #try_register_binding}, which rebuilds the binding from
+     * {@link #skin_id_by_mesh} the next time `scene.build` asks for the mesh's geometry id.
+     * Releasing through {@link unbind} would drop that association too and hand the returning
+     * mesh back undeformed. Forgetting the skin is what {@link unbind} is for, and it is a
+     * different thing to want.
+     *
+     * The mesh does pay for a fresh clone on its way back in: a new vertex region, its copy
+     * from source, and a new tree. That is the right trade while nothing removes a mesh from
+     * the scene except an entity that is actually leaving — culling and LOD never do — and it
+     * is what a clone cache keyed by source geometry would take away if that ever changes.
+     *
+     * No-op for a mesh that has no clone — a {@link SkinnedMesh} that never reached
+     * `scene.build` or was released already.
+     *
+     * @param {SkinnedMesh} mesh
+     */
+    release_clone(mesh: SkinnedMesh): void;
     /**
      * Per-frame: upload any new bindings + dispatch the skinning
      * compute pass that deforms cloned vertex regions in place.
@@ -146,4 +188,10 @@ export class GPUMeshSkinningContext {
     destroy(): void;
     #private;
 }
+export type ShadeGPUCommandContext = import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
+export type GPUGeometryManager = import("../../geometry/GPUGeometryManager.js").GPUGeometryManager;
+export type GPUSceneContext = import("../../scene/GPUSceneContext.js").GPUSceneContext;
+export type Mesh = import("../../scene/Mesh.js").Mesh;
+export type SkinnedMesh = import("../../scene/SkinnedMesh.js").SkinnedMesh;
+export type GPUAnimationManager = import("../GPUAnimationManager.js").GPUAnimationManager;
 //# sourceMappingURL=GPUMeshSkinningContext.d.ts.map

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshSkinningContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAoNI;;;;;;;OAOG;IACH,sEAPW;QACV,UAAgB,qBAAqB;QACrC,iBAAuB,sBAAsB;QAC7C,aAAmB,kBAAkB;QACrC,MAAY,YAAY;KACrB,EAcH;IAED;;;;;;OAMG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,wCAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,mCAFa,MAAM,CAelB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iCAFW,MAAM,QAmBhB;IAED;;;;;;;OAOG;IACH,gCAFa,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;;;OAUG;IACH,gCAYC;IAED;;;;;;;;OAQG;IACH,4BAFW,MAAM,QAYhB;IAyCD;;;;;;;;;;;;;;;OAeG;IACH,8CAyNC;IAqSD,gBAkBC;;CACJ"}
+{"version":3,"file":"GPUMeshSkinningContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js"],"names":[],"mappings":"AAkFA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IA0OI;;;;;;;OAOG;IACH,sEAPW;QACV,UAAgB,EAAE,kBAAkB,CAAC;QACrC,iBAAuB,EAAE,mBAAmB,CAAC;QAC7C,aAAmB,EAAE,eAAe,CAAC;QACrC,MAAY,YAAY;KACrB,EAcH;IAED;;;;;;OAMG;IACH,iCAEC;IAED;;;;;;;OAOG;IACH,yCAEC;IAED;;;;;;OAMG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,wCAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,4BAHW,IAAI,GACF,MAAM,CAelB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,WAHW,WAAW,WACX,MAAM,QAmBhB;IAED;;;;;;;OAOG;IACH,kBAHW,WAAW,GACT,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;;;OAUG;IACH,aAFW,WAAW,QAYrB;IAED;;;;;;;;OAQG;IACH,4BAFW,MAAM,QAUhB;IA0FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,oBAFW,WAAW,QAqBrB;IAyCD;;;;;;;;;;;;;;;OAeG;IACH,gBAFW,sBAAsB,QA2NhC;IA4SD,gBAkBC;;CACJ;qCA7sCY,OAAO,2CAA2C,EAAE,sBAAsB;iCAC1E,OAAO,sCAAsC,EAAE,kBAAkB;8BACjE,OAAO,gCAAgC,EAAE,eAAe;mBACxD,OAAO,qBAAqB,EAAE,IAAI;0BAClC,OAAO,4BAA4B,EAAE,WAAW;kCAChD,OAAO,2BAA2B,EAAE,mBAAmB"}

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

@@ -27,6 +27,15 @@ import {
 } from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
 import { GPUBLASRefitBatch } from "../../geometry/bvh/GPUBLASRefitBatch.js";
 
+/**
+ * @typedef {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ * @typedef {import("../../geometry/GPUGeometryManager.js").GPUGeometryManager} GPUGeometryManager
+ * @typedef {import("../../scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../scene/Mesh.js").Mesh} Mesh
+ * @typedef {import("../../scene/SkinnedMesh.js").SkinnedMesh} SkinnedMesh
+ * @typedef {import("../GPUAnimationManager.js").GPUAnimationManager} GPUAnimationManager
+ */
+
 /**
  * Initial bindings-buffer capacity (in binding records). 16 × 16 bytes
  * = 256 bytes — wasteful for a scene with no SkinnedMesh, but the
@@ -239,13 +248,35 @@ export class GPUMeshSkinningContext {
     #prev_positions_capacity_vertices = 0;
 
     /**
-     * Next free vertex slot in {@link #prev_positions_buffer}. Each
-     * binding registration reserves `sum(vertex_count)` vertices
-     * starting here and advances by that amount. Monotonic.
+     * High-water mark in {@link #prev_positions_buffer}: the first vertex slot no binding
+     * has ever been given. A binding that cannot be served from
+     * {@link #free_prev_position_ranges} reserves `sum(vertex_count)` vertices starting
+     * here and advances it past them.
+     *
+     * Monotonic, but no longer the whole allocator — a slice given back is reused before
+     * this advances again, so it tracks peak concurrent skinned vertices rather than every
+     * binding ever registered.
+     *
      * @type {number}
      */
     #next_prev_position_vertex_offset = 0;
 
+    /**
+     * Prev-position slices handed back when a binding was dropped, bucketed by their length
+     * in vertices. Each bucket is a stack of base vertex offsets free to give out again.
+     *
+     * Same shape, and the same reasoning, as the skin matrix free list in
+     * {@link GPUAnimationManager}: a slice's base is written into
+     * {@link #prev_position_offsets_cpu} per meshlet and read by the skinning pass as a flat
+     * address, so a slice can be reused where it lies but never moved. Matched exactly and
+     * never split — a binding placed in a shorter slice would write past it — which costs
+     * nothing here because the churn is one character's mesh replaced by the same
+     * character's mesh, at identical vertex counts.
+     *
+     * @type {Map<number, number[]>}
+     */
+    #free_prev_position_ranges = new Map();
+
     /**
      * Per-meshlet base offset (in u32 words) into
      * {@link #prev_positions_buffer}. Indexed by absolute meshlet
@@ -338,6 +369,18 @@ export class GPUMeshSkinningContext {
         return this.#prev_positions_buffer;
     }
 
+    /**
+     * Vertex slots {@link prev_positions_buffer} has to address: the high-water mark, which
+     * covers every live binding plus any slice sitting on the free list between them.
+     * Not a count of live skinned vertices — a dropped binding leaves its slice addressable
+     * for the next binding of its size.
+     *
+     * @returns {number}
+     */
+    get prev_position_vertex_count() {
+        return this.#next_prev_position_vertex_offset;
+    }
+
     /**
      * The binding records the skinning pass reads — one {@link SKINNING_BINDING_STRUCT} per bound
      * {@link SkinnedMesh}, in {@link #bindings} order. `null` until the first binding has been
@@ -457,9 +500,7 @@ export class GPUMeshSkinningContext {
 
         for (let i = this.#bindings.length - 1; i >= 0; i--) {
             if (this.#bindings[i].mesh === mesh) {
-                this.#total_meshlet_count -= this.#bindings[i].meshlet_count;
-                this.#bindings.splice(i, 1);
-                this.#bindings_dirty = true;
+                this.#drop_binding_at(i);
                 break;
             }
         }
@@ -479,11 +520,150 @@ export class GPUMeshSkinningContext {
             const b = this.#bindings[i];
             if (b.skin_id === skin_id) {
                 this.#skin_id_by_mesh.delete(b.mesh);
-                this.#total_meshlet_count -= b.meshlet_count;
-                this.#bindings.splice(i, 1);
-                this.#bindings_dirty = true;
+                this.#drop_binding_at(i);
+            }
+        }
+    }
+
+    /**
+     * Take binding `index` out of the pass and give back what it was holding.
+     *
+     * The prev-position slice goes back on the free list and every meshlet row that pointed
+     * into it is reset to {@link PREV_POSITION_OFFSET_INVALID}. Both halves matter: without
+     * the free the side buffer grows for every binding ever made, and without the reset a
+     * later binding landing on these meshlet rows would inherit an address into somebody
+     * else's slice. The sentinel is also the right answer in its own right — a mesh with no
+     * binding writes no `position_prev`, and the velocity pass falls back to rigid
+     * per-object math for it.
+     *
+     * @param {number} index into {@link #bindings}
+     */
+    #drop_binding_at(index) {
+        const binding = this.#bindings[index];
+
+        this.#total_meshlet_count -= binding.meshlet_count;
+
+        const offsets = this.#prev_position_offsets_cpu;
+        const first_row = binding.clone_meshlet_metadata_offset;
+
+        for (let i = 0; i < binding.meshlet_count; i++) {
+            const row = first_row + i;
+
+            if (row < offsets.length) {
+                offsets[row] = PREV_POSITION_OFFSET_INVALID;
             }
         }
+
+        this.#free_prev_position_range(
+            binding.prev_position_vertex_offset,
+            binding.prev_position_vertex_count,
+        );
+
+        this.#bindings.splice(index, 1);
+        this.#bindings_dirty = true;
+    }
+
+    /**
+     * Reserve `vertex_count` consecutive vertex slots in the prev-positions side buffer and
+     * answer with the base slot. A slice of exactly that length that a dropped binding gave
+     * back is preferred over fresh space — see {@link #free_prev_position_ranges}.
+     *
+     * @param {number} vertex_count
+     * @returns {number} base vertex slot of the reserved slice
+     */
+    #allocate_prev_position_range(vertex_count) {
+        const reusable = this.#free_prev_position_ranges.get(vertex_count);
+
+        if (reusable !== undefined && reusable.length > 0) {
+            // already inside the buffer: it was sized for this slice when the slice was first
+            // handed out, and the buffer only ever grows
+            return reusable.pop();
+        }
+
+        const base_vertex_offset = this.#next_prev_position_vertex_offset;
+
+        this.#next_prev_position_vertex_offset += vertex_count;
+        this.#ensure_prev_positions_capacity_vertices(this.#next_prev_position_vertex_offset);
+
+        return base_vertex_offset;
+    }
+
+    /**
+     * Put a prev-positions slice back on the free list.
+     *
+     * The bytes are left as they are. Nothing reads them until a binding points a meshlet row
+     * at this slice again, and the frame it does is the frame the skinning pass fills it.
+     *
+     * @param {number} base_vertex_offset
+     * @param {number} vertex_count
+     */
+    #free_prev_position_range(base_vertex_offset, vertex_count) {
+        if (vertex_count === 0) {
+            return;
+        }
+
+        let bucket = this.#free_prev_position_ranges.get(vertex_count);
+
+        if (bucket === undefined) {
+            bucket = [];
+
+            this.#free_prev_position_ranges.set(vertex_count, bucket);
+        }
+
+        bucket.push(base_vertex_offset);
+    }
+
+    /**
+     * Give back everything a {@link SkinnedMesh} was holding on the GPU: its binding, its
+     * prev-position slice, and the per-instance geometry clone it rendered.
+     *
+     * **Called when the mesh leaves the scene, not when it unbinds.** A clone is named by the
+     * meshes-table row of the instance that renders it, so it lives exactly as long as that
+     * row does — {@link GPUSceneContext} calls this from the same place it gives the row
+     * back. Unbinding is a different event: an unbound mesh keeps rendering its clone frozen
+     * at the last pose the skinning pass wrote, and freeing there would hand a live renderer
+     * a vertex region that has since gone to somebody else.
+     *
+     * The binding record goes first, and for its own reason: it names the clone's meshlet
+     * rows, and the skinning pass would deform whatever took their place.
+     *
+     * **Which skin the mesh belongs to is not forgotten.** A mesh may leave the scene and
+     * come back — the row it gets is not even the row it had — and the engine's answer to
+     * that is {@link #try_register_binding}, which rebuilds the binding from
+     * {@link #skin_id_by_mesh} the next time `scene.build` asks for the mesh's geometry id.
+     * Releasing through {@link unbind} would drop that association too and hand the returning
+     * mesh back undeformed. Forgetting the skin is what {@link unbind} is for, and it is a
+     * different thing to want.
+     *
+     * The mesh does pay for a fresh clone on its way back in: a new vertex region, its copy
+     * from source, and a new tree. That is the right trade while nothing removes a mesh from
+     * the scene except an entity that is actually leaving — culling and LOD never do — and it
+     * is what a clone cache keyed by source geometry would take away if that ever changes.
+     *
+     * No-op for a mesh that has no clone — a {@link SkinnedMesh} that never reached
+     * `scene.build` or was released already.
+     *
+     * @param {SkinnedMesh} mesh
+     */
+    release_clone(mesh) {
+        assert.defined(mesh, 'mesh');
+
+        const clone_metadata = this.#clones.get(mesh);
+
+        if (clone_metadata === undefined) {
+            return;
+        }
+
+        for (let i = this.#bindings.length - 1; i >= 0; i--) {
+            if (this.#bindings[i].mesh === mesh) {
+                this.#drop_binding_at(i);
+                break;
+            }
+        }
+
+        this.#clones.delete(mesh);
+
+        this.#geometries.remove_clone(clone_metadata);
     }
 
     /**
@@ -797,7 +977,7 @@ export class GPUMeshSkinningContext {
         const meshlet_count = clone_metadata.meshlets.meshlet_count;
         const clone_meshlet_metadata_offset = clone_metadata.meshlets.metadata.offset;
 
-        this.#bindings.push({
+        const binding = {
             skin_id,
             mesh,
             source_meshlet_metadata_offset: source_metadata.meshlets.metadata.offset,
@@ -806,7 +986,13 @@ export class GPUMeshSkinningContext {
             clone_geometry_index: clone_metadata.index,
             // the identity the clone's BLAS is registered under, for the per-frame refit
             clone_metadata,
-        });
+            // the prev-position slice this binding was given, so dropping it can hand the
+            // slice back — filled in below, once the source's vertex counts have been walked
+            prev_position_vertex_offset: 0,
+            prev_position_vertex_count: 0,
+        };
+
+        this.#bindings.push(binding);
         this.#total_meshlet_count += meshlet_count;
         this.#bindings_dirty = true;
 
@@ -835,10 +1021,11 @@ export class GPUMeshSkinningContext {
             total_vertices += vc;
         }
 
-        const base_vertex_offset = this.#next_prev_position_vertex_offset;
-        this.#next_prev_position_vertex_offset += total_vertices;
+        const base_vertex_offset = this.#allocate_prev_position_range(total_vertices);
+
+        binding.prev_position_vertex_offset = base_vertex_offset;
+        binding.prev_position_vertex_count = total_vertices;
 
-        this.#ensure_prev_positions_capacity_vertices(this.#next_prev_position_vertex_offset);
         this.#ensure_prev_position_offsets_capacity(clone_meshlet_metadata_offset + meshlet_count);
 
         // Phase 2: per-meshlet offsets. Convert (vertex slot)

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

@@ -10,7 +10,7 @@ export class BindGroupDescriptor {
      *
      * @returns {BindGroupLayoutDescriptor}
      */
-    get layout(): BindGroupLayoutDescriptor;
+    get layout(): import("../../descriptor/binding/BindGroupLayoutDescriptor.js").BindGroupLayoutDescriptor;
     /**
      *
      * @returns {GPUBindingResource[]}
@@ -30,4 +30,5 @@ export class BindGroupDescriptor {
     isBindGroupDescriptor: boolean;
     #private;
 }
+export type BindGroupLayoutDescriptor = import("../../descriptor/binding/BindGroupLayoutDescriptor.js").BindGroupLayoutDescriptor;
 //# sourceMappingURL=BindGroupDescriptor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"BindGroupDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BindGroupDescriptor.js"],"names":[],"mappings":"AAsIA;IA0FI;;;;;OAKG;IACH,wDAHW,oBAAoB,GAClB,mBAAmB,CAe/B;IAtGD;;;OAGG;IACH,wCAEC;IAQD;;;OAGG;IACH,oCAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CAqBlB;IAED;;;;OAIG;IACH,cAHW,mBAAmB,GACjB,OAAO,CA+BnB;IAwBL,+BAAmD;;CAFlD"}
+{"version":3,"file":"BindGroupDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BindGroupDescriptor.js"],"names":[],"mappings":"AA0IA;IA0FI;;;;;OAKG;IACH,oBAJW,yBAAyB,WACzB,oBAAoB,GAClB,mBAAmB,CAe/B;IAtGD;;;OAGG;IACH,wGAEC;IAQD;;;OAGG;IACH,oCAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CAqBlB;IAED;;;;OAIG;IACH,cAHW,mBAAmB,GACjB,OAAO,CA+BnB;IAwBL,+BAAmD;;CAFlD;wCApPY,OAAO,uDAAuD,EAAE,yBAAyB"}

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

@@ -1,6 +1,10 @@
 import { assert } from "../../../core/assert.js";
 import { lowbias32 } from "../../../core/math/hash/lowbias32.js";
 
+/**
+ * @typedef {import("../../descriptor/binding/BindGroupLayoutDescriptor.js").BindGroupLayoutDescriptor} BindGroupLayoutDescriptor
+ */
+
 /**
  *
  * @type {WeakMap<GPUBuffer, number>}

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

@@ -47,5 +47,6 @@ export class BindGroupManager {
     update(): void;
     #private;
 }
+export type PipelineLayoutManager = import("../../device/pipeline/PipelineLayoutManager.js").PipelineLayoutManager;
 import { BindGroupDescriptor } from "./BindGroupDescriptor.js";
 //# sourceMappingURL=BindGroupManager.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"BindGroupManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BindGroupManager.js"],"names":[],"mappings":"AA4BA;IAwGI;;;;;;OAMG;IACH,+EAHW;QAAC,SAAS,CAAC,EAAC,MAAM,CAAA;KAAC,EAY7B;IAhHD;;;;OAIG;IACH,qCAFa,mBAAmB,CAI/B;IA4DD;;;OAGG;IACH,2CAEC;IAED;;OAEG;IACH,+CAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,2BAEC;IAyBD;;;;OAIG;IACH,mBAHW,mBAAmB,gBAwC7B;IAED;;;;OAIG;IACH,mBAHW,mBAAmB,gBA+C7B;IAGD,eA6BC;;CACJ;oCApRmC,0BAA0B"}
+{"version":3,"file":"BindGroupManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/binding/BindGroupManager.js"],"names":[],"mappings":"AAgCA;IAwGI;;;;;;OAMG;IACH,wCAJW,qBAAqB,kBACrB;QAAC,SAAS,CAAC,EAAC,MAAM,CAAA;KAAC,EAY7B;IAhHD;;;;OAIG;IACH,qCAFa,mBAAmB,CAI/B;IA4DD;;;OAGG;IACH,2CAEC;IAED;;OAEG;IACH,+CAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,2BAEC;IAyBD;;;;OAIG;IACH,mBAHW,mBAAmB,gBAwC7B;IAED;;;;OAIG;IACH,mBAHW,mBAAmB,gBA+C7B;IAGD,eA6BC;;CACJ;oCArRY,OAAO,gDAAgD,EAAE,qBAAqB;oCAHvD,0BAA0B"}

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

@@ -5,6 +5,10 @@ import { invokeObjectHash } from "../../../core/model/object/invokeObjectHash.js
 import { adapt_cache_capacity } from "./adapt_cache_capacity.js";
 import { BindGroupDescriptor } from "./BindGroupDescriptor.js";
 
+/**
+ * @typedef {import("../../device/pipeline/PipelineLayoutManager.js").PipelineLayoutManager} PipelineLayoutManager
+ */
+
 /**
  * How many generations must an element survive in order to be promoted to old-gen
  * @type {number}

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

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("../../device/graph/BufferResourceDescriptor.js").BufferResourceDescriptor} BufferResourceDescriptor
+ */
 export class GPUBufferAllocatorNative {
     /**
      *
@@ -19,4 +22,5 @@ export class GPUBufferAllocatorNative {
     destroy(): void;
     #private;
 }
+export type BufferResourceDescriptor = import("../../device/graph/BufferResourceDescriptor.js").BufferResourceDescriptor;
 //# sourceMappingURL=GPUBufferAllocatorNative.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUBufferAllocatorNative.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferAllocatorNative.js"],"names":[],"mappings":"AAAA;IAMI;;;OAGG;IACH,+BAEC;IAED;;;;OAIG;IACH,qDAEC;IAED;;;;OAIG;IACH,oCAIC;IAED,gBAEC;;CAEJ"}
+{"version":3,"file":"GPUBufferAllocatorNative.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferAllocatorNative.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;IAMI;;;OAGG;IACH,+BAEC;IAED;;;;OAIG;IACH,gBAHW,wBAAwB,aAKlC;IAED;;;;OAIG;IACH,oCAIC;IAED,gBAEC;;CAEJ;uCAzCY,OAAO,gDAAgD,EAAE,wBAAwB"}

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

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import("../../device/graph/BufferResourceDescriptor.js").BufferResourceDescriptor} BufferResourceDescriptor
+ */
+
 export class GPUBufferAllocatorNative {
     /**
      * @type {GPUDevice}

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

@@ -1,15 +1,26 @@
+/**
+ * @typedef {import("../shader/type/WebGPUType.js").WebGPUType} WebGPUType
+ */
 export class GPUTypedBuffer {
     /**
      *
-     * @param {string} [label]
-     * @param {GPUDevice} device
-     * @param {WebGPUType} type
-     * @param {number|GPUBufferUsage} usage
-     * @param {boolean} mappedAtCreation
-     * @param {*} [initial_value] Optional initial value
+     * @param {Object} options
+     * @param {string} [options.label]
+     * @param {GPUDevice} options.device
+     * @param {WebGPUType} options.type
+     * @param {number|GPUBufferUsage} options.usage
+     * @param {boolean} options.mappedAtCreation
+     * @param {*} [options.initial_value] Optional initial value
      * @returns {GPUTypedBuffer}
      */
-    static create({ label, device, type, usage, mappedAtCreation, initial_value, }?: string): GPUTypedBuffer;
+    static create({ label, device, type, usage, mappedAtCreation, initial_value, }: {
+        label?: string;
+        device: GPUDevice;
+        type: WebGPUType;
+        usage: number | GPUBufferUsage;
+        mappedAtCreation: boolean;
+        initial_value?: any;
+    }): GPUTypedBuffer;
     /**
      *
      * @param {WebGPUType} type
@@ -30,7 +41,7 @@ export class GPUTypedBuffer {
      *
      * @returns {WebGPUType}
      */
-    get type(): WebGPUType;
+    get type(): import("../shader/type/WebGPUType.js").WebGPUType;
     get size(): any;
     destroy(): void;
     /**
@@ -43,4 +54,5 @@ export class GPUTypedBuffer {
     toString(): string;
     #private;
 }
+export type WebGPUType = import("../shader/type/WebGPUType.js").WebGPUType;
 //# sourceMappingURL=GPUTypedBuffer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUTypedBuffer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUTypedBuffer.js"],"names":[],"mappings":"AAIA;IA+DI;;;;;;;;;OASG;IACH,iFARW,MAAM,GAMJ,cAAc,CA8C1B;IA7ED;;;;OAIG;IACH,iDAWC;IAtDD;;;OAGG;IACH,gCAEC;IAOD;;;OAGG;IACH,wBAEC;IAOD;;;OAGG;IACH,uBAEC;IAED,gBAEC;IAoBD,gBAEC;IA2DD;;;;;OAKG;IACH,+CASC;IAED,mBAKC;;CACJ"}
+{"version":3,"file":"GPUTypedBuffer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUTypedBuffer.js"],"names":[],"mappings":"AAIA;;GAEG;AAEH;IA+DI;;;;;;;;;;OAUG;IACH;QAR4B,KAAK,GAAtB,MAAM;QACa,MAAM;QACL,IAAI,EAAxB,UAAU;QACqB,KAAK,EAApC,MAAM,iBAAe;QACJ,gBAAgB,EAAjC,OAAO;QACK,aAAa;QACvB,cAAc,CA8C1B;IA9ED;;;;OAIG;IACH,kBAHW,UAAU,qBAcpB;IAtDD;;;OAGG;IACH,gCAEC;IAOD;;;OAGG;IACH,wBAEC;IAOD;;;OAGG;IACH,8DAEC;IAED,gBAEC;IAoBD,gBAEC;IA4DD;;;;;OAKG;IACH,+CASC;IAED,mBAKC;;CACJ;yBAlJY,OAAO,8BAA8B,EAAE,UAAU"}

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

@@ -2,6 +2,10 @@ import { assert } from "../../../core/assert.js";
 import { queue_write_typed_buffer_data } from "../shader/type/queue_typed_buffer_update.js";
 import { write_gpu_typed_buffer } from "../shader/type/serde/write_gpu_typed_buffer.js";
 
+/**
+ * @typedef {import("../shader/type/WebGPUType.js").WebGPUType} WebGPUType
+ */
+
 export class GPUTypedBuffer {
 
     /**
@@ -67,12 +71,13 @@ export class GPUTypedBuffer {
 
     /**
      *
-     * @param {string} [label]
-     * @param {GPUDevice} device
-     * @param {WebGPUType} type
-     * @param {number|GPUBufferUsage} usage
-     * @param {boolean} mappedAtCreation
-     * @param {*} [initial_value] Optional initial value
+     * @param {Object} options
+     * @param {string} [options.label]
+     * @param {GPUDevice} options.device
+     * @param {WebGPUType} options.type
+     * @param {number|GPUBufferUsage} options.usage
+     * @param {boolean} options.mappedAtCreation
+     * @param {*} [options.initial_value] Optional initial value
      * @returns {GPUTypedBuffer}
      */
     static create({

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

@@ -1,11 +1,19 @@
 /**
  *
- * @param {FrameGraph} graph
- * @param {number} buffer
- * @param {WebGPUType} type
- * @param {number} [offset] byte offset where to start reading
- * @param {number} [count] optional number of members of given type to read, if not specified will read the entire buffer
- * @param {function([])} callback
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.buffer
+ * @param {WebGPUType} options.type
+ * @param {number} [options.offset] byte offset where to start reading
+ * @param {number} [options.count] optional number of members of given type to read, if not specified will read the entire buffer
+ * @param {function([])} options.callback
  */
-export function graph_inspect_gpu_buffer({ graph, buffer, type, offset, count, callback }: FrameGraph): any;
+export function graph_inspect_gpu_buffer({ graph, buffer, type, offset, count, callback }: {
+    graph: FrameGraph;
+    buffer: number;
+    type: WebGPUType;
+    offset?: number;
+    count?: number;
+    callback: (arg0: []) => any;
+}): any;
 //# sourceMappingURL=graph_inspect_gpu_buffer.d.ts.map