@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,1024 +1,1024 @@
-import { assert } from "../../../../core/assert.js";
-import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { write_gpu_typed_buffer } from "../../shader/type/serde/write_gpu_typed_buffer.js";
-import {
-    shader_geometry_sphere_derive,
-    WORKGROUP_SIZE as SPHERE_DERIVE_WORKGROUP_SIZE,
-} from "./bounds_refresh/shader_geometry_sphere_derive.js";
-import {
-    shader_meshlet_bounds_reduce,
-    WORKGROUP_SIZE as BOUNDS_REDUCE_WORKGROUP_SIZE,
-} from "./bounds_refresh/shader_meshlet_bounds_reduce.js";
-import {
-    shader_meshlet_bounds_scatter,
-    WORKGROUP_SIZE as BOUNDS_SCATTER_WORKGROUP_SIZE,
-} from "./bounds_refresh/shader_meshlet_bounds_scatter.js";
-import {
-    shader_skinned_mesh_bounds_refresh,
-    WORKGROUP_SIZE as MESH_BOUNDS_REFRESH_WORKGROUP_SIZE,
-} from "./bounds_refresh/shader_skinned_mesh_bounds_refresh.js";
-import {
-    SKINNING_BINDING_STRUCT
-} from "./SKINNING_BINDING_STRUCT.js";
-import {
-    shader_meshlet_apply_skinning
-} from "./shader_meshlet_apply_skinning.js";
-import {
-    MESHLET_METADATA_STRUCT
-} from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-
-/**
- * Initial bindings-buffer capacity (in binding records). 16 × 16 bytes
- * = 256 bytes — wasteful for a scene with no SkinnedMesh, but the
- * doubling growth absorbs any larger scene cheaply.
- */
-const BINDINGS_INITIAL_CAPACITY = 16;
-
-/**
- * Initial dispatch-lookup capacity (in `(binding_index, meshlet_local)`
- * pairs, i.e. 8 bytes per slot). Sized to the same default a small
- * skinned mesh produces.
- */
-const DISPATCH_LOOKUP_INITIAL_CAPACITY = 256;
-
-/**
- * Initial `prev_positions_buffer` capacity in vertices. Each vertex
- * is 3 × f32 = 12 bytes. 1024 vertices → 12 KB. Doubles on grow.
- */
-const PREV_POSITIONS_INITIAL_CAPACITY_VERTICES = 1024;
-
-/**
- * Initial `prev_position_offsets_buffer` capacity in u32 records
- * (one per meshlet metadata row). 1024 × 4 = 4 KB. Doubles on grow.
- */
-const PREV_POSITION_OFFSETS_INITIAL_CAPACITY = 1024;
-
-/**
- * Sentinel value in `prev_position_offsets` for meshlet metadata
- * rows that are NOT skinned clones — sources, static-mesh geometries,
- * pre-skinning clones (rare), etc. The skinning shader sees this
- * value and skips its `position_prev` write; the velocity post-pass
- * sees it and falls back to the rigid per-object math.
- */
-const PREV_POSITION_OFFSET_INVALID = 0xFFFFFFFF;
-
-/**
- * f32 vertex_count byte offset within MESHLET_METADATA_STRUCT, resolved
- * at module load (after `.pack()` reorders fields). Used by the CPU
- * binding-registration path to walk the source's metadata bytes and
- * sum vertex counts for prev-position side-buffer allocation.
- */
-const MESHLET_VERTEX_COUNT_BYTE_OFFSET = MESHLET_METADATA_STRUCT.get('vertex_count').offset;
-const MESHLET_STRIDE_BYTES = MESHLET_METADATA_STRUCT.aligned_size;
-
-/**
- * Per-scene container for the skinning subsystem's state. Owned by
- * {@link GPUSceneContext}; receives the scene's
- * {@link GPUGeometryManager} so it can allocate per-instance geometry
- * clones for {@link SkinnedMesh} instances and route the skinning
- * compute pass against those clones.
- *
- * Three responsibilities:
- *  1. Geometry-clone routing — `obtain_geometry_index(mesh)` returns
- *     the clone id for SkinnedMesh, the source id for everyone else.
- *  2. Skinning binding bookkeeping — each SkinnedMesh with a `skin_id`
- *     produces one binding record linking its clone's vertex region
- *     back to the source's data and to the skin's matrix range.
- *  3. Per-frame dispatch — `update(cmd_ctx, animation_manager)`
- *     uploads any new bindings and dispatches the skinning compute
- *     pass that deforms the cloned vertex regions in place.
- *
- * The CPU-side binding records cache `skin_id` rather than
- * `skin_matrix_offset` because the offset is owned by the animation
- * manager. Resolution happens at upload time via
- * `animation_manager.get_skin_matrix_offset(skin_id)`.
- */
-export class GPUMeshSkinningContext {
-
-    /** @type {GPUDevice} */
-    #device;
-
-    /** @type {GPUGeometryManager} */
-    #geometries;
-
-    /** @type {GPUAnimationManager} */
-    #animation_manager;
-
-    /**
-     * Per-SkinnedMesh clone metadata, cached so repeated lookups
-     * (binding-registration, geometry id resolution) hit the same
-     * record rather than re-cloning the source. Persists across
-     * scene rebuilds (unlike id_mapping).
-     *
-     * @type {Map<SkinnedMesh, GPUGeometryMetadata>}
-     */
-    #clones = new Map();
-
-    /**
-     * Per-mesh skin assignment. Populated by {@link bind}; consumed
-     * by {@link #register_binding} when it stamps the GPU binding
-     * record. A mesh present here has had a skinning binding
-     * registered exactly once — re-binding the same mesh is a
-     * no-op (the existing binding stands).
-     *
-     * Held here rather than on the {@link SkinnedMesh} so the public
-     * mesh class doesn't carry GPU-side state; consumers who need
-     * to look up "what skin is mesh X bound to?" can query via
-     * {@link get_skin_id}.
-     *
-     * @type {Map<SkinnedMesh, number>}
-     */
-    #skin_id_by_mesh = new Map();
-
-    /**
-     * One CPU record per `(SkinnedMesh, clone)` binding registered via
-     * {@link #register_binding}. Resolved into GPU bytes at upload
-     * time — `skin_id` becomes `skin_matrix_offset` via
-     * {@link GPUAnimationManager#get_skin_matrix_offset}, and `mesh`
-     * becomes a meshes-table row via
-     * {@link GPUSceneContext#mesh_row_of}. The mesh is held rather
-     * than its row because the row is not stable: registration
-     * happens before the scene has placed the mesh at all, and the
-     * table reuses rows afterwards.
-     *
-     * Append-only in this MVP — removing a SkinnedMesh leaks its
-     * binding (alongside its clone). Acceptable at the lifetime-
-     * distinct-instance scale; phase-4 frees both together.
-     *
-     * @type {{
-     *     skin_id: number,
-     *     mesh: SkinnedMesh,
-     *     source_meshlet_metadata_offset: number,
-     *     clone_meshlet_metadata_offset: number,
-     *     meshlet_count: number,
-     *     clone_geometry_index: number,
-     * }[]}
-     */
-    #bindings = [];
-
-    /**
-     * Sum of {@link #bindings}[i].meshlet_count — the dispatch-lookup
-     * length and the workgroup count for the skinning compute pass.
-     * Tracked incrementally to avoid re-summing per frame.
-     * @type {number}
-     */
-    #total_meshlet_count = 0;
-
-    /**
-     * Set when {@link #bindings} has changed since the last upload.
-     * Cleared by {@link update} after re-uploading both the bindings
-     * buffer and the dispatch-lookup buffer.
-     * @type {boolean}
-     */
-    #bindings_dirty = false;
-
-    /**
-     * The scene context's {@link GPUSceneContext#mesh_rows_version} as of the last bindings upload.
-     * The records hold meshes-table rows and that table reuses them, so a difference here means
-     * every record's row has to be resolved again.
-     *
-     * @type {number}
-     */
-    #uploaded_mesh_rows_version = -1;
-
-    /**
-     * GPU mirror of {@link #bindings}, with `skin_id` resolved to
-     * `skin_matrix_offset`. `null` until the first binding is
-     * registered.
-     * @type {GPUBuffer|null}
-     */
-    #bindings_buffer = null;
-
-    /**
-     * Capacity of {@link #bindings_buffer} in binding records. Grows
-     * by doubling when a new binding pushes past it.
-     * @type {number}
-     */
-    #bindings_capacity = 0;
-
-    /**
-     * Flat `(binding_index, meshlet_local_index)` u32 pairs — one pair
-     * per workgroup. The skinning shader reads `dispatch_lookup[wg_id]`
-     * to figure out which (binding, meshlet) it's processing.
-     * @type {GPUBuffer|null}
-     */
-    #dispatch_lookup_buffer = null;
-
-    /**
-     * Capacity of {@link #dispatch_lookup_buffer} in `(binding,
-     * meshlet)` pairs (i.e. half the u32 count). Grows by doubling.
-     * @type {number}
-     */
-    #dispatch_lookup_capacity = 0;
-
-    /**
-     * Side-buffer holding the previous-frame mesh-local skinned
-     * positions for every clone meshlet's vertices. Laid out as
-     * tightly-packed `vec3<f32>` (3 × u32 words, f32 bit pattern)
-     * per vertex; each clone meshlet owns a contiguous slice of
-     * `vertex_count` vec3s starting at the offset recorded in
-     * {@link #prev_position_offsets_buffer}.
-     *
-     * Written by the skinning compute shader (using the manager's
-     * `prev_skin_matrices_buffer`), read by the velocity post-pass
-     * to interpolate per-vertex skin deformation across the rasterized
-     * triangle.
-     *
-     * Append-only — bindings reserve contiguous vertex ranges via
-     * {@link #next_prev_position_vertex_offset}; nothing frees.
-     *
-     * @type {GPUBuffer|null}
-     */
-    #prev_positions_buffer = null;
-
-    /**
-     * Capacity of {@link #prev_positions_buffer} in vertices (each
-     * vertex = 3 × u32 words).
-     * @type {number}
-     */
-    #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.
-     * @type {number}
-     */
-    #next_prev_position_vertex_offset = 0;
-
-    /**
-     * Per-meshlet base offset (in u32 words) into
-     * {@link #prev_positions_buffer}. Indexed by absolute meshlet
-     * metadata row — `prev_position_offsets[meshlet_index]` gives
-     * either {@link PREV_POSITION_OFFSET_INVALID} (non-clone or
-     * not-yet-bound meshlet) or the first u32 word of that
-     * meshlet's prev-position slice.
-     *
-     * Sized to the meshlet metadata buffer's record capacity (or
-     * larger). Re-uploaded from the CPU shadow whenever a new
-     * binding adds entries.
-     *
-     * @type {GPUBuffer|null}
-     */
-    #prev_position_offsets_buffer = null;
-
-    /**
-     * Capacity of {@link #prev_position_offsets_buffer} in u32
-     * records (= one per meshlet metadata row).
-     * @type {number}
-     */
-    #prev_position_offsets_capacity = 0;
-
-    /**
-     * CPU shadow of {@link #prev_position_offsets_buffer}. Mutated
-     * by {@link #register_binding} when computing per-meshlet offsets;
-     * re-uploaded wholesale by {@link #upload_prev_position_offsets}.
-     * Entries default to {@link PREV_POSITION_OFFSET_INVALID}.
-     *
-     * @type {Uint32Array}
-     */
-    #prev_position_offsets_cpu = new Uint32Array(0);
-
-    /**
-     * Back-reference to the owning {@link GPUSceneContext} so the
-     * bindings-upload path can resolve a mesh to its meshes-table row
-     * via {@link GPUSceneContext#mesh_row_of} without the caller
-     * threading that lookup through every `bind()` call.
-     *
-     * Resolution cannot happen at registration time: `bind` and
-     * `obtain_geometry_index` both run before `scene.build` has given
-     * the mesh a row. Nor does resolving once suffice — the table
-     * hands out the lowest free row, so a mesh that leaves and
-     * re-enters the scene lands somewhere else, which is what
-     * {@link GPUSceneContext#mesh_rows_version} is compared for.
-     *
-     * @type {GPUSceneContext}
-     */
-    #scene_context;
-
-    /**
-     * @param {{
-     *     geometries: GPUGeometryManager,
-     *     animation_manager: GPUAnimationManager,
-     *     scene_context: GPUSceneContext,
-     *     device: GPUDevice,
-     * }} args
-     */
-    constructor({ geometries, animation_manager, scene_context, device }) {
-        assert.defined(geometries, 'geometries');
-        assert.defined(animation_manager, 'animation_manager');
-        assert.defined(scene_context, 'scene_context');
-        assert.defined(device, 'device');
-
-        this.#geometries = geometries;
-        this.#animation_manager = animation_manager;
-        this.#scene_context = scene_context;
-        this.#device = device;
-    }
-
-    /**
-     * Side-buffer of previous-frame mesh-local skinned positions for
-     * the velocity post-pass. `null` until the first skinning binding
-     * has been registered.
-     *
-     * @returns {GPUBuffer|null}
-     */
-    get prev_positions_buffer() {
-        return this.#prev_positions_buffer;
-    }
-
-    /**
-     * 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
-     * registered and uploaded.
-     *
-     * @returns {GPUBuffer|null}
-     */
-    get bindings_buffer() {
-        return this.#bindings_buffer;
-    }
-
-    /**
-     * Per-meshlet base offsets into {@link prev_positions_buffer},
-     * indexed by absolute meshlet metadata row. Non-clone meshlets
-     * hold the sentinel `0xFFFFFFFF`. `null` until the first
-     * skinning binding has been registered.
-     *
-     * @returns {GPUBuffer|null}
-     */
-    get prev_position_offsets_buffer() {
-        return this.#prev_position_offsets_buffer;
-    }
-
-    /**
-     * Geometry id to assign to this mesh's instance record. Idempotent.
-     *
-     * - For a {@link SkinnedMesh}: a per-instance clone of the source's
-     *   GPU geometry. The first time we see a given mesh, allocate a
-     *   clone; subsequent calls return the cached id. If the mesh has
-     *   already been bound to a skin via {@link bind}, the binding's
-     *   registration also runs here so scene.build's first sight of
-     *   a pre-bound mesh doesn't strand it without a deformation pass.
-     * - For a regular {@link Mesh}: the source's id from the geometry
-     *   manager.
-     *
-     * @param {Mesh} mesh
-     * @returns {number}
-     */
-    obtain_geometry_index(mesh) {
-        if (mesh.isSkinnedMesh === true) {
-            const clone_metadata = this.#ensure_clone(mesh);
-            // If the mesh has already been bound (bind() ran before
-            // scene.build for this mesh), register its binding now.
-            // No-op if not yet bound or if the binding has already
-            // been registered in a previous call.
-            this.#try_register_binding(mesh, clone_metadata);
-            return clone_metadata.index;
-        }
-
-        this.#geometries.add(mesh.geometry);
-        return this.#geometries.getAddress(mesh.geometry);
-    }
-
-    /**
-     * Bind a {@link SkinnedMesh} to a skin. The mesh's clone (if not
-     * already allocated) is created on demand; a skinning-pass
-     * binding record is registered so the deformation runs each
-     * frame. The skin id is stored on the context (not on the mesh
-     * — `SkinnedMesh` carries no GPU state).
-     *
-     * Re-binding the same mesh with a different skin id is rejected
-     * (single-binding model in this MVP — use {@link unbind} first if
-     * you need to swap). Calling with the same skin id is a no-op.
-     *
-     * Tolerates being called before `scene.build` registers the mesh;
-     * the binding upload happens during the next per-frame
-     * {@link update}.
-     *
-     * @param {SkinnedMesh} mesh
-     * @param {number} skin_id
-     */
-    bind(mesh, skin_id) {
-        assert.defined(mesh, 'mesh');
-        assert.equal(mesh.isSkinnedMesh, true, 'mesh.isSkinnedMesh !== true');
-        assert.isNonNegativeInteger(skin_id, 'skin_id');
-
-        const existing = this.#skin_id_by_mesh.get(mesh);
-        if (existing !== undefined) {
-            assert.equal(
-                existing, skin_id,
-                `SkinnedMesh '${mesh.name}' is already bound to skin ${existing}; unbind before rebinding`
-            );
-            return;
-        }
-
-        this.#skin_id_by_mesh.set(mesh, skin_id);
-        const clone_metadata = this.#ensure_clone(mesh);
-        this.#try_register_binding(mesh, clone_metadata);
-    }
-
-    /**
-     * Skin id currently bound to this mesh, or `undefined` if the
-     * mesh hasn't been bound. Read-only accessor — bookkeeping lives
-     * here, not on the mesh.
-     *
-     * @param {SkinnedMesh} mesh
-     * @returns {number|undefined}
-     */
-    get_skin_id(mesh) {
-        return this.#skin_id_by_mesh.get(mesh);
-    }
-
-    /**
-     * Drop the binding for a single mesh. The mesh's geometry clone
-     * stays allocated (deallocation needs compaction work the MVP
-     * doesn't do), but the per-frame deformation no longer runs for
-     * it — its vertices freeze at whatever the last skinning pass
-     * wrote.
-     *
-     * No-op if the mesh isn't bound.
-     *
-     * @param {SkinnedMesh} mesh
-     */
-    unbind(mesh) {
-        if (!this.#skin_id_by_mesh.has(mesh)) return;
-        this.#skin_id_by_mesh.delete(mesh);
-
-        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;
-                break;
-            }
-        }
-    }
-
-    /**
-     * Drop every binding that points at the given skin id. Called
-     * by {@link GPUAnimationManager#unregister_skin} so freeing the
-     * skin's GPU rows also tears down the meshes' deformation
-     * registrations (which would otherwise try to look up the freed
-     * skin's matrix offset on the next bindings upload and assert).
-     *
-     * @param {number} skin_id
-     */
-    unbind_all_by_skin(skin_id) {
-        for (let i = this.#bindings.length - 1; i >= 0; i--) {
-            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;
-            }
-        }
-    }
-
-    /**
-     * Lookup-or-create the per-mesh clone metadata. Cached so that
-     * repeated lookups (binding-registration, geometry id resolution
-     * via obtain_geometry_index) hit the same record without
-     * re-cloning the source.
-     *
-     * @param {SkinnedMesh} mesh
-     * @returns {GPUGeometryMetadata}
-     */
-    #ensure_clone(mesh) {
-        let clone_metadata = this.#clones.get(mesh);
-        if (clone_metadata === undefined) {
-            clone_metadata = this.#geometries.add_clone(mesh.geometry);
-            this.#clones.set(mesh, clone_metadata);
-        }
-        return clone_metadata;
-    }
-
-    /**
-     * Register a binding for this mesh if conditions allow:
-     *   - the mesh has been bound to a skin via {@link bind}, AND
-     *   - we haven't already registered the binding for this mesh.
-     *
-     * @param {SkinnedMesh} mesh
-     * @param {GPUGeometryMetadata} clone_metadata
-     */
-    #try_register_binding(mesh, clone_metadata) {
-        const skin_id = this.#skin_id_by_mesh.get(mesh);
-        if (skin_id === undefined) return;
-        // The binding's presence in #bindings is the source of truth
-        // for "already registered". Cheap O(bindings) scan; bindings
-        // are O(skinned-mesh-count).
-        for (let i = 0; i < this.#bindings.length; i++) {
-            if (this.#bindings[i].mesh === mesh) return;
-        }
-
-        this.#register_binding(mesh, clone_metadata, skin_id);
-    }
-
-    /**
-     * Per-frame: upload any new bindings + dispatch the skinning
-     * compute pass that deforms cloned vertex regions in place.
-     *
-     * No-op if no bindings have been registered. Upload is skipped
-     * when nothing's changed since the last call. Must run after
-     * `shader_skin_matrix_prep` (which fills the skin matrices the
-     * deformation reads) and before any pass that consumes the
-     * skinned vertex data.
-     *
-     * The animation manager passed at construction supplies
-     * `skin_matrices_buffer` and resolves `skin_id` →
-     * `skin_matrix_offset` for the binding records.
-     *
-     * @param {ShadeGPUCommandContext} cmd_ctx
-     */
-    update(cmd_ctx) {
-        if (this.#bindings.length === 0) {
-            return;
-        }
-
-        // Flush any meshlet-clone work that hasn't been drained yet —
-        // typically happens on the first frame a fresh SkinnedMesh
-        // appears, when scene.build queues a clone in `pending_clones`
-        // but the per-frame `graphics.update` flush already ran earlier
-        // in the same frame. Without this, the skinning shader would
-        // read the cloned meshlet record before its `address` field
-        // got memcpy'd + patched (zero-initialized backing buffer →
-        // address 0), and writes would land at the start of the data
-        // buffer, corrupting whatever geometry sits there. Idempotent /
-        // no-op when nothing's pending, so repeat calls in subsequent
-        // frames are free.
-        //
-        // We call directly into `geometries.meshlets.update` rather
-        // than `geometries.update`: the latter also rebuilds the
-        // geometry metadata buffer (destroying + recreating it) when
-        // `__needs_update` is set, but the FrameGraph passes that
-        // already encoded into this cmd_ctx have captured the old
-        // buffer reference. Destroying it mid-cmd-context produces a
-        // "used in submit while destroyed" validation error. The
-        // metadata-buffer rebuild is the *next* GraphicsContext.update's
-        // job; here we just need the meshlet pending-clone flush.
-        this.#geometries.meshlets.update(cmd_ctx);
-
-        // The binding record carries a meshes-table row, and that table reuses rows: a scene the
-        // mesh left and re-entered puts it somewhere else, and every other binding's row can move
-        // out from under it too. So the records are re-resolved whenever the table's membership has
-        // changed since they were written, not only when a binding was added or dropped.
-        const mesh_rows_version = this.#scene_context.mesh_rows_version;
-
-        if (this.#bindings_dirty || this.#uploaded_mesh_rows_version !== mesh_rows_version) {
-            this.#upload_bindings();
-
-            this.#uploaded_mesh_rows_version = mesh_rows_version;
-        }
-
-        if (this.#bindings_dirty) {
-            // Neither of these reads anything outside the binding list, so a scene edit that left
-            // the list alone cannot have moved them.
-            this.#upload_dispatch_lookup();
-            this.#upload_prev_position_offsets();
-            this.#bindings_dirty = false;
-        }
-
-        const meshlets = this.#geometries.meshlets;
-        const total = this.#total_meshlet_count;
-        const binding_count = this.#bindings.length;
-        const max_workgroups = this.#device.limits.maxComputeWorkgroupsPerDimension;
-
-        // ── Skinning: deform the cloned vertex regions ────────────
-        //
-        // WebGPU's `dispatchWorkgroups` is capped at the device's
-        // `maxComputeWorkgroupsPerDimension` (65535 is the spec
-        // minimum; modern desktop GPUs typically report higher).
-        // With one workgroup per (binding, meshlet) pair, a busy
-        // scene (e.g. a grid of skinned characters) can exceed that
-        // — 324 dancers × ~220 meshlets each ≈ 71K pairs.
-        //
-        // Split into sub-dispatches when needed, passing
-        // `dispatch_offset` so the shader's lookup-index arithmetic
-        // keeps indexing a flat `dispatch_lookup` table. The encoded
-        // cost grows linearly in sub-dispatch count, but the GPU
-        // work is identical to a single huge dispatch.
-        for (let offset = 0; offset < total; offset += max_workgroups) {
-            const this_chunk = Math.min(max_workgroups, total - offset);
-            const dispatch_offset = cmd_ctx.allocateTransientValueBuffer(u32, offset);
-
-            shader_meshlet_apply_skinning.dispatch({
-                encoder: cmd_ctx,
-                group_count_x: this_chunk,
-                bindings: {
-                    dispatch_offset,
-                    meshlet_data: meshlets.buffer_data,
-                    meshlet_metadata: meshlets.buffer_metadata,
-                    skin_matrices: this.#animation_manager.skin_matrices_buffer,
-                    prev_skin_matrices: this.#animation_manager.prev_skin_matrices_buffer,
-                    skinning_bindings: this.#bindings_buffer,
-                    dispatch_lookup: this.#dispatch_lookup_buffer,
-                    prev_position_offsets: this.#prev_position_offsets_buffer,
-                    prev_positions: this.#prev_positions_buffer,
-                    // Skinning shader reads the SkinnedMesh's
-                    // `transforms` row to source the live
-                    // mesh.transform_global for the post-DQ
-                    // position cancellation.
-                    scene_database: this.#scene_context.scene_database_buffer,
-                },
-            });
-        }
-
-        // ── Bounds refresh chain ──────────────────────────────────
-        //
-        // Animated clones move outside their source-encoded bounds;
-        // the rasterizer's per-meshlet AABB cull and per-mesh sphere
-        // cull would reject them until we refresh both. The chain
-        // here runs every frame the skinning dispatched anything
-        // (cheap when nothing changed: dispatch overhead only, the
-        // shaders early-out on the workgroup boundary).
-        //
-        // Order is load-bearing:
-        //   1. scatter  — reset meshlet.bounds_box / geometry.bounding_box to ±inf
-        //   2. reduce   — atomic-merge per-vertex into meshlet + geometry box
-        //   3. derive   — geometry box → geometry sphere (per binding)
-        //   4. mesh     — geometry box+sphere → world-space mesh bounds (per binding)
-        //
-        // The same `dispatch_lookup` table that drove the skinning
-        // dispatch above also drives the scatter and reduce dispatches
-        // — every (binding, meshlet) pair gets exactly the same set
-        // of workgroups, just running different shaders.
-        const geometry_metadata_buffer = this.#geometries.buffer_metadata;
-        const scene_database_buffer = this.#scene_context.scene_database_buffer;
-
-        // ── 1. Scatter: ±inf sentinels into meshlet + geometry bounds.
-        // Linear-thread dispatch: WG_SIZE threads per workgroup, one
-        // thread per pair. With WG_SIZE = 64 the workgroup count is
-        // ceil(total/64) — single sub-dispatch except at extreme
-        // scale (~4M pairs).
-        {
-            const total_workgroups = Math.ceil(total / BOUNDS_SCATTER_WORKGROUP_SIZE);
-            for (let offset_wg = 0; offset_wg < total_workgroups; offset_wg += max_workgroups) {
-                const this_chunk = Math.min(max_workgroups, total_workgroups - offset_wg);
-                // dispatch_offset is in *pair* units for scatter — the
-                // shader does `gid.x + dispatch_offset`.
-                const dispatch_offset = cmd_ctx.allocateTransientValueBuffer(
-                    u32,
-                    offset_wg * BOUNDS_SCATTER_WORKGROUP_SIZE
-                );
-                const total_pair_count = cmd_ctx.allocateTransientValueBuffer(u32, total);
-                shader_meshlet_bounds_scatter.dispatch({
-                    encoder: cmd_ctx,
-                    group_count_x: this_chunk,
-                    bindings: {
-                        dispatch_offset,
-                        total_pair_count,
-                        skinning_bindings: this.#bindings_buffer,
-                        dispatch_lookup: this.#dispatch_lookup_buffer,
-                        meshlet_metadata_atomic: meshlets.buffer_metadata,
-                        geometry_metadata_atomic: geometry_metadata_buffer,
-                    },
-                });
-            }
-        }
-
-        // ── 2. Reduce: per-meshlet workgroup, merges into meshlet +
-        // geometry box atomically. Same workgroup-per-pair pattern as
-        // skinning; same pagination.
-        for (let offset = 0; offset < total; offset += max_workgroups) {
-            const this_chunk = Math.min(max_workgroups, total - offset);
-            const dispatch_offset = cmd_ctx.allocateTransientValueBuffer(u32, offset);
-
-            shader_meshlet_bounds_reduce.dispatch({
-                encoder: cmd_ctx,
-                group_count_x: this_chunk,
-                bindings: {
-                    dispatch_offset,
-                    skinning_bindings: this.#bindings_buffer,
-                    dispatch_lookup: this.#dispatch_lookup_buffer,
-                    meshlet_data: meshlets.buffer_data,
-                    meshlet_metadata_atomic: meshlets.buffer_metadata,
-                    geometry_metadata_atomic: geometry_metadata_buffer,
-                },
-            });
-        }
-
-        // ── 3. Sphere derive: per binding, geometry box → sphere.
-        // Linear-thread dispatch, sized to ceil(binding_count/64).
-        // Binding count is small (one per active SkinnedMesh, so
-        // hundreds at most), single sub-dispatch always suffices.
-        {
-            const total_workgroups = Math.ceil(binding_count / SPHERE_DERIVE_WORKGROUP_SIZE);
-            if (total_workgroups > 0) {
-                const binding_count_u = cmd_ctx.allocateTransientValueBuffer(u32, binding_count);
-                shader_geometry_sphere_derive.dispatch({
-                    encoder: cmd_ctx,
-                    group_count_x: total_workgroups,
-                    bindings: {
-                        binding_count: binding_count_u,
-                        skinning_bindings: this.#bindings_buffer,
-                        geometry_metadata_atomic: geometry_metadata_buffer,
-                    },
-                });
-            }
-        }
-
-        // ── 4. Mesh-instance bounds: per binding, geometry → world
-        // mesh bounds. Reuses the existing per-mesh bounds chunk
-        // (sphere radius scaled by max-column-length of the
-        // transform 3×3, conservative under non-uniform scale).
-        {
-            const total_workgroups = Math.ceil(binding_count / MESH_BOUNDS_REFRESH_WORKGROUP_SIZE);
-            if (total_workgroups > 0) {
-                const binding_count_u = cmd_ctx.allocateTransientValueBuffer(u32, binding_count);
-                shader_skinned_mesh_bounds_refresh.dispatch({
-                    encoder: cmd_ctx,
-                    group_count_x: total_workgroups,
-                    bindings: {
-                        binding_count: binding_count_u,
-                        skinning_bindings: this.#bindings_buffer,
-                        scene_database: scene_database_buffer,
-                        geometries: geometry_metadata_buffer,
-                    },
-                });
-            }
-        }
-    }
-
-    /**
-     * @param {SkinnedMesh} mesh
-     * @param {GPUGeometryMetadata} clone_metadata
-     * @param {number} skin_id
-     */
-    #register_binding(mesh, clone_metadata, skin_id) {
-        const source_metadata = this.#geometries.get_metadata(mesh.geometry);
-        assert.defined(source_metadata, 'source_metadata');
-
-        const meshlet_count = clone_metadata.meshlets.meshlet_count;
-        const clone_meshlet_metadata_offset = clone_metadata.meshlets.metadata.offset;
-
-        this.#bindings.push({
-            skin_id,
-            mesh,
-            source_meshlet_metadata_offset: source_metadata.meshlets.metadata.offset,
-            clone_meshlet_metadata_offset,
-            meshlet_count,
-            clone_geometry_index: clone_metadata.index,
-        });
-        this.#total_meshlet_count += meshlet_count;
-        this.#bindings_dirty = true;
-
-        // ── Prev-position side-buffer bookkeeping ────────────────
-        //
-        // Walk the source's CPU metadata bytes to sum vertex counts
-        // (source and clone share the same vertex counts per
-        // meshlet — the clone is a memcpy of the source data). Each
-        // clone meshlet gets a contiguous (vertex_count × 3 u32)
-        // slot in the prev_positions side-buffer; record its base
-        // word offset in the per-meshlet offsets table indexed by
-        // absolute clone meshlet metadata row.
-        //
-        // `metadata_buffer_original` comes from `BinaryBuffer.data`
-        // and IS the raw `ArrayBuffer` (not a typed-array view), so
-        // we wrap it in a DataView directly without dereferencing
-        // a `.buffer` property.
-        const metadata_bytes = source_metadata.meshlets.metadata_buffer_original;
-        const view = new DataView(metadata_bytes);
-
-        // Phase 1: sum total vertices so we can grow the side-buffer
-        // up front, before recording per-meshlet offsets.
-        let total_vertices = 0;
-        for (let i = 0; i < meshlet_count; i++) {
-            const vc = view.getUint32(i * MESHLET_STRIDE_BYTES + MESHLET_VERTEX_COUNT_BYTE_OFFSET, true);
-            total_vertices += vc;
-        }
-
-        const base_vertex_offset = this.#next_prev_position_vertex_offset;
-        this.#next_prev_position_vertex_offset += 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)
-        // to u32-word offset (× 3) since the side-buffer stores
-        // 3 × f32 per vertex back-to-back.
-        let cumulative_vertex_offset = 0;
-        for (let i = 0; i < meshlet_count; i++) {
-            const vc = view.getUint32(i * MESHLET_STRIDE_BYTES + MESHLET_VERTEX_COUNT_BYTE_OFFSET, true);
-            const meshlet_word_offset = (base_vertex_offset + cumulative_vertex_offset) * 3;
-            this.#prev_position_offsets_cpu[clone_meshlet_metadata_offset + i] = meshlet_word_offset;
-            cumulative_vertex_offset += vc;
-        }
-    }
-
-    /**
-     * Grow {@link #prev_positions_buffer} to fit at least
-     * `required_vertices` vertices. Doubles from
-     * {@link PREV_POSITIONS_INITIAL_CAPACITY_VERTICES}. The buffer's
-     * contents are scratch (rewritten every frame by the skinning
-     * compute pass), so growth doesn't copy data — but the reference
-     * is invalidated, so callers must re-fetch through the getter.
-     *
-     * @param {number} required_vertices
-     */
-    #ensure_prev_positions_capacity_vertices(required_vertices) {
-        if (this.#prev_positions_buffer !== null && required_vertices <= this.#prev_positions_capacity_vertices) {
-            return;
-        }
-
-        let new_capacity = Math.max(
-            this.#prev_positions_capacity_vertices,
-            PREV_POSITIONS_INITIAL_CAPACITY_VERTICES,
-        );
-        while (new_capacity < required_vertices) {
-            new_capacity *= 2;
-        }
-
-        if (this.#prev_positions_buffer !== null) {
-            this.#prev_positions_buffer.destroy();
-        }
-
-        // 3 × u32 per vertex (each u32 carries an f32 bit pattern).
-        this.#prev_positions_buffer = this.#device.createBuffer({
-            label: 'GPUMeshSkinningContext/PrevPositions',
-            size: new_capacity * 3 * 4,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
-        });
-        this.#prev_positions_capacity_vertices = new_capacity;
-    }
-
-    /**
-     * Grow {@link #prev_position_offsets_buffer} (and its CPU
-     * shadow) to cover at least `required_records` meshlet metadata
-     * rows. Entries beyond previously written ones default to
-     * {@link PREV_POSITION_OFFSET_INVALID} so non-clone meshlets
-     * read as "no prev-position data, fall back".
-     *
-     * @param {number} required_records
-     */
-    #ensure_prev_position_offsets_capacity(required_records) {
-        if (this.#prev_position_offsets_buffer !== null && required_records <= this.#prev_position_offsets_capacity) {
-            return;
-        }
-
-        let new_capacity = Math.max(
-            this.#prev_position_offsets_capacity,
-            PREV_POSITION_OFFSETS_INITIAL_CAPACITY,
-        );
-        while (new_capacity < required_records) {
-            new_capacity *= 2;
-        }
-
-        // Re-allocate CPU shadow, copy old entries, fill new with
-        // sentinel.
-        const new_cpu = new Uint32Array(new_capacity);
-        new_cpu.fill(PREV_POSITION_OFFSET_INVALID);
-        new_cpu.set(this.#prev_position_offsets_cpu);
-        this.#prev_position_offsets_cpu = new_cpu;
-
-        if (this.#prev_position_offsets_buffer !== null) {
-            this.#prev_position_offsets_buffer.destroy();
-        }
-
-        this.#prev_position_offsets_buffer = this.#device.createBuffer({
-            label: 'GPUMeshSkinningContext/PrevPositionOffsets',
-            size: new_capacity * 4,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-        });
-        this.#prev_position_offsets_capacity = new_capacity;
-    }
-
-    /**
-     * Re-upload the entire {@link #prev_position_offsets_cpu} shadow
-     * to the GPU offsets buffer. Called when a new binding has
-     * registered new entries (rare — bindings register once, not
-     * per frame). Whole-buffer upload because the buffer is small
-     * (one u32 per meshlet metadata row, hundreds of KB at typical
-     * stress-test scale).
-     */
-    #upload_prev_position_offsets() {
-        if (this.#prev_position_offsets_buffer === null) {
-            return;
-        }
-        this.#device.queue.writeBuffer(
-            this.#prev_position_offsets_buffer,
-            0,
-            this.#prev_position_offsets_cpu.buffer,
-            0,
-            this.#prev_position_offsets_capacity * 4,
-        );
-    }
-
-    /**
-     * Resolve every CPU binding into GPU bytes (looking up
-     * `skin_matrix_offset` from the animation manager) and upload to
-     * the bindings buffer. Grows the buffer first if the binding
-     * count has outgrown its capacity.
-     */
-    #upload_bindings() {
-        const binding_count = this.#bindings.length;
-        const struct_size = SKINNING_BINDING_STRUCT.aligned_size;
-
-        if (binding_count > this.#bindings_capacity) {
-            let new_capacity = Math.max(this.#bindings_capacity, BINDINGS_INITIAL_CAPACITY);
-            while (new_capacity < binding_count) {
-                new_capacity *= 2;
-            }
-
-            if (this.#bindings_buffer !== null) {
-                this.#bindings_buffer.destroy();
-            }
-
-            this.#bindings_buffer = this.#device.createBuffer({
-                label: 'GPUMeshSkinningContext/Bindings',
-                size: new_capacity * struct_size,
-                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-            });
-            this.#bindings_capacity = new_capacity;
-        }
-
-        const data = new ArrayBuffer(binding_count * struct_size);
-        for (let i = 0; i < binding_count; i++) {
-            const b = this.#bindings[i];
-
-            // The meshes table is asked for the row rather than having it
-            // derived from the transforms row: every node earns a
-            // transforms row and only the geometry-bearing ones earn a
-            // mesh row, so the two tables run at different rates as soon
-            // as the scene holds a group, an anchor or a joint — which is
-            // every glTF. A bound mesh is in the scene: assertion catches
-            // both a SkinnedMesh scene.build has not seen yet and one that
-            // left the scene without being unbound, either of which would
-            // otherwise reach the shader as a garbage row.
-            const mesh_instance_index = this.#scene_context.mesh_row_of(b.mesh);
-            assert.isNonNegativeInteger(
-                mesh_instance_index,
-                `SkinnedMesh '${b.mesh.name}' (id=${b.mesh.id}) has no meshes-table row — scene.build must run before skinning bindings upload`
-            );
-
-            write_gpu_typed_buffer({
-                skin_matrix_offset: this.#animation_manager.get_skin_matrix_offset(b.skin_id),
-                source_meshlet_metadata_offset: b.source_meshlet_metadata_offset,
-                clone_meshlet_metadata_offset: b.clone_meshlet_metadata_offset,
-                meshlet_count: b.meshlet_count,
-                clone_geometry_index: b.clone_geometry_index,
-                mesh_instance_index,
-            }, SKINNING_BINDING_STRUCT, data, i * struct_size);
-        }
-
-        this.#device.queue.writeBuffer(this.#bindings_buffer, 0, data);
-    }
-
-    /**
-     * Build the flat `(binding_index, meshlet_local_index)` table —
-     * one pair per workgroup the skinning dispatch will spawn — and
-     * upload to the dispatch-lookup buffer (growing it if needed).
-     */
-    #upload_dispatch_lookup() {
-        const total = this.#total_meshlet_count;
-
-        if (total > this.#dispatch_lookup_capacity) {
-            let new_capacity = Math.max(this.#dispatch_lookup_capacity, DISPATCH_LOOKUP_INITIAL_CAPACITY);
-            while (new_capacity < total) {
-                new_capacity *= 2;
-            }
-
-            if (this.#dispatch_lookup_buffer !== null) {
-                this.#dispatch_lookup_buffer.destroy();
-            }
-
-            this.#dispatch_lookup_buffer = this.#device.createBuffer({
-                label: 'GPUMeshSkinningContext/DispatchLookup',
-                // 8 bytes per pair (two u32s).
-                size: new_capacity * 8,
-                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-            });
-            this.#dispatch_lookup_capacity = new_capacity;
-        }
-
-        const data = new Uint32Array(total * 2);
-        let cursor = 0;
-        for (let b = 0; b < this.#bindings.length; b++) {
-            const binding = this.#bindings[b];
-            for (let m = 0; m < binding.meshlet_count; m++) {
-                data[cursor++] = b;
-                data[cursor++] = m;
-            }
-        }
-
-        this.#device.queue.writeBuffer(this.#dispatch_lookup_buffer, 0, data);
-    }
-
-    destroy() {
-        if (this.#bindings_buffer !== null) {
-            this.#bindings_buffer.destroy();
-            this.#bindings_buffer = null;
-        }
-        if (this.#dispatch_lookup_buffer !== null) {
-            this.#dispatch_lookup_buffer.destroy();
-            this.#dispatch_lookup_buffer = null;
-        }
-        if (this.#prev_positions_buffer !== null) {
-            this.#prev_positions_buffer.destroy();
-            this.#prev_positions_buffer = null;
-        }
-        if (this.#prev_position_offsets_buffer !== null) {
-            this.#prev_position_offsets_buffer.destroy();
-            this.#prev_position_offsets_buffer = null;
-        }
-    }
-}
+import { assert } from "../../../../core/assert.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { write_gpu_typed_buffer } from "../../shader/type/serde/write_gpu_typed_buffer.js";
+import {
+    shader_geometry_sphere_derive,
+    WORKGROUP_SIZE as SPHERE_DERIVE_WORKGROUP_SIZE,
+} from "./bounds_refresh/shader_geometry_sphere_derive.js";
+import {
+    shader_meshlet_bounds_reduce,
+    WORKGROUP_SIZE as BOUNDS_REDUCE_WORKGROUP_SIZE,
+} from "./bounds_refresh/shader_meshlet_bounds_reduce.js";
+import {
+    shader_meshlet_bounds_scatter,
+    WORKGROUP_SIZE as BOUNDS_SCATTER_WORKGROUP_SIZE,
+} from "./bounds_refresh/shader_meshlet_bounds_scatter.js";
+import {
+    shader_skinned_mesh_bounds_refresh,
+    WORKGROUP_SIZE as MESH_BOUNDS_REFRESH_WORKGROUP_SIZE,
+} from "./bounds_refresh/shader_skinned_mesh_bounds_refresh.js";
+import {
+    SKINNING_BINDING_STRUCT
+} from "./SKINNING_BINDING_STRUCT.js";
+import {
+    shader_meshlet_apply_skinning
+} from "./shader_meshlet_apply_skinning.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+
+/**
+ * Initial bindings-buffer capacity (in binding records). 16 × 16 bytes
+ * = 256 bytes — wasteful for a scene with no SkinnedMesh, but the
+ * doubling growth absorbs any larger scene cheaply.
+ */
+const BINDINGS_INITIAL_CAPACITY = 16;
+
+/**
+ * Initial dispatch-lookup capacity (in `(binding_index, meshlet_local)`
+ * pairs, i.e. 8 bytes per slot). Sized to the same default a small
+ * skinned mesh produces.
+ */
+const DISPATCH_LOOKUP_INITIAL_CAPACITY = 256;
+
+/**
+ * Initial `prev_positions_buffer` capacity in vertices. Each vertex
+ * is 3 × f32 = 12 bytes. 1024 vertices → 12 KB. Doubles on grow.
+ */
+const PREV_POSITIONS_INITIAL_CAPACITY_VERTICES = 1024;
+
+/**
+ * Initial `prev_position_offsets_buffer` capacity in u32 records
+ * (one per meshlet metadata row). 1024 × 4 = 4 KB. Doubles on grow.
+ */
+const PREV_POSITION_OFFSETS_INITIAL_CAPACITY = 1024;
+
+/**
+ * Sentinel value in `prev_position_offsets` for meshlet metadata
+ * rows that are NOT skinned clones — sources, static-mesh geometries,
+ * pre-skinning clones (rare), etc. The skinning shader sees this
+ * value and skips its `position_prev` write; the velocity post-pass
+ * sees it and falls back to the rigid per-object math.
+ */
+const PREV_POSITION_OFFSET_INVALID = 0xFFFFFFFF;
+
+/**
+ * f32 vertex_count byte offset within MESHLET_METADATA_STRUCT, resolved
+ * at module load (after `.pack()` reorders fields). Used by the CPU
+ * binding-registration path to walk the source's metadata bytes and
+ * sum vertex counts for prev-position side-buffer allocation.
+ */
+const MESHLET_VERTEX_COUNT_BYTE_OFFSET = MESHLET_METADATA_STRUCT.get('vertex_count').offset;
+const MESHLET_STRIDE_BYTES = MESHLET_METADATA_STRUCT.aligned_size;
+
+/**
+ * Per-scene container for the skinning subsystem's state. Owned by
+ * {@link GPUSceneContext}; receives the scene's
+ * {@link GPUGeometryManager} so it can allocate per-instance geometry
+ * clones for {@link SkinnedMesh} instances and route the skinning
+ * compute pass against those clones.
+ *
+ * Three responsibilities:
+ *  1. Geometry-clone routing — `obtain_geometry_index(mesh)` returns
+ *     the clone id for SkinnedMesh, the source id for everyone else.
+ *  2. Skinning binding bookkeeping — each SkinnedMesh with a `skin_id`
+ *     produces one binding record linking its clone's vertex region
+ *     back to the source's data and to the skin's matrix range.
+ *  3. Per-frame dispatch — `update(cmd_ctx, animation_manager)`
+ *     uploads any new bindings and dispatches the skinning compute
+ *     pass that deforms the cloned vertex regions in place.
+ *
+ * The CPU-side binding records cache `skin_id` rather than
+ * `skin_matrix_offset` because the offset is owned by the animation
+ * manager. Resolution happens at upload time via
+ * `animation_manager.get_skin_matrix_offset(skin_id)`.
+ */
+export class GPUMeshSkinningContext {
+
+    /** @type {GPUDevice} */
+    #device;
+
+    /** @type {GPUGeometryManager} */
+    #geometries;
+
+    /** @type {GPUAnimationManager} */
+    #animation_manager;
+
+    /**
+     * Per-SkinnedMesh clone metadata, cached so repeated lookups
+     * (binding-registration, geometry id resolution) hit the same
+     * record rather than re-cloning the source. Persists across
+     * scene rebuilds (unlike id_mapping).
+     *
+     * @type {Map<SkinnedMesh, GPUGeometryMetadata>}
+     */
+    #clones = new Map();
+
+    /**
+     * Per-mesh skin assignment. Populated by {@link bind}; consumed
+     * by {@link #register_binding} when it stamps the GPU binding
+     * record. A mesh present here has had a skinning binding
+     * registered exactly once — re-binding the same mesh is a
+     * no-op (the existing binding stands).
+     *
+     * Held here rather than on the {@link SkinnedMesh} so the public
+     * mesh class doesn't carry GPU-side state; consumers who need
+     * to look up "what skin is mesh X bound to?" can query via
+     * {@link get_skin_id}.
+     *
+     * @type {Map<SkinnedMesh, number>}
+     */
+    #skin_id_by_mesh = new Map();
+
+    /**
+     * One CPU record per `(SkinnedMesh, clone)` binding registered via
+     * {@link #register_binding}. Resolved into GPU bytes at upload
+     * time — `skin_id` becomes `skin_matrix_offset` via
+     * {@link GPUAnimationManager#get_skin_matrix_offset}, and `mesh`
+     * becomes a meshes-table row via
+     * {@link GPUSceneContext#mesh_row_of}. The mesh is held rather
+     * than its row because the row is not stable: registration
+     * happens before the scene has placed the mesh at all, and the
+     * table reuses rows afterwards.
+     *
+     * Append-only in this MVP — removing a SkinnedMesh leaks its
+     * binding (alongside its clone). Acceptable at the lifetime-
+     * distinct-instance scale; phase-4 frees both together.
+     *
+     * @type {{
+     *     skin_id: number,
+     *     mesh: SkinnedMesh,
+     *     source_meshlet_metadata_offset: number,
+     *     clone_meshlet_metadata_offset: number,
+     *     meshlet_count: number,
+     *     clone_geometry_index: number,
+     * }[]}
+     */
+    #bindings = [];
+
+    /**
+     * Sum of {@link #bindings}[i].meshlet_count — the dispatch-lookup
+     * length and the workgroup count for the skinning compute pass.
+     * Tracked incrementally to avoid re-summing per frame.
+     * @type {number}
+     */
+    #total_meshlet_count = 0;
+
+    /**
+     * Set when {@link #bindings} has changed since the last upload.
+     * Cleared by {@link update} after re-uploading both the bindings
+     * buffer and the dispatch-lookup buffer.
+     * @type {boolean}
+     */
+    #bindings_dirty = false;
+
+    /**
+     * The scene context's {@link GPUSceneContext#mesh_rows_version} as of the last bindings upload.
+     * The records hold meshes-table rows and that table reuses them, so a difference here means
+     * every record's row has to be resolved again.
+     *
+     * @type {number}
+     */
+    #uploaded_mesh_rows_version = -1;
+
+    /**
+     * GPU mirror of {@link #bindings}, with `skin_id` resolved to
+     * `skin_matrix_offset`. `null` until the first binding is
+     * registered.
+     * @type {GPUBuffer|null}
+     */
+    #bindings_buffer = null;
+
+    /**
+     * Capacity of {@link #bindings_buffer} in binding records. Grows
+     * by doubling when a new binding pushes past it.
+     * @type {number}
+     */
+    #bindings_capacity = 0;
+
+    /**
+     * Flat `(binding_index, meshlet_local_index)` u32 pairs — one pair
+     * per workgroup. The skinning shader reads `dispatch_lookup[wg_id]`
+     * to figure out which (binding, meshlet) it's processing.
+     * @type {GPUBuffer|null}
+     */
+    #dispatch_lookup_buffer = null;
+
+    /**
+     * Capacity of {@link #dispatch_lookup_buffer} in `(binding,
+     * meshlet)` pairs (i.e. half the u32 count). Grows by doubling.
+     * @type {number}
+     */
+    #dispatch_lookup_capacity = 0;
+
+    /**
+     * Side-buffer holding the previous-frame mesh-local skinned
+     * positions for every clone meshlet's vertices. Laid out as
+     * tightly-packed `vec3<f32>` (3 × u32 words, f32 bit pattern)
+     * per vertex; each clone meshlet owns a contiguous slice of
+     * `vertex_count` vec3s starting at the offset recorded in
+     * {@link #prev_position_offsets_buffer}.
+     *
+     * Written by the skinning compute shader (using the manager's
+     * `prev_skin_matrices_buffer`), read by the velocity post-pass
+     * to interpolate per-vertex skin deformation across the rasterized
+     * triangle.
+     *
+     * Append-only — bindings reserve contiguous vertex ranges via
+     * {@link #next_prev_position_vertex_offset}; nothing frees.
+     *
+     * @type {GPUBuffer|null}
+     */
+    #prev_positions_buffer = null;
+
+    /**
+     * Capacity of {@link #prev_positions_buffer} in vertices (each
+     * vertex = 3 × u32 words).
+     * @type {number}
+     */
+    #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.
+     * @type {number}
+     */
+    #next_prev_position_vertex_offset = 0;
+
+    /**
+     * Per-meshlet base offset (in u32 words) into
+     * {@link #prev_positions_buffer}. Indexed by absolute meshlet
+     * metadata row — `prev_position_offsets[meshlet_index]` gives
+     * either {@link PREV_POSITION_OFFSET_INVALID} (non-clone or
+     * not-yet-bound meshlet) or the first u32 word of that
+     * meshlet's prev-position slice.
+     *
+     * Sized to the meshlet metadata buffer's record capacity (or
+     * larger). Re-uploaded from the CPU shadow whenever a new
+     * binding adds entries.
+     *
+     * @type {GPUBuffer|null}
+     */
+    #prev_position_offsets_buffer = null;
+
+    /**
+     * Capacity of {@link #prev_position_offsets_buffer} in u32
+     * records (= one per meshlet metadata row).
+     * @type {number}
+     */
+    #prev_position_offsets_capacity = 0;
+
+    /**
+     * CPU shadow of {@link #prev_position_offsets_buffer}. Mutated
+     * by {@link #register_binding} when computing per-meshlet offsets;
+     * re-uploaded wholesale by {@link #upload_prev_position_offsets}.
+     * Entries default to {@link PREV_POSITION_OFFSET_INVALID}.
+     *
+     * @type {Uint32Array}
+     */
+    #prev_position_offsets_cpu = new Uint32Array(0);
+
+    /**
+     * Back-reference to the owning {@link GPUSceneContext} so the
+     * bindings-upload path can resolve a mesh to its meshes-table row
+     * via {@link GPUSceneContext#mesh_row_of} without the caller
+     * threading that lookup through every `bind()` call.
+     *
+     * Resolution cannot happen at registration time: `bind` and
+     * `obtain_geometry_index` both run before `scene.build` has given
+     * the mesh a row. Nor does resolving once suffice — the table
+     * hands out the lowest free row, so a mesh that leaves and
+     * re-enters the scene lands somewhere else, which is what
+     * {@link GPUSceneContext#mesh_rows_version} is compared for.
+     *
+     * @type {GPUSceneContext}
+     */
+    #scene_context;
+
+    /**
+     * @param {{
+     *     geometries: GPUGeometryManager,
+     *     animation_manager: GPUAnimationManager,
+     *     scene_context: GPUSceneContext,
+     *     device: GPUDevice,
+     * }} args
+     */
+    constructor({ geometries, animation_manager, scene_context, device }) {
+        assert.defined(geometries, 'geometries');
+        assert.defined(animation_manager, 'animation_manager');
+        assert.defined(scene_context, 'scene_context');
+        assert.defined(device, 'device');
+
+        this.#geometries = geometries;
+        this.#animation_manager = animation_manager;
+        this.#scene_context = scene_context;
+        this.#device = device;
+    }
+
+    /**
+     * Side-buffer of previous-frame mesh-local skinned positions for
+     * the velocity post-pass. `null` until the first skinning binding
+     * has been registered.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get prev_positions_buffer() {
+        return this.#prev_positions_buffer;
+    }
+
+    /**
+     * 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
+     * registered and uploaded.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get bindings_buffer() {
+        return this.#bindings_buffer;
+    }
+
+    /**
+     * Per-meshlet base offsets into {@link prev_positions_buffer},
+     * indexed by absolute meshlet metadata row. Non-clone meshlets
+     * hold the sentinel `0xFFFFFFFF`. `null` until the first
+     * skinning binding has been registered.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get prev_position_offsets_buffer() {
+        return this.#prev_position_offsets_buffer;
+    }
+
+    /**
+     * Geometry id to assign to this mesh's instance record. Idempotent.
+     *
+     * - For a {@link SkinnedMesh}: a per-instance clone of the source's
+     *   GPU geometry. The first time we see a given mesh, allocate a
+     *   clone; subsequent calls return the cached id. If the mesh has
+     *   already been bound to a skin via {@link bind}, the binding's
+     *   registration also runs here so scene.build's first sight of
+     *   a pre-bound mesh doesn't strand it without a deformation pass.
+     * - For a regular {@link Mesh}: the source's id from the geometry
+     *   manager.
+     *
+     * @param {Mesh} mesh
+     * @returns {number}
+     */
+    obtain_geometry_index(mesh) {
+        if (mesh.isSkinnedMesh === true) {
+            const clone_metadata = this.#ensure_clone(mesh);
+            // If the mesh has already been bound (bind() ran before
+            // scene.build for this mesh), register its binding now.
+            // No-op if not yet bound or if the binding has already
+            // been registered in a previous call.
+            this.#try_register_binding(mesh, clone_metadata);
+            return clone_metadata.index;
+        }
+
+        this.#geometries.add(mesh.geometry);
+        return this.#geometries.getAddress(mesh.geometry);
+    }
+
+    /**
+     * Bind a {@link SkinnedMesh} to a skin. The mesh's clone (if not
+     * already allocated) is created on demand; a skinning-pass
+     * binding record is registered so the deformation runs each
+     * frame. The skin id is stored on the context (not on the mesh
+     * — `SkinnedMesh` carries no GPU state).
+     *
+     * Re-binding the same mesh with a different skin id is rejected
+     * (single-binding model in this MVP — use {@link unbind} first if
+     * you need to swap). Calling with the same skin id is a no-op.
+     *
+     * Tolerates being called before `scene.build` registers the mesh;
+     * the binding upload happens during the next per-frame
+     * {@link update}.
+     *
+     * @param {SkinnedMesh} mesh
+     * @param {number} skin_id
+     */
+    bind(mesh, skin_id) {
+        assert.defined(mesh, 'mesh');
+        assert.equal(mesh.isSkinnedMesh, true, 'mesh.isSkinnedMesh !== true');
+        assert.isNonNegativeInteger(skin_id, 'skin_id');
+
+        const existing = this.#skin_id_by_mesh.get(mesh);
+        if (existing !== undefined) {
+            assert.equal(
+                existing, skin_id,
+                `SkinnedMesh '${mesh.name}' is already bound to skin ${existing}; unbind before rebinding`
+            );
+            return;
+        }
+
+        this.#skin_id_by_mesh.set(mesh, skin_id);
+        const clone_metadata = this.#ensure_clone(mesh);
+        this.#try_register_binding(mesh, clone_metadata);
+    }
+
+    /**
+     * Skin id currently bound to this mesh, or `undefined` if the
+     * mesh hasn't been bound. Read-only accessor — bookkeeping lives
+     * here, not on the mesh.
+     *
+     * @param {SkinnedMesh} mesh
+     * @returns {number|undefined}
+     */
+    get_skin_id(mesh) {
+        return this.#skin_id_by_mesh.get(mesh);
+    }
+
+    /**
+     * Drop the binding for a single mesh. The mesh's geometry clone
+     * stays allocated (deallocation needs compaction work the MVP
+     * doesn't do), but the per-frame deformation no longer runs for
+     * it — its vertices freeze at whatever the last skinning pass
+     * wrote.
+     *
+     * No-op if the mesh isn't bound.
+     *
+     * @param {SkinnedMesh} mesh
+     */
+    unbind(mesh) {
+        if (!this.#skin_id_by_mesh.has(mesh)) return;
+        this.#skin_id_by_mesh.delete(mesh);
+
+        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;
+                break;
+            }
+        }
+    }
+
+    /**
+     * Drop every binding that points at the given skin id. Called
+     * by {@link GPUAnimationManager#unregister_skin} so freeing the
+     * skin's GPU rows also tears down the meshes' deformation
+     * registrations (which would otherwise try to look up the freed
+     * skin's matrix offset on the next bindings upload and assert).
+     *
+     * @param {number} skin_id
+     */
+    unbind_all_by_skin(skin_id) {
+        for (let i = this.#bindings.length - 1; i >= 0; i--) {
+            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;
+            }
+        }
+    }
+
+    /**
+     * Lookup-or-create the per-mesh clone metadata. Cached so that
+     * repeated lookups (binding-registration, geometry id resolution
+     * via obtain_geometry_index) hit the same record without
+     * re-cloning the source.
+     *
+     * @param {SkinnedMesh} mesh
+     * @returns {GPUGeometryMetadata}
+     */
+    #ensure_clone(mesh) {
+        let clone_metadata = this.#clones.get(mesh);
+        if (clone_metadata === undefined) {
+            clone_metadata = this.#geometries.add_clone(mesh.geometry);
+            this.#clones.set(mesh, clone_metadata);
+        }
+        return clone_metadata;
+    }
+
+    /**
+     * Register a binding for this mesh if conditions allow:
+     *   - the mesh has been bound to a skin via {@link bind}, AND
+     *   - we haven't already registered the binding for this mesh.
+     *
+     * @param {SkinnedMesh} mesh
+     * @param {GPUGeometryMetadata} clone_metadata
+     */
+    #try_register_binding(mesh, clone_metadata) {
+        const skin_id = this.#skin_id_by_mesh.get(mesh);
+        if (skin_id === undefined) return;
+        // The binding's presence in #bindings is the source of truth
+        // for "already registered". Cheap O(bindings) scan; bindings
+        // are O(skinned-mesh-count).
+        for (let i = 0; i < this.#bindings.length; i++) {
+            if (this.#bindings[i].mesh === mesh) return;
+        }
+
+        this.#register_binding(mesh, clone_metadata, skin_id);
+    }
+
+    /**
+     * Per-frame: upload any new bindings + dispatch the skinning
+     * compute pass that deforms cloned vertex regions in place.
+     *
+     * No-op if no bindings have been registered. Upload is skipped
+     * when nothing's changed since the last call. Must run after
+     * `shader_skin_matrix_prep` (which fills the skin matrices the
+     * deformation reads) and before any pass that consumes the
+     * skinned vertex data.
+     *
+     * The animation manager passed at construction supplies
+     * `skin_matrices_buffer` and resolves `skin_id` →
+     * `skin_matrix_offset` for the binding records.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     */
+    update(cmd_ctx) {
+        if (this.#bindings.length === 0) {
+            return;
+        }
+
+        // Flush any meshlet-clone work that hasn't been drained yet —
+        // typically happens on the first frame a fresh SkinnedMesh
+        // appears, when scene.build queues a clone in `pending_clones`
+        // but the per-frame `graphics.update` flush already ran earlier
+        // in the same frame. Without this, the skinning shader would
+        // read the cloned meshlet record before its `address` field
+        // got memcpy'd + patched (zero-initialized backing buffer →
+        // address 0), and writes would land at the start of the data
+        // buffer, corrupting whatever geometry sits there. Idempotent /
+        // no-op when nothing's pending, so repeat calls in subsequent
+        // frames are free.
+        //
+        // We call directly into `geometries.meshlets.update` rather
+        // than `geometries.update`: the latter also rebuilds the
+        // geometry metadata buffer (destroying + recreating it) when
+        // `__needs_update` is set, but the FrameGraph passes that
+        // already encoded into this cmd_ctx have captured the old
+        // buffer reference. Destroying it mid-cmd-context produces a
+        // "used in submit while destroyed" validation error. The
+        // metadata-buffer rebuild is the *next* GraphicsContext.update's
+        // job; here we just need the meshlet pending-clone flush.
+        this.#geometries.meshlets.update(cmd_ctx);
+
+        // The binding record carries a meshes-table row, and that table reuses rows: a scene the
+        // mesh left and re-entered puts it somewhere else, and every other binding's row can move
+        // out from under it too. So the records are re-resolved whenever the table's membership has
+        // changed since they were written, not only when a binding was added or dropped.
+        const mesh_rows_version = this.#scene_context.mesh_rows_version;
+
+        if (this.#bindings_dirty || this.#uploaded_mesh_rows_version !== mesh_rows_version) {
+            this.#upload_bindings();
+
+            this.#uploaded_mesh_rows_version = mesh_rows_version;
+        }
+
+        if (this.#bindings_dirty) {
+            // Neither of these reads anything outside the binding list, so a scene edit that left
+            // the list alone cannot have moved them.
+            this.#upload_dispatch_lookup();
+            this.#upload_prev_position_offsets();
+            this.#bindings_dirty = false;
+        }
+
+        const meshlets = this.#geometries.meshlets;
+        const total = this.#total_meshlet_count;
+        const binding_count = this.#bindings.length;
+        const max_workgroups = this.#device.limits.maxComputeWorkgroupsPerDimension;
+
+        // ── Skinning: deform the cloned vertex regions ────────────
+        //
+        // WebGPU's `dispatchWorkgroups` is capped at the device's
+        // `maxComputeWorkgroupsPerDimension` (65535 is the spec
+        // minimum; modern desktop GPUs typically report higher).
+        // With one workgroup per (binding, meshlet) pair, a busy
+        // scene (e.g. a grid of skinned characters) can exceed that
+        // — 324 dancers × ~220 meshlets each ≈ 71K pairs.
+        //
+        // Split into sub-dispatches when needed, passing
+        // `dispatch_offset` so the shader's lookup-index arithmetic
+        // keeps indexing a flat `dispatch_lookup` table. The encoded
+        // cost grows linearly in sub-dispatch count, but the GPU
+        // work is identical to a single huge dispatch.
+        for (let offset = 0; offset < total; offset += max_workgroups) {
+            const this_chunk = Math.min(max_workgroups, total - offset);
+            const dispatch_offset = cmd_ctx.allocateTransientValueBuffer(u32, offset);
+
+            shader_meshlet_apply_skinning.dispatch({
+                encoder: cmd_ctx,
+                group_count_x: this_chunk,
+                bindings: {
+                    dispatch_offset,
+                    meshlet_data: meshlets.buffer_data,
+                    meshlet_metadata: meshlets.buffer_metadata,
+                    skin_matrices: this.#animation_manager.skin_matrices_buffer,
+                    prev_skin_matrices: this.#animation_manager.prev_skin_matrices_buffer,
+                    skinning_bindings: this.#bindings_buffer,
+                    dispatch_lookup: this.#dispatch_lookup_buffer,
+                    prev_position_offsets: this.#prev_position_offsets_buffer,
+                    prev_positions: this.#prev_positions_buffer,
+                    // Skinning shader reads the SkinnedMesh's
+                    // `transforms` row to source the live
+                    // mesh.transform_global for the post-DQ
+                    // position cancellation.
+                    scene_database: this.#scene_context.scene_database_buffer,
+                },
+            });
+        }
+
+        // ── Bounds refresh chain ──────────────────────────────────
+        //
+        // Animated clones move outside their source-encoded bounds;
+        // the rasterizer's per-meshlet AABB cull and per-mesh sphere
+        // cull would reject them until we refresh both. The chain
+        // here runs every frame the skinning dispatched anything
+        // (cheap when nothing changed: dispatch overhead only, the
+        // shaders early-out on the workgroup boundary).
+        //
+        // Order is load-bearing:
+        //   1. scatter  — reset meshlet.bounds_box / geometry.bounding_box to ±inf
+        //   2. reduce   — atomic-merge per-vertex into meshlet + geometry box
+        //   3. derive   — geometry box → geometry sphere (per binding)
+        //   4. mesh     — geometry box+sphere → world-space mesh bounds (per binding)
+        //
+        // The same `dispatch_lookup` table that drove the skinning
+        // dispatch above also drives the scatter and reduce dispatches
+        // — every (binding, meshlet) pair gets exactly the same set
+        // of workgroups, just running different shaders.
+        const geometry_metadata_buffer = this.#geometries.buffer_metadata;
+        const scene_database_buffer = this.#scene_context.scene_database_buffer;
+
+        // ── 1. Scatter: ±inf sentinels into meshlet + geometry bounds.
+        // Linear-thread dispatch: WG_SIZE threads per workgroup, one
+        // thread per pair. With WG_SIZE = 64 the workgroup count is
+        // ceil(total/64) — single sub-dispatch except at extreme
+        // scale (~4M pairs).
+        {
+            const total_workgroups = Math.ceil(total / BOUNDS_SCATTER_WORKGROUP_SIZE);
+            for (let offset_wg = 0; offset_wg < total_workgroups; offset_wg += max_workgroups) {
+                const this_chunk = Math.min(max_workgroups, total_workgroups - offset_wg);
+                // dispatch_offset is in *pair* units for scatter — the
+                // shader does `gid.x + dispatch_offset`.
+                const dispatch_offset = cmd_ctx.allocateTransientValueBuffer(
+                    u32,
+                    offset_wg * BOUNDS_SCATTER_WORKGROUP_SIZE
+                );
+                const total_pair_count = cmd_ctx.allocateTransientValueBuffer(u32, total);
+                shader_meshlet_bounds_scatter.dispatch({
+                    encoder: cmd_ctx,
+                    group_count_x: this_chunk,
+                    bindings: {
+                        dispatch_offset,
+                        total_pair_count,
+                        skinning_bindings: this.#bindings_buffer,
+                        dispatch_lookup: this.#dispatch_lookup_buffer,
+                        meshlet_metadata_atomic: meshlets.buffer_metadata,
+                        geometry_metadata_atomic: geometry_metadata_buffer,
+                    },
+                });
+            }
+        }
+
+        // ── 2. Reduce: per-meshlet workgroup, merges into meshlet +
+        // geometry box atomically. Same workgroup-per-pair pattern as
+        // skinning; same pagination.
+        for (let offset = 0; offset < total; offset += max_workgroups) {
+            const this_chunk = Math.min(max_workgroups, total - offset);
+            const dispatch_offset = cmd_ctx.allocateTransientValueBuffer(u32, offset);
+
+            shader_meshlet_bounds_reduce.dispatch({
+                encoder: cmd_ctx,
+                group_count_x: this_chunk,
+                bindings: {
+                    dispatch_offset,
+                    skinning_bindings: this.#bindings_buffer,
+                    dispatch_lookup: this.#dispatch_lookup_buffer,
+                    meshlet_data: meshlets.buffer_data,
+                    meshlet_metadata_atomic: meshlets.buffer_metadata,
+                    geometry_metadata_atomic: geometry_metadata_buffer,
+                },
+            });
+        }
+
+        // ── 3. Sphere derive: per binding, geometry box → sphere.
+        // Linear-thread dispatch, sized to ceil(binding_count/64).
+        // Binding count is small (one per active SkinnedMesh, so
+        // hundreds at most), single sub-dispatch always suffices.
+        {
+            const total_workgroups = Math.ceil(binding_count / SPHERE_DERIVE_WORKGROUP_SIZE);
+            if (total_workgroups > 0) {
+                const binding_count_u = cmd_ctx.allocateTransientValueBuffer(u32, binding_count);
+                shader_geometry_sphere_derive.dispatch({
+                    encoder: cmd_ctx,
+                    group_count_x: total_workgroups,
+                    bindings: {
+                        binding_count: binding_count_u,
+                        skinning_bindings: this.#bindings_buffer,
+                        geometry_metadata_atomic: geometry_metadata_buffer,
+                    },
+                });
+            }
+        }
+
+        // ── 4. Mesh-instance bounds: per binding, geometry → world
+        // mesh bounds. Reuses the existing per-mesh bounds chunk
+        // (sphere radius scaled by max-column-length of the
+        // transform 3×3, conservative under non-uniform scale).
+        {
+            const total_workgroups = Math.ceil(binding_count / MESH_BOUNDS_REFRESH_WORKGROUP_SIZE);
+            if (total_workgroups > 0) {
+                const binding_count_u = cmd_ctx.allocateTransientValueBuffer(u32, binding_count);
+                shader_skinned_mesh_bounds_refresh.dispatch({
+                    encoder: cmd_ctx,
+                    group_count_x: total_workgroups,
+                    bindings: {
+                        binding_count: binding_count_u,
+                        skinning_bindings: this.#bindings_buffer,
+                        scene_database: scene_database_buffer,
+                        geometries: geometry_metadata_buffer,
+                    },
+                });
+            }
+        }
+    }
+
+    /**
+     * @param {SkinnedMesh} mesh
+     * @param {GPUGeometryMetadata} clone_metadata
+     * @param {number} skin_id
+     */
+    #register_binding(mesh, clone_metadata, skin_id) {
+        const source_metadata = this.#geometries.get_metadata(mesh.geometry);
+        assert.defined(source_metadata, 'source_metadata');
+
+        const meshlet_count = clone_metadata.meshlets.meshlet_count;
+        const clone_meshlet_metadata_offset = clone_metadata.meshlets.metadata.offset;
+
+        this.#bindings.push({
+            skin_id,
+            mesh,
+            source_meshlet_metadata_offset: source_metadata.meshlets.metadata.offset,
+            clone_meshlet_metadata_offset,
+            meshlet_count,
+            clone_geometry_index: clone_metadata.index,
+        });
+        this.#total_meshlet_count += meshlet_count;
+        this.#bindings_dirty = true;
+
+        // ── Prev-position side-buffer bookkeeping ────────────────
+        //
+        // Walk the source's CPU metadata bytes to sum vertex counts
+        // (source and clone share the same vertex counts per
+        // meshlet — the clone is a memcpy of the source data). Each
+        // clone meshlet gets a contiguous (vertex_count × 3 u32)
+        // slot in the prev_positions side-buffer; record its base
+        // word offset in the per-meshlet offsets table indexed by
+        // absolute clone meshlet metadata row.
+        //
+        // `metadata_buffer_original` comes from `BinaryBuffer.data`
+        // and IS the raw `ArrayBuffer` (not a typed-array view), so
+        // we wrap it in a DataView directly without dereferencing
+        // a `.buffer` property.
+        const metadata_bytes = source_metadata.meshlets.metadata_buffer_original;
+        const view = new DataView(metadata_bytes);
+
+        // Phase 1: sum total vertices so we can grow the side-buffer
+        // up front, before recording per-meshlet offsets.
+        let total_vertices = 0;
+        for (let i = 0; i < meshlet_count; i++) {
+            const vc = view.getUint32(i * MESHLET_STRIDE_BYTES + MESHLET_VERTEX_COUNT_BYTE_OFFSET, true);
+            total_vertices += vc;
+        }
+
+        const base_vertex_offset = this.#next_prev_position_vertex_offset;
+        this.#next_prev_position_vertex_offset += 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)
+        // to u32-word offset (× 3) since the side-buffer stores
+        // 3 × f32 per vertex back-to-back.
+        let cumulative_vertex_offset = 0;
+        for (let i = 0; i < meshlet_count; i++) {
+            const vc = view.getUint32(i * MESHLET_STRIDE_BYTES + MESHLET_VERTEX_COUNT_BYTE_OFFSET, true);
+            const meshlet_word_offset = (base_vertex_offset + cumulative_vertex_offset) * 3;
+            this.#prev_position_offsets_cpu[clone_meshlet_metadata_offset + i] = meshlet_word_offset;
+            cumulative_vertex_offset += vc;
+        }
+    }
+
+    /**
+     * Grow {@link #prev_positions_buffer} to fit at least
+     * `required_vertices` vertices. Doubles from
+     * {@link PREV_POSITIONS_INITIAL_CAPACITY_VERTICES}. The buffer's
+     * contents are scratch (rewritten every frame by the skinning
+     * compute pass), so growth doesn't copy data — but the reference
+     * is invalidated, so callers must re-fetch through the getter.
+     *
+     * @param {number} required_vertices
+     */
+    #ensure_prev_positions_capacity_vertices(required_vertices) {
+        if (this.#prev_positions_buffer !== null && required_vertices <= this.#prev_positions_capacity_vertices) {
+            return;
+        }
+
+        let new_capacity = Math.max(
+            this.#prev_positions_capacity_vertices,
+            PREV_POSITIONS_INITIAL_CAPACITY_VERTICES,
+        );
+        while (new_capacity < required_vertices) {
+            new_capacity *= 2;
+        }
+
+        if (this.#prev_positions_buffer !== null) {
+            this.#prev_positions_buffer.destroy();
+        }
+
+        // 3 × u32 per vertex (each u32 carries an f32 bit pattern).
+        this.#prev_positions_buffer = this.#device.createBuffer({
+            label: 'GPUMeshSkinningContext/PrevPositions',
+            size: new_capacity * 3 * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        });
+        this.#prev_positions_capacity_vertices = new_capacity;
+    }
+
+    /**
+     * Grow {@link #prev_position_offsets_buffer} (and its CPU
+     * shadow) to cover at least `required_records` meshlet metadata
+     * rows. Entries beyond previously written ones default to
+     * {@link PREV_POSITION_OFFSET_INVALID} so non-clone meshlets
+     * read as "no prev-position data, fall back".
+     *
+     * @param {number} required_records
+     */
+    #ensure_prev_position_offsets_capacity(required_records) {
+        if (this.#prev_position_offsets_buffer !== null && required_records <= this.#prev_position_offsets_capacity) {
+            return;
+        }
+
+        let new_capacity = Math.max(
+            this.#prev_position_offsets_capacity,
+            PREV_POSITION_OFFSETS_INITIAL_CAPACITY,
+        );
+        while (new_capacity < required_records) {
+            new_capacity *= 2;
+        }
+
+        // Re-allocate CPU shadow, copy old entries, fill new with
+        // sentinel.
+        const new_cpu = new Uint32Array(new_capacity);
+        new_cpu.fill(PREV_POSITION_OFFSET_INVALID);
+        new_cpu.set(this.#prev_position_offsets_cpu);
+        this.#prev_position_offsets_cpu = new_cpu;
+
+        if (this.#prev_position_offsets_buffer !== null) {
+            this.#prev_position_offsets_buffer.destroy();
+        }
+
+        this.#prev_position_offsets_buffer = this.#device.createBuffer({
+            label: 'GPUMeshSkinningContext/PrevPositionOffsets',
+            size: new_capacity * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this.#prev_position_offsets_capacity = new_capacity;
+    }
+
+    /**
+     * Re-upload the entire {@link #prev_position_offsets_cpu} shadow
+     * to the GPU offsets buffer. Called when a new binding has
+     * registered new entries (rare — bindings register once, not
+     * per frame). Whole-buffer upload because the buffer is small
+     * (one u32 per meshlet metadata row, hundreds of KB at typical
+     * stress-test scale).
+     */
+    #upload_prev_position_offsets() {
+        if (this.#prev_position_offsets_buffer === null) {
+            return;
+        }
+        this.#device.queue.writeBuffer(
+            this.#prev_position_offsets_buffer,
+            0,
+            this.#prev_position_offsets_cpu.buffer,
+            0,
+            this.#prev_position_offsets_capacity * 4,
+        );
+    }
+
+    /**
+     * Resolve every CPU binding into GPU bytes (looking up
+     * `skin_matrix_offset` from the animation manager) and upload to
+     * the bindings buffer. Grows the buffer first if the binding
+     * count has outgrown its capacity.
+     */
+    #upload_bindings() {
+        const binding_count = this.#bindings.length;
+        const struct_size = SKINNING_BINDING_STRUCT.aligned_size;
+
+        if (binding_count > this.#bindings_capacity) {
+            let new_capacity = Math.max(this.#bindings_capacity, BINDINGS_INITIAL_CAPACITY);
+            while (new_capacity < binding_count) {
+                new_capacity *= 2;
+            }
+
+            if (this.#bindings_buffer !== null) {
+                this.#bindings_buffer.destroy();
+            }
+
+            this.#bindings_buffer = this.#device.createBuffer({
+                label: 'GPUMeshSkinningContext/Bindings',
+                size: new_capacity * struct_size,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+            this.#bindings_capacity = new_capacity;
+        }
+
+        const data = new ArrayBuffer(binding_count * struct_size);
+        for (let i = 0; i < binding_count; i++) {
+            const b = this.#bindings[i];
+
+            // The meshes table is asked for the row rather than having it
+            // derived from the transforms row: every node earns a
+            // transforms row and only the geometry-bearing ones earn a
+            // mesh row, so the two tables run at different rates as soon
+            // as the scene holds a group, an anchor or a joint — which is
+            // every glTF. A bound mesh is in the scene: assertion catches
+            // both a SkinnedMesh scene.build has not seen yet and one that
+            // left the scene without being unbound, either of which would
+            // otherwise reach the shader as a garbage row.
+            const mesh_instance_index = this.#scene_context.mesh_row_of(b.mesh);
+            assert.isNonNegativeInteger(
+                mesh_instance_index,
+                `SkinnedMesh '${b.mesh.name}' (id=${b.mesh.id}) has no meshes-table row — scene.build must run before skinning bindings upload`
+            );
+
+            write_gpu_typed_buffer({
+                skin_matrix_offset: this.#animation_manager.get_skin_matrix_offset(b.skin_id),
+                source_meshlet_metadata_offset: b.source_meshlet_metadata_offset,
+                clone_meshlet_metadata_offset: b.clone_meshlet_metadata_offset,
+                meshlet_count: b.meshlet_count,
+                clone_geometry_index: b.clone_geometry_index,
+                mesh_instance_index,
+            }, SKINNING_BINDING_STRUCT, data, i * struct_size);
+        }
+
+        this.#device.queue.writeBuffer(this.#bindings_buffer, 0, data);
+    }
+
+    /**
+     * Build the flat `(binding_index, meshlet_local_index)` table —
+     * one pair per workgroup the skinning dispatch will spawn — and
+     * upload to the dispatch-lookup buffer (growing it if needed).
+     */
+    #upload_dispatch_lookup() {
+        const total = this.#total_meshlet_count;
+
+        if (total > this.#dispatch_lookup_capacity) {
+            let new_capacity = Math.max(this.#dispatch_lookup_capacity, DISPATCH_LOOKUP_INITIAL_CAPACITY);
+            while (new_capacity < total) {
+                new_capacity *= 2;
+            }
+
+            if (this.#dispatch_lookup_buffer !== null) {
+                this.#dispatch_lookup_buffer.destroy();
+            }
+
+            this.#dispatch_lookup_buffer = this.#device.createBuffer({
+                label: 'GPUMeshSkinningContext/DispatchLookup',
+                // 8 bytes per pair (two u32s).
+                size: new_capacity * 8,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+            this.#dispatch_lookup_capacity = new_capacity;
+        }
+
+        const data = new Uint32Array(total * 2);
+        let cursor = 0;
+        for (let b = 0; b < this.#bindings.length; b++) {
+            const binding = this.#bindings[b];
+            for (let m = 0; m < binding.meshlet_count; m++) {
+                data[cursor++] = b;
+                data[cursor++] = m;
+            }
+        }
+
+        this.#device.queue.writeBuffer(this.#dispatch_lookup_buffer, 0, data);
+    }
+
+    destroy() {
+        if (this.#bindings_buffer !== null) {
+            this.#bindings_buffer.destroy();
+            this.#bindings_buffer = null;
+        }
+        if (this.#dispatch_lookup_buffer !== null) {
+            this.#dispatch_lookup_buffer.destroy();
+            this.#dispatch_lookup_buffer = null;
+        }
+        if (this.#prev_positions_buffer !== null) {
+            this.#prev_positions_buffer.destroy();
+            this.#prev_positions_buffer = null;
+        }
+        if (this.#prev_position_offsets_buffer !== null) {
+            this.#prev_position_offsets_buffer.destroy();
+            this.#prev_position_offsets_buffer = null;
+        }
+    }
+}