@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -1,1958 +1,2063 @@
-import { assert } from "../../../core/assert.js";
-import { FrameGraph } from "../../../engine/graphics/render/frame_graph/FrameGraph.js";
-import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
-import {
-    graph_scene_update_transform_hierarchy
-} from "../scene/hierarchy/graph_scene_update_transform_hierarchy.js";
-import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
-import {
-    ANIMATION_BOUND_TRACK_GROUP_NULL,
-    TRACKS_PER_GROUP_NODE,
-} from "./ANIMATION_BOUND_TRACK_GROUP_STRUCT.js";
-import { ANIMATION_DATABASE_SPEC } from "./ANIMATION_DATABASE_SPEC.js";
-import { AnimationClipFlags } from "./AnimationClipFlags.js";
-import { KEYFRAMES_PER_BLOCK } from "./ANIMATION_KEYFRAME_BLOCK_STRUCT.js";
-import {
-    ANIMATION_SKIN_JOINT_BLOCK_NULL,
-    JOINTS_PER_SKIN_BLOCK,
-} from "./ANIMATION_SKIN_JOINT_BLOCK_STRUCT.js";
-import { POSE_ACCUMULATOR_SLOT_BYTES } from "./POSE_ACCUMULATOR_LAYOUT.js";
-import {
-    clip_scale_channels,
-    skin_clip_scale_conflicts
-} from "./skin_clip_scale_conflicts.js";
-import { skin_normalize_mesh_frame } from "./skin_normalize_mesh_frame.js";
-import {
-    shader_animation_apply,
-    WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE,
-} from "./shader_animation_apply.js";
-import {
-    shader_animation_pose_resolve,
-    WORKGROUP_SIZE as ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE,
-} from "./shader_animation_pose_resolve.js";
-import {
-    shader_animation_tick,
-    WORKGROUP_SIZE as ANIMATION_TICK_WORKGROUP_SIZE,
-} from "./shader_animation_tick.js";
-import {
-    shader_skin_matrix_prep,
-    WORKGROUP_SIZE as SKIN_MATRIX_PREP_WORKGROUP_SIZE,
-} from "./skinning/shader_skin_matrix_prep.js";
-
-/**
- * Tail-slot placeholders for the fixed-size inline arrays in chain
- * nodes. The shader's `count` guard means these bytes are never read,
- * but the upload buffer doesn't zero unwritten ranges and
- * `write_struct_value` skips undefined fields — so explicit zeros are
- * the only way to keep tail bytes deterministic. Frozen so a stray
- * mutation can't bleed into multiple slots that share the reference.
- */
-const ZERO_KEYFRAME = Object.freeze({ time: 0, value: 0, inTangent: 0, outTangent: 0 });
-const ZERO_BINDING = Object.freeze({ track: 0, instance: 0, property: 0 });
-// Object.freeze on a typed array with elements throws under V8
-// ("Cannot freeze array buffer views with elements"), so we leave the
-// Float32Array unfrozen — the surrounding placeholder object is still
-// frozen to keep accidental field-level mutation out of bounds.
-const ZERO_INVERSE_BIND = new Float32Array(16);
-const ZERO_SKIN_JOINT = Object.freeze({ node: 0, inverse_bind: ZERO_INVERSE_BIND });
-
-/**
- * One skinning matrix is a `mat4x4f` — 16 f32s, 64 bytes. The
- * `skin_matrices` scratch buffer holds one entry per (skin, joint) pair
- * across every registered skin.
- */
-const SKIN_MATRIX_BYTES = 64;
-
-/**
- * Initial capacity of the `skin_matrices` scratch buffer, in matrices.
- * 256 × 64 = 16 KB — fits a handful of small skeletons before the first
- * grow. Picked to be wasteful neither at "no skins" nor "one character"
- * scale; growth doubles, so a few realloc cycles cover anything larger.
- */
-const SKIN_MATRICES_INITIAL_CAPACITY = 256;
-
-/**
- * Initial capacity of the {@link #pose_accumulator_buffer} in rows
- * (= transforms-table slots). 256 × 64 = 16 KB; growth doubles to
- * fit larger scenes. Resolve always zeroes the slot after draining,
- * so a fresh buffer (createBuffer is zero-initialised) and a "no
- * contribution this frame" state are observationally identical.
- */
-const POSE_ACCUMULATOR_INITIAL_CAPACITY = 256;
-
-/**
- * Per-frame `dt` cap pushed into the tick shader. Without it, a tab
- * backgrounded for several seconds (or a paused debugger) would
- * leak that whole interval into the next tick — either rocketing a
- * looping clip through dozens of cycles in one step or, for
- * non-looping clips, clamping them past the meaningful range. The
- * cap trades a few frames of CSS-smooth animation after a stall
- * for a deterministic clip state.
- */
-const MAX_DT_SECONDS = 1 / 15;
-
-/**
- * Allocate a singly-linked chain of fixed-capacity nodes into `table`,
- * one node per `items_per_chunk`-sized window of `items`. Builds
- * tail-first so each node's successor id is known at `add()` time —
- * the alternative (forward + back-patch) would mean a second `set()`
- * per node.
- *
- * `build_node(start, count, next_id)` constructs the record to add: it
- * populates the inline array from `items[start..start+count]`, pads
- * tail slots, and assembles any extra payload the table expects
- * (including embedding `next_id` as the node's `next` field).
- *
- * Returns the head id (the last `add()`'s slot id), or `0xFFFFFFFF` if
- * `items` is empty.
- *
- * @template T
- * @template R
- * @param {{ add: (record: R) => number }} table
- * @param {T[]} items
- * @param {number} items_per_chunk
- * @param {(start: number, count: number, next_id: number) => R} build_node
- * @returns {number}
- */
-function add_linked_chain(table, items, items_per_chunk, build_node) {
-    const node_count = Math.ceil(items.length / items_per_chunk);
-    let next_id = 0xFFFFFFFF;
-
-    for (let n = node_count - 1; n >= 0; n--) {
-        const start = n * items_per_chunk;
-        const this_count = Math.min(items_per_chunk, items.length - start);
-        next_id = table.add(build_node(start, this_count, next_id));
-    }
-
-    return next_id;
-}
-
-/**
- * Top-level coordinator for GPU-resident animation.
- *
- * Owns a single {@link GPUDatabase} keyed by {@link ANIMATION_DATABASE_SPEC}
- * with five tables: `animation_curves`, `animation_keyframe_blocks`,
- * `animation_tracks`, `animation_clips`, `animation_bound_track_groups`.
- * Every record — including individual keyframes (inlined inside block
- * nodes) and individual bindings (inlined inside group nodes) — lives in
- * the database, so the dispatch shader needs only one storage binding.
- *
- * Animation *data* (curves, keyframes, tracks) is independent from
- * *bound clips* (each carrying a `time` and a head pointer to its
- * bound-track group chain). Bindings are no longer their own table:
- * each chain node inlines up to {@link TRACKS_PER_GROUP_NODE} bindings
- * and back-references its owning clip.
- *
- * Usage:
- *  1. (Once at setup) Either low-level (`add_curve`, `add_track`,
- *     `add_skin`, `add_clip`) or high-level (`register_skin`,
- *     `register_clip` against the CPU data classes {@link Skin} /
- *     {@link ShadeAnimationClip}).
- *  2. (Once) {@link start} per clip to begin GPU-driven playback —
- *     the {@link shader_animation_tick} pass advances `time` each
- *     frame thereafter. CPU-driven prototypes can instead call
- *     {@link set_time} per frame and skip the Playing flag.
- *  3. (Per frame) {@link update} flushes pending writes for the
- *     database. The scene context already does this on its own
- *     update path.
- */
-export class GPUAnimationManager {
-
-    /** @type {GPUDevice} */
-    #device;
-
-    /** @type {string} */
-    #label;
-
-    /** @type {GPUDatabase} */
-    #database;
-
-    /**
-     * Ping-pong pair of per-frame skinning-matrix buffers — one holds
-     * this frame's matrices (target of the prep dispatch, source for
-     * skinning's current-position write), the other last frame's
-     * (source for skinning's `position_prev` write that feeds the
-     * velocity post-pass).
-     *
-     * Ping-pong rather than a single buffer because the prev-frame
-     * matrices need to survive next frame's prep dispatch — and the
-     * cheapest way to preserve them is to write the new matrices into
-     * the OTHER buffer instead of overwriting the only one we have.
-     *
-     * {@link #skin_matrices_current_index} selects which entry of this
-     * array is "current" for the frame about to be dispatched;
-     * {@link dispatch_skin_matrix_prep} flips it before each frame's
-     * prep so the now-stale slot gets recycled.
-     *
-     * Lazily allocated on first {@link add_skin}; both grow together
-     * by doubling. After a grow both buffers are zero-initialised and
-     * {@link #first_frame_skin_matrices} is set so the next prep
-     * dispatch seeds the "previous" buffer with a copy of the freshly
-     * written "current" — without this, the first velocity readback
-     * after a grow would interpolate against zero matrices.
-     *
-     * @type {Array<GPUBuffer|null>}
-     */
-    #skin_matrices_buffers = [null, null];
-
-    /**
-     * Which entry of {@link #skin_matrices_buffers} is "current" for
-     * the next prep dispatch. Flipped at the start of every prep call.
-     * @type {number}
-     */
-    #skin_matrices_current_index = 0;
-
-    /**
-     * When true, the next prep dispatch will copy the freshly-written
-     * "current" buffer into the "previous" buffer at the end of the
-     * pass — used on first allocation and after every grow so the
-     * very first velocity computation has matching prev/current
-     * matrices (zero velocity).
-     * @type {boolean}
-     */
-    #first_frame_skin_matrices = true;
-
-    /**
-     * Capacity of each of {@link #skin_matrices_buffers} in matrices
-     * (not bytes). Both buffers always have the same capacity.
-     * @type {number}
-     */
-    #skin_matrices_capacity = 0;
-
-    /**
-     * Next free matrix index. Each {@link add_skin} reserves
-     * `joint_count` consecutive entries starting here, then advances.
-     * Monotonic — no freeing in the MVP.
-     * @type {number}
-     */
-    #next_skin_matrix_offset = 0;
-
-    /**
-     * CPU-side `skin_id → skin_matrix_offset` map. Each registered
-     * skin's base address in the shared `skin_matrices` scratch
-     * buffer; the per-block absolute offset (the prep shader's hot
-     * path) is derived as `base + chain_position *
-     * JOINTS_PER_SKIN_BLOCK` at registration. Storing the base on
-     * GPU would duplicate it — the block records already carry the
-     * per-block absolute address, and only the CPU (the skinning-
-     * binding upload path) needs the skin's base value.
-     *
-     * @type {Map<number, number>}
-     */
-    #skin_matrix_offsets = new Map();
-
-    /**
-     * Registered skins by id, kept for one reason: a clip registered *after* a skin has to be held
-     * against it, and a clip registered before one has to be held against the skin when it arrives.
-     * The frame a skinned mesh is deformed in is fixed once, at registration, and a clip that scales
-     * a joint is the one thing that can undo it afterwards — see {@link skin_clip_scale_conflicts}
-     * and `SKINNING_FRAME_PLAN.md` §4.
-     *
-     * @type {Map<number, Skin>}
-     */
-    #skins_by_id = new Map();
-
-    /**
-     * Registered clips that scale *something*, by id. Almost always empty — a character's clips
-     * rotate and translate — which is what keeps the pairwise check free in the ordinary case.
-     *
-     * @type {Map<number, ShadeAnimationClip>}
-     */
-    #scaling_clips = new Map();
-
-    /**
-     * Per-frame pose-accumulator scratch buffer. One slot per
-     * `transforms_table` row (slot size = `POSE_ACCUMULATOR_SLOT_BYTES`).
-     * The apply pass atomic-adds weighted TRS contributions into each
-     * dirty row; the resolve pass drains it into `transforms_table.local_*`
-     * and zeros the slot for next frame.
-     *
-     * Lazily allocated on first {@link ensure_pose_accumulator_capacity};
-     * grows by doubling. Grow destroys the old buffer — since resolve
-     * always leaves it zero, no copy is needed on grow.
-     *
-     * @type {GPUBuffer|null}
-     */
-    #pose_accumulator_buffer = null;
-
-    /**
-     * Capacity of {@link #pose_accumulator_buffer} in rows (slot
-     * indices), not bytes.
-     * @type {number}
-     */
-    #pose_accumulator_capacity = 0;
-
-    /**
-     * Back-reference to the owning scene context. Lets the high-level
-     * `register_*` methods resolve `Node3D.id` → transforms-table row
-     * via {@link GPUSceneContext#id_mapping} and bind skinning meshes
-     * via {@link GPUSceneContext#skinning}, without callers having to
-     * thread the context through every call.
-     *
-     * The manager doesn't touch this at construction (the scene
-     * context is itself only partially constructed when it builds the
-     * manager) — only inside `register_*` calls, which happen after
-     * scene.build has populated `id_mapping`.
-     *
-     * @type {GPUSceneContext}
-     */
-    #scene_context;
-
-    /**
-     * Identity-keyed cache of curve-id-on-GPU for every
-     * {@link AnimationCurve} that has been registered via
-     * {@link register_clip}. Lets multiple clips whose channels share
-     * the same curve instance (e.g. one base clip retargeted across
-     * many character instances) reuse the same GPU rows for the
-     * curve header + keyframe blocks rather than uploading
-     * duplicates. At grid-of-dancers scale duplication would balloon
-     * the keyframe-blocks table past its page-table limits.
-     *
-     * Low-level `add_curve` deliberately stays uncached — every call
-     * uploads — so existing callers that pre-build curves with
-     * distinct IDs (e.g. a pre-built track pool)
-     * keep their behavior.
-     *
-     * @type {WeakMap<AnimationCurve, number>}
-     */
-    #curve_id_cache = new WeakMap();
-
-    /**
-     * The curves uploaded so far, by what they are rather than which instance they were: the
-     * `hash()` of a curve's keys, to every uploaded curve with that hash and its GPU id.
-     *
-     * An instance cache alone shares nothing between two parses of one file, and a character
-     * instanced a few hundred times is a few hundred parses — each with its own instances of the
-     * same keys, filling the keyframe-block table with copies of one dance until its page limit
-     * refuses the next dancer. Curves are read-only once uploaded and nothing here releases them,
-     * so equal content can safely mean one upload.
-     *
-     * A hash bucket is a list because a hash is not an identity: a curve is only shared with one
-     * whose every key `equals` its own, tangents included.
-     *
-     * @type {Map<number, {curve: AnimationCurve, id: number}[]>}
-     */
-    #curve_id_by_content = new Map();
-
-    /**
-     * Cache of track-id-on-GPU keyed by `(curve_id_x, curve_id_y,
-     * curve_id_z, curve_id_w, mask)`. With curve dedup already
-     * sharing curve IDs across clips, two channels in different
-     * clips that bind to the same (target_property, curves) end up
-     * with identical track keys — and we can share the track row
-     * too. Each curve_id slot is `-1` when the corresponding channel
-     * is absent.
-     *
-     * Keys are joined into a string for Map lookup; the join cost is
-     * negligible compared to the GPU upload it avoids.
-     *
-     * @type {Map<string, number>}
-     */
-    #track_id_cache = new Map();
-
-    /**
-     * Skins registered via {@link register_skin} whose joint-block
-     * chain hasn't been built yet because one or more joint Node3Ds
-     * lacks an `id_mapping` row. The skin's GPU table row exists
-     * (placeholder `joint_block_head = NULL`, no joints driving the
-     * prep pass yet), and state mutators / unregister already work
-     * — but the deformation only kicks in once {@link update}
-     * successfully drains the entry.
-     *
-     * Each entry: `skin_id`, the CPU {@link Skin} (whose `joints`
-     * array drives the chain build), the `skin_matrix_offset`
-     * reserved at register time, and the `inverse_bind_matrices`
-     * typed array.
-     *
-     * @type {Array<{
-     *     skin_id: number,
-     *     skin: Skin,
-     *     skin_matrix_offset: number,
-     *     inverse_bind_matrices: Float32Array,
-     * }>}
-     */
-    #pending_skins = [];
-
-    /**
-     * Clips registered via {@link register_clip} whose bindings
-     * chain hasn't been built yet because one or more channel
-     * targets lacks an `id_mapping` row. The clip's GPU table row
-     * exists (placeholder `bound_track_group_head = NULL`, no
-     * tracks driving the apply pass yet); time/state mutators and
-     * unregister already work.
-     *
-     * Each entry: `clip_id` plus the per-channel `(track_id,
-     * target, property)` triples — the curves and tracks were
-     * interned at register time so only the (target → instance row)
-     * resolution is deferred.
-     *
-     * @type {Array<{
-     *     clip_id: number,
-     *     channels: Array<{ track: number, target: Node3D, property: number }>,
-     * }>}
-     */
-    #pending_clips = [];
-
-    /**
-     * @param {GPUDevice} device
-     * @param {string} label
-     * @param {GPUSceneContext} scene_context
-     */
-    constructor(device, label, scene_context) {
-        assert.defined(device, 'device');
-        assert.defined(scene_context, 'scene_context');
-
-        this.#device = device;
-        this.#label = label;
-        this.#scene_context = scene_context;
-
-        this.#database = new GPUDatabase({
-            device,
-            definition: ANIMATION_DATABASE_SPEC,
-            label: `${label}/Database`,
-        });
-    }
-
-    /**
-     * @returns {GPUDatabase}
-     */
-    get database() {
-        return this.#database;
-    }
-
-    /**
-     * Per-frame skinning-matrix scratch buffer for the *current*
-     * frame. `null` until the first skin is registered. The
-     * skin-matrix-prep pass writes to it; the skinning compute pass
-     * reads from it to deform current-frame positions. Address `j`
-     * of skin `s` is at matrix index `s.skin_matrix_offset + j`.
-     *
-     * The buffer reference is invalidated on grow AND flips role
-     * every frame as part of the ping-pong with
-     * {@link prev_skin_matrices_buffer} — re-fetch each frame.
-     *
-     * @returns {GPUBuffer|null}
-     */
-    get skin_matrices_buffer() {
-        return this.#skin_matrices_buffers[this.#skin_matrices_current_index];
-    }
-
-    /**
-     * Previous-frame counterpart of {@link skin_matrices_buffer} —
-     * holds the matrices the previous frame's prep dispatch wrote.
-     * Read by the skinning compute pass to produce per-vertex
-     * `position_prev` data for the velocity post-pass.
-     *
-     * `null` until the first skin is registered. Flips role with
-     * {@link skin_matrices_buffer} every frame.
-     *
-     * @returns {GPUBuffer|null}
-     */
-    get prev_skin_matrices_buffer() {
-        return this.#skin_matrices_buffers[1 - this.#skin_matrices_current_index];
-    }
-
-    /**
-     * Number of matrices currently in use (= sum of `joint_count` over
-     * registered skins). Independent of buffer capacity, which is at
-     * least this big.
-     *
-     * @returns {number}
-     */
-    get skin_matrix_count() {
-        return this.#next_skin_matrix_offset;
-    }
-
-    /**
-     * Pose-accumulator scratch buffer (per-Node3D-row weighted
-     * contribution slots). `null` until {@link ensure_pose_accumulator_capacity}
-     * is called for the first time.
-     *
-     * The buffer reference is invalidated on grow — re-fetch each
-     * frame after {@link ensure_pose_accumulator_capacity} rather
-     * than caching across frames.
-     *
-     * @returns {GPUBuffer|null}
-     */
-    get pose_accumulator_buffer() {
-        return this.#pose_accumulator_buffer;
-    }
-
-    /**
-     * Ensure the pose-accumulator scratch buffer can address at least
-     * `row_count` `transforms_table` rows. Grows by doubling from the
-     * initial capacity; idempotent when already big enough. Called
-     * by the per-frame dispatch driver after `scene.build` has
-     * stabilised the transforms-table size for the frame.
-     *
-     * Grow destroys the previous GPU buffer; resolve always leaves the
-     * accumulator zeroed at the end of each frame, so there's nothing
-     * to copy across the realloc.
-     *
-     * @param {number} row_count
-     */
-    ensure_pose_accumulator_capacity(row_count) {
-        assert.isNonNegativeInteger(row_count, 'row_count');
-
-        // Existing buffer fits the request → nothing to do. The null
-        // check guarantees the very first call always allocates,
-        // even when `row_count == 0` (e.g. before any scene content
-        // has been built): downstream binding paths assume the
-        // buffer reference is non-null whenever the apply pass runs.
-        if (this.#pose_accumulator_buffer !== null && row_count <= this.#pose_accumulator_capacity) {
-            return;
-        }
-
-        let new_capacity = Math.max(this.#pose_accumulator_capacity, POSE_ACCUMULATOR_INITIAL_CAPACITY);
-        while (new_capacity < row_count) {
-            new_capacity *= 2;
-        }
-
-        if (this.#pose_accumulator_buffer !== null) {
-            this.#pose_accumulator_buffer.destroy();
-        }
-
-        this.#pose_accumulator_buffer = this.#device.createBuffer({
-            label: `${this.#label}/PoseAccumulator`,
-            size: new_capacity * POSE_ACCUMULATOR_SLOT_BYTES,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
-        });
-        this.#pose_accumulator_capacity = new_capacity;
-    }
-
-    /**
-     * Read back a skin's record from the database's CPU shadow.
-     *
-     * @param {number} skin_id
-     * @returns {{joint_block_head: number, joint_count: number}}
-     */
-    get_skin(skin_id) {
-        assert.isNonNegativeInteger(skin_id, 'skin_id');
-        return this.#database.get('animation_skins').get(skin_id);
-    }
-
-    /**
-     * Base address of the skin's matrix range in the shared
-     * `skin_matrices` scratch buffer — matrix `j` of the skin lives
-     * at `skin_matrices[get_skin_matrix_offset(skin_id) + j]`.
-     *
-     * Tracked CPU-side rather than on the skin record because the
-     * value is only ever consumed by the skinning-binding upload
-     * path; the prep shader uses the per-block absolute offset
-     * (cheaper than a per-thread skin lookup for that hot path).
-     *
-     * @param {number} skin_id
-     * @returns {number}
-     */
-    get_skin_matrix_offset(skin_id) {
-        assert.isNonNegativeInteger(skin_id, 'skin_id');
-        const offset = this.#skin_matrix_offsets.get(skin_id);
-        assert.defined(offset, `unknown skin_id ${skin_id}`);
-        return offset;
-    }
-
-    /**
-     * Add an animation curve. Keyframes are split into linked-list blocks
-     * of up to {@link KEYFRAMES_PER_BLOCK} entries each; the curve header
-     * points at the head block, and each block's `next` field chains
-     * forward.
-     *
-     * The curve is a cubic Hermite spline — step, linear, and arbitrary
-     * cubic shapes are all expressible by choosing tangents on each keyframe.
-     *
-     * @param {AnimationCurve} curve
-     * @returns {number} curve id (index into the `animation_curves` table)
-     */
-    add_curve(curve) {
-        assert.defined(curve, 'curve');
-        assert.equal(curve.isAnimationCurve, true, 'curve.isAnimationCurve !== true');
-        assert.greaterThanOrEqual(curve.length, 1, 'curve must have at least one keyframe');
-
-        const keys = curve.keys;
-        const blocks_table = this.#database.get('animation_keyframe_blocks');
-
-        const head_block_id = add_linked_chain(
-            blocks_table,
-            keys,
-            KEYFRAMES_PER_BLOCK,
-            (start, count, next) => {
-                const keyframes = new Array(KEYFRAMES_PER_BLOCK);
-                for (let j = 0; j < KEYFRAMES_PER_BLOCK; j++) {
-                    keyframes[j] = j < count ? keys[start + j] : ZERO_KEYFRAME;
-                }
-                return { keyframes, count, next };
-            }
-        );
-
-        const curves_table = this.#database.get('animation_curves');
-        return curves_table.add({
-            kind: 0,
-            keyframe_block_head: head_block_id,
-            keyframe_count: keys.length,
-            time_min: curve.start_time,
-            time_max: curve.end_time,
-        });
-    }
-
-    /**
-     * Add a track. Channels are addressed by name (`x`, `y`, `z`, `w`) — the
-     * provided curves go into the matching slots of the track's `vec4f`
-     * output. Omitted channels are masked off and read as 0.
-     *
-     * The slot meaning is property-specific: for `MeshTranslation`, x/y/z
-     * are the translation components; for `MeshRotation` they're the
-     * quaternion's x/y/z/w. The track's mask travels with the evaluated
-     * value to the apply step, which uses it to decide which destinations
-     * to overwrite.
-     *
-     * @param {{ x?: number, y?: number, z?: number, w?: number }} channels
-     *     curve ids per channel; pass at least one
-     * @returns {number} track id (index into the `animation_tracks` table)
-     */
-    add_track(channels) {
-        assert.defined(channels, 'channels');
-
-        const cx = channels.x;
-        const cy = channels.y;
-        const cz = channels.z;
-        const cw = channels.w;
-
-        let mask = 0;
-        if (cx !== undefined) mask |= 0x1;
-        if (cy !== undefined) mask |= 0x2;
-        if (cz !== undefined) mask |= 0x4;
-        if (cw !== undefined) mask |= 0x8;
-
-        assert.notEqual(mask, 0, 'track must have at least one channel');
-
-        const curves = [
-            cx ?? 0,
-            cy ?? 0,
-            cz ?? 0,
-            cw ?? 0,
-        ];
-
-        const table = this.#database.get('animation_tracks');
-        return table.add({ mask, curves });
-    }
-
-    /**
-     * Create a bound clip — a group of bound tracks that share a single
-     * `time`. Bindings are split into linked-list group nodes of up to
-     * {@link TRACKS_PER_GROUP_NODE} each; the clip points at the head
-     * node and each node back-references the clip so the apply shader
-     * (one thread per group node) can fetch the clip without walking the
-     * chain from the clip end.
-     *
-     * Tracks may be authored on a clock that doesn't align with
-     * `[time_start, time_end]` — their curves are clamped to their own
-     * `[time_min, time_max]` during evaluation.
-     *
-     * Defaults: `time = 0`, `time_start = 0`, `time_end = 0`,
-     * `playback_rate = 1`, `playback_weight = 1`, `flags = 0` (not
-     * playing, not looping). The clip is inert at creation — call
-     * {@link start} to begin GPU-side time advancement.
-     *
-     * @param {{
-     *     time?: number,
-     *     time_start?: number,
-     *     time_end?: number,
-     *     bindings: Array<{ track: number, instance: number, property: number }>,
-     * }} clip
-     * @returns {number} clip id (index into the `animation_clips` table)
-     */
-    add_clip(clip) {
-        assert.defined(clip, 'clip');
-        assert.isArray(clip.bindings, 'clip.bindings');
-        assert.greaterThanOrEqual(clip.bindings.length, 1, 'clip must have at least one binding');
-
-        const time = clip.time ?? 0;
-        const time_start = clip.time_start ?? 0;
-        const time_end = clip.time_end ?? 0;
-        const bindings = clip.bindings;
-
-        const clips_table = this.#database.get('animation_clips');
-        const groups_table = this.#database.get('animation_bound_track_groups');
-
-        // Reserve the clip slot up front so group nodes can back-reference
-        // it via `clip`. The head pointer is patched in once the chain is
-        // built (we don't know its first id until we've allocated every
-        // group node).
-        const clip_id = clips_table.add({
-            time,
-            time_start,
-            time_end,
-            bound_track_group_head: ANIMATION_BOUND_TRACK_GROUP_NULL,
-            playback_rate: 1,
-            flags: 0,
-            playback_weight: 1,
-        });
-
-        const head_group_id = add_linked_chain(
-            groups_table,
-            bindings,
-            TRACKS_PER_GROUP_NODE,
-            (start, count, next) => {
-                const inline_bindings = new Array(TRACKS_PER_GROUP_NODE);
-                for (let j = 0; j < TRACKS_PER_GROUP_NODE; j++) {
-                    if (j < count) {
-                        const b = bindings[start + j];
-
-                        assert.isNonNegativeInteger(b.track, `clip.bindings[${start + j}].track`);
-                        assert.isNonNegativeInteger(b.instance, `clip.bindings[${start + j}].instance`);
-                        assert.isNonNegativeInteger(b.property, `clip.bindings[${start + j}].property`);
-
-                        inline_bindings[j] = b;
-                    } else {
-                        inline_bindings[j] = ZERO_BINDING;
-                    }
-                }
-                return { bindings: inline_bindings, count, next, clip: clip_id };
-            }
-        );
-
-        // Patch the head pointer now that the chain exists. Re-`set` the
-        // whole record because the table API doesn't expose per-field
-        // updates.
-        clips_table.set(clip_id, {
-            time,
-            time_start,
-            time_end,
-            bound_track_group_head: head_group_id,
-            playback_rate: 1,
-            flags: 0,
-            playback_weight: 1,
-        });
-
-        return clip_id;
-    }
-
-    /**
-     * Overwrite a single field of a clip's record by reading the current
-     * record back from the CPU shadow and re-`set`ting with one field
-     * changed. The table API doesn't expose per-field updates, so we
-     * round-trip through a full record; the upload-buffer dedupe
-     * collapses the resulting per-frame write into a single GPU touch
-     * when nothing else changed.
-     *
-     * @param {number} clip_id
-     * @param {string} field
-     * @param {number} value
-     */
-    #patch_clip_field(clip_id, field, value) {
-        assert.isNonNegativeInteger(clip_id, 'clip_id');
-
-        const clips_table = this.#database.get('animation_clips');
-        const current = clips_table.get(clip_id);
-
-        clips_table.set(clip_id, {
-            time: current.time,
-            time_start: current.time_start,
-            time_end: current.time_end,
-            bound_track_group_head: current.bound_track_group_head,
-            playback_rate: current.playback_rate,
-            flags: current.flags,
-            playback_weight: current.playback_weight,
-            [field]: value,
-        });
-    }
-
-    /**
-     * Direct override of a clip's `time`. Bypasses {@link start} /
-     * {@link stop} — `time` is written even if the clip is paused, and
-     * the {@link AnimationClipFlags.Playing} bit is left untouched.
-     * The host typically uses this to scrub or rewind; GPU-driven
-     * playback advances time on its own via the tick shader.
-     *
-     * TODO: race between `start()` and `set_time()` is non-atomic — if
-     * a caller does `start(id); set_time(id, phase)` and the next GPU
-     * tick fires before the page upload from `set_time` lands, the
-     * tick advances from the old `time` for one frame. RIS would be
-     * an atomic `start_at(id, time, ...)` that fuses both field
-     * writes into one record set. For phase offsets the one-frame
-     * skew is invisible; for scrub-and-resume UIs it can show.
-     *
-     * @param {number} clip_id
-     * @param {number} time
-     */
-    set_time(clip_id, time) {
-        assert.isNumber(time, 'time');
-        this.#patch_clip_field(clip_id, 'time', time);
-    }
-
-    /**
-     * Direct override of a clip's per-frame advance scalar. `1.0` =
-     * realtime; `0.0` effectively pauses (independent of the
-     * {@link AnimationClipFlags.Playing} bit); negative values play
-     * in reverse.
-     *
-     * @param {number} clip_id
-     * @param {number} rate
-     */
-    set_playback_rate(clip_id, rate) {
-        assert.isNumber(rate, 'rate');
-        this.#patch_clip_field(clip_id, 'playback_rate', rate);
-    }
-
-    /**
-     * Override a clip's contribution weight into the pose accumulator.
-     * `1.0` is full strength; `0.0` silences the clip without removing
-     * its bindings; values in between blend it against other clips
-     * targeting the same nodes. The apply shader pre-multiplies every
-     * curve-evaluated value by this scalar before atomic-adding into
-     * the accumulator.
-     *
-     * Normalized blends expect weights across all clips driving a
-     * node to sum to `1`; additive layers use weights that don't sum
-     * to `1`. The system doesn't enforce either — host's call.
-     *
-     * @param {number} clip_id
-     * @param {number} weight
-     */
-    set_playback_weight(clip_id, weight) {
-        assert.isNumber(weight, 'weight');
-        this.#patch_clip_field(clip_id, 'playback_weight', weight);
-    }
-
-    /**
-     * Add (OR) one or more flag bits onto a clip's bitfield. Bits
-     * already set stay set; other bits are untouched. Values come
-     * from {@link AnimationClipFlags} and can be combined with `|`:
-     * `set_flags(id, AnimationClipFlags.Loop | AnimationClipFlags.Playing)`.
-     *
-     * Counterpart {@link clear_flags} ANDs the bits out. Together
-     * they cover the common cases without the overwrite footgun
-     * the original version had (where setting Loop would silently
-     * clear Playing).
-     *
-     * For toggling just the playing bit, {@link start} / {@link stop}
-     * are equivalent shortcuts.
-     *
-     * @param {number} clip_id
-     * @param {number} flags bits to set
-     */
-    set_flags(clip_id, flags) {
-        assert.isNonNegativeInteger(flags, 'flags');
-
-        const clips_table = this.#database.get('animation_clips');
-        const current = clips_table.get(clip_id);
-
-        this.#patch_clip_field(clip_id, 'flags', current.flags | flags);
-    }
-
-    /**
-     * Clear (AND-NOT) one or more flag bits from a clip's bitfield.
-     * Bits not present in `flags` are left untouched. Symmetric
-     * with {@link set_flags}.
-     *
-     * @param {number} clip_id
-     * @param {number} flags bits to clear
-     */
-    clear_flags(clip_id, flags) {
-        assert.isNonNegativeInteger(flags, 'flags');
-
-        const clips_table = this.#database.get('animation_clips');
-        const current = clips_table.get(clip_id);
-
-        this.#patch_clip_field(clip_id, 'flags', current.flags & ~flags);
-    }
-
-    /**
-     * Begin GPU-side playback. Sets the {@link AnimationClipFlags.Playing}
-     * bit; preserves every other flag bit, the current `time`, the
-     * `playback_rate`, and so on. Calling {@link stop} and then `start`
-     * back-to-back should feel like a no-op modulo at most one tick's
-     * worth of advance.
-     *
-     * Idempotent: starting an already-playing clip is a no-op (the
-     * upload-buffer dedupe collapses the write).
-     *
-     * @param {number} clip_id
-     */
-    start(clip_id) {
-        assert.isNonNegativeInteger(clip_id, 'clip_id');
-
-        const clips_table = this.#database.get('animation_clips');
-        const current = clips_table.get(clip_id);
-
-        this.#patch_clip_field(clip_id, 'flags', current.flags | AnimationClipFlags.Playing);
-    }
-
-    /**
-     * Pause GPU-side playback. Clears the {@link AnimationClipFlags.Playing}
-     * bit; preserves every other flag bit and the current `time`.
-     * Symmetric with {@link start} — a stop/start pair leaves the clip
-     * where it was (give or take one tick of GPU time loss).
-     *
-     * Idempotent: stopping an already-stopped clip is a no-op.
-     *
-     * @param {number} clip_id
-     */
-    stop(clip_id) {
-        assert.isNonNegativeInteger(clip_id, 'clip_id');
-
-        const clips_table = this.#database.get('animation_clips');
-        const current = clips_table.get(clip_id);
-
-        this.#patch_clip_field(clip_id, 'flags', current.flags & ~AnimationClipFlags.Playing);
-    }
-
-    /**
-     * Register a skin: an ordered list of joints, each pinning a
-     * Node3D row that drives the joint plus the inverse-bind matrix
-     * that takes vertex positions from mesh space into the joint's
-     * bind-pose local space. The skin reserves a contiguous range of
-     * `joints.length` matrices in the {@link #skin_matrices_buffer}
-     * scratch buffer; the prep pass populates that range each frame
-     * with `node.global × inverse_bind` for every joint.
-     *
-     * The skin record carries no mesh-world factor. The rasterizer
-     * applies `mesh.transform_global` to the skinned clone vertex
-     * via the standard mesh transform path
-     * ({@link chunk_mesh_resolve_vertex_position_world}), so adding
-     * an `inverse(mesh.global)` factor in the skin matrix would
-     * double-cancel against that re-application and shrink the rig
-     * back to mesh-local coordinates rendered as world.
-     *
-     * Joints are split into linked-list blocks of up to
-     * {@link JOINTS_PER_SKIN_BLOCK} each — same chain pattern used for
-     * bound-track groups and keyframe blocks. Each block records the
-     * absolute write offset for its slots, so the prep shader's
-     * per-thread work is one block load + a bounded inner loop with no
-     * indirection back through the skin record.
-     *
-     * @param {{
-     *     joints: Array<{ node: number, inverse_bind: Float32Array | number[] }>,
-     * }} skin
-     * @returns {number} skin id (index into the `animation_skins` table)
-     */
-    add_skin(skin) {
-        assert.defined(skin, 'skin');
-        assert.isArray(skin.joints, 'skin.joints');
-        assert.greaterThanOrEqual(skin.joints.length, 1, 'skin must have at least one joint');
-
-        const joints = skin.joints;
-        const joint_count = joints.length;
-
-        // Reserve the matrix range. Each block bakes in its absolute
-        // slot offset (skin_base + chain_position * JOINTS_PER_SKIN_BLOCK)
-        // so the prep shader writes directly without dereferencing
-        // the skin row for the offset; the base is also stashed on
-        // the CPU map so the skinning-binding upload can look it up
-        // without reading the GPU back.
-        const skin_matrix_offset = this.#next_skin_matrix_offset;
-        this.#next_skin_matrix_offset += joint_count;
-        this.#ensure_skin_matrices_capacity(this.#next_skin_matrix_offset);
-
-        const skins_table = this.#database.get('animation_skins');
-        const blocks_table = this.#database.get('animation_skin_joint_blocks');
-
-        // Reserve the skin row up front. The head pointer is patched
-        // in once the chain exists. NULL placeholder — 0 is a valid
-        // block row id (the first allocation in an empty table).
-        const skin_id = skins_table.add({
-            joint_block_head: ANIMATION_SKIN_JOINT_BLOCK_NULL,
-            joint_count,
-        });
-        this.#skin_matrix_offsets.set(skin_id, skin_matrix_offset);
-
-        const head_block_id = add_linked_chain(
-            blocks_table,
-            joints,
-            JOINTS_PER_SKIN_BLOCK,
-            (start, count, next) => {
-                const inline_joints = new Array(JOINTS_PER_SKIN_BLOCK);
-                for (let j = 0; j < JOINTS_PER_SKIN_BLOCK; j++) {
-                    if (j < count) {
-                        const joint = joints[start + j];
-
-                        assert.isNonNegativeInteger(joint.node, `skin.joints[${start + j}].node`);
-                        assert.defined(joint.inverse_bind, `skin.joints[${start + j}].inverse_bind`);
-
-                        inline_joints[j] = joint;
-                    } else {
-                        inline_joints[j] = ZERO_SKIN_JOINT;
-                    }
-                }
-                return {
-                    joints: inline_joints,
-                    count,
-                    next,
-                    skin_matrix_offset: skin_matrix_offset + start,
-                };
-            }
-        );
-
-        // Patch the head pointer now that the chain exists. Re-`set`
-        // the whole record because the table API doesn't expose
-        // per-field updates.
-        skins_table.set(skin_id, {
-            joint_block_head: head_block_id,
-            joint_count,
-        });
-
-        return skin_id;
-    }
-
-    /**
-     * High-level skin registration: consumes a {@link Skin} (CPU data
-     * with Node3D joint references and a flat inverse-bind matrix
-     * array), allocates a GPU skin record, and binds every entry in
-     * `skin.meshes` through the skinning context.
-     *
-     * **Eventual consistency.** The `skin_id` is allocated and
-     * returned synchronously — callers can immediately pass it to
-     * state mutators or {@link unregister_skin}. If any joint's
-     * Node3D hasn't been added to a scene yet (no `id_mapping` row),
-     * the joint-block chain that drives the deformation is queued
-     * and built on the next {@link update} that sees all joints
-     * resolved. The skin's table row uses a placeholder
-     * `joint_block_head` until then — observationally indistinguishable
-     * from "skin with no joints driving it" (no deformation runs).
-     *
-     * Mesh→skin bindings register immediately via
-     * {@link GPUMeshSkinningContext#bind}; the skinning context
-     * already tolerates pre-scene-build registration. Each mesh also
-     * gets its {@link SkinnedMesh#skin} reference and a fresh set of
-     * bounds off it, synchronously — that part does not wait for
-     * `id_mapping`, because it reads the joints' `transform_global`
-     * rather than any GPU row.
-     *
-     * @param {Skin} skin
-     * @returns {number} skin id (index into the `animation_skins` table)
-     */
-    register_skin(skin) {
-        assert.defined(skin, 'skin');
-        assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
-        assert.greaterThanOrEqual(skin.meshes.length, 1, 'skin.meshes must contain at least one mesh');
-
-        const joint_count = skin.joints.length;
-        const inverse_bind_matrices = skin.inverse_bind_matrices;
-
-        // Reserve the matrix range up front — block records carry
-        // their absolute slot offset, so the prep shader writes
-        // directly. The base also lands on #skin_matrix_offsets so
-        // skinning-binding upload can look it up.
-        const skin_matrix_offset = this.#next_skin_matrix_offset;
-        this.#next_skin_matrix_offset += joint_count;
-        this.#ensure_skin_matrices_capacity(this.#next_skin_matrix_offset);
-
-        // Reserve the skin row immediately with a placeholder head
-        // pointer. State mutators and the public id are usable from
-        // this point on; the joint chain gets patched in once
-        // id_mapping has every joint (possibly synchronously below,
-        // possibly deferred via the pending queue).
-        const skins_table = this.#database.get('animation_skins');
-        const skin_id = skins_table.add({
-            // NULL placeholder — 0 is a valid block row id
-            joint_block_head: ANIMATION_SKIN_JOINT_BLOCK_NULL,
-            joint_count,
-        });
-        this.#skin_matrix_offsets.set(skin_id, skin_matrix_offset);
-
-        // Bind every mesh into the skinning context. Idempotent and
-        // pre-build tolerant — the binding upload defers until
-        // id_mapping is ready.
-        //
-        // Each mesh also takes a reference to the CPU-side skin and
-        // re-derives its bounds off it. From here on the skin's
-        // formula is what places the mesh's vertices, and `Mesh`'s
-        // composition — rest-pose geometry under `transform_global` —
-        // is the wrong one, because the skinning pass cancels that
-        // transform back out (see {@link SkinnedMesh#updateBoundsBasic}).
-        // Nothing else would notice: bounds are refreshed by
-        // `updateMatrices`, and a character does not move again just
-        // because it finished loading.
-        // Before any of that: put the meshes into the frame this skin actually deforms in. The
-        // skinning pass writes each clone's vertices in `inverse(mesh.global)` space, so
-        // `mesh.global` is that frame — and glTF says a skinned mesh's node transform is ignored,
-        // which makes the frame the engine's to choose rather than the exporter's to get right.
-        // Ahead of the bind loop because it moves the mesh, and the bounds published below have to
-        // be the ones that survive. See `SKINNING_FRAME_PLAN.md`.
-        this.#normalize_skin_frame(skin);
-
-        this.#skins_by_id.set(skin_id, skin);
-
-        for (const clip of this.#scaling_clips.values()) {
-            this.#report_scale_conflicts(skin, clip);
-        }
-
-        const skinning = this.#scene_context.skinning;
-        const meshes = skin.meshes;
-        for (let i = 0; i < meshes.length; i++) {
-            const mesh = meshes[i];
-
-            skinning.bind(mesh, skin_id);
-
-            mesh.skin = skin;
-            mesh.updateBoundsBasic();
-
-            // The row the scene context published for this mesh holds the pre-skin bounds, and
-            // nothing about binding a skin looks like movement — `updateBoundsBasic` is not
-            // `updateMatrices` and does not touch the version the sync compares against. Without
-            // this the corrected box sits on the CPU object and never reaches the table.
-            mesh.needsUpdate = true;
-        }
-
-        // Try to complete now. If id_mapping is ready for every
-        // joint, the chain gets built and patched in. Otherwise the
-        // skin lands on #pending_skins and the next update() drain
-        // retries.
-        const pending = {
-            skin_id,
-            skin,
-            skin_matrix_offset,
-            inverse_bind_matrices,
-        };
-        if (!this.#try_complete_skin(pending)) {
-            this.#pending_skins.push(pending);
-        }
-
-        return skin_id;
-    }
-
-    /**
-     * Put a skin's meshes into the frame it deforms in, and say so when they cannot be.
-     *
-     * The correction itself is {@link skin_normalize_mesh_frame}, which is where the argument lives.
-     * This is the reporting: an asset that renders wrong should say which asset and by how much, on
-     * the frame it is registered, rather than reaching a person as a screenshot of soup.
-     *
-     * @param {Skin} skin
-     */
-    #normalize_skin_frame(skin) {
-        const report = skin_normalize_mesh_frame(skin);
-
-        // a glTF skin's `name` is optional and often absent; the mesh it deforms is what a person
-        // would recognise, and is what the asset's own hierarchy calls it
-        const label = skin.name !== '' ? skin.name : (skin.meshes[0]?.name ?? '<unnamed>');
-
-        if (report.unwalked.length > 0) {
-            console.error(
-                `skin '${label}': ${report.unwalked.length} of its nodes have never been walked — `
-                + `'${report.unwalked[0].name}' among them — so their world transforms are the `
-                + `identity by default rather than by derivation. Call updateMatrices on the scene `
-                + `before registering. Nothing was moved; the deformation will be wrong.`
-            );
-
-            return;
-        }
-
-        if (report.frame_defect > 0.001) {
-            console.error(
-                `skin '${label}': no frame can deform it — `
-                + `inverse(frame) × joint.global × inverse_bind is ${report.frame_defect.toFixed(4)} `
-                + `away from rigid at its own bind pose, and a dual quaternion carries a rotation and `
-                + `a translation and nothing else. The rest pose has a non-uniform scale or a shear `
-                + `in it. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §4.`
-            );
-
-            return;
-        }
-
-        if (report.residual > 0.001) {
-            console.error(
-                `skin '${label}': its mesh frame did not land — ${report.residual.toFixed(6)} `
-                + `left over. A correction carrying shear does not survive a Transform64's TRS `
-                + `components. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §3.`
-            );
-
-            return;
-        }
-
-        for (const mesh of report.obstructed) {
-            console.warn(
-                `skin '${label}': mesh node '${mesh.name}' carries the skin's frame now, and its `
-                + `${mesh.children.length} child node(s) inherit it. Sockets belong on bones.`
-            );
-        }
-
-        if (report.corrected > 0) {
-            // verbose rather than a warning: this is a legal asset shape, and a crowd of them would
-            // otherwise be a crowd of log lines
-            console.debug(
-                `skin '${label}': ${report.corrected} mesh frame(s) moved onto the skin's bind `
-                + `transform, absorbing ${report.absorbed.toFixed(4)} of non-rigidity the skinning `
-                + `pass could not have carried.`
-            );
-        }
-    }
-
-    /**
-     * Say so when a clip scales a skin's joints out from under the frame it is deformed in.
-     *
-     * The frame {@link skin_normalize_mesh_frame} chooses is fixed at registration, and it is sound
-     * because the joints and the mesh share their scaling ancestors. A scale that reaches only some
-     * of them breaks that every frame it plays, on the GPU, where nothing can see it —
-     * {@link skin_clip_scale_conflicts} is that question asked off the clip's own curves instead.
-     *
-     * Nothing is refused: the clip is legal animation and the skin is a legal skin, and it is their
-     * combination the skinning pass cannot carry. Refusing either would be picking one to blame.
-     *
-     * @param {Skin} skin
-     * @param {ShadeAnimationClip} clip
-     */
-    #report_scale_conflicts(skin, clip) {
-        const conflicts = skin_clip_scale_conflicts(skin, clip);
-
-        if (conflicts.length === 0) {
-            return;
-        }
-
-        const skin_label = skin.name !== '' ? skin.name : (skin.meshes[0]?.name ?? '<unnamed>');
-
-        const nodes = conflicts.map(conflict => conflict.node.name || '<unnamed>').join(', ');
-
-        const uniform = conflicts.every(conflict => conflict.uniform);
-
-        console.error(
-            `clip '${clip.name}' scales ${conflicts.length} node(s) of skin '${skin_label}' — `
-            + `${nodes} — which reach its joints but not its mesh, so the scale enters the joint `
-            + `matrices and not the frame they are folded against. A dual quaternion cannot carry `
-            + `it and no choice of frame fixes it: the deformation will be wrong while this clip `
-            + `plays. `
-            + (uniform
-                ? `The scale is uniform, which SKINNING_FRAME_PLAN.md §4 has a design for.`
-                : `The scale is non-uniform, which no dual quaternion holds — §4's linear-blend `
-                + `path or an import-time refusal.`)
-        );
-    }
-
-    /**
-     * Attempt to build the joint-block chain for a pending skin and
-     * patch its head pointer onto the skin row. Returns `true` when
-     * every joint Node3D has resolved to a transforms-table row
-     * (and the chain was built); `false` when at least one joint is
-     * still missing.
-     *
-     * @param {{
-     *     skin_id: number,
-     *     skin: Skin,
-     *     skin_matrix_offset: number,
-     *     inverse_bind_matrices: Float32Array,
-     * }} pending
-     * @returns {boolean}
-     */
-    #try_complete_skin(pending) {
-        const id_mapping = this.#scene_context.id_mapping;
-        const joint_nodes = pending.skin.joints;
-        const joint_count = joint_nodes.length;
-        const inverse_bind_matrices = pending.inverse_bind_matrices;
-        const skin_matrix_offset = pending.skin_matrix_offset;
-        const skin_id = pending.skin_id;
-
-        // All-or-nothing: a single missing row leaves the chain
-        // unbuilt — partial chains aren't valid (the prep shader
-        // walks every block).
-        const joints = new Array(joint_count);
-        for (let i = 0; i < joint_count; i++) {
-            const node = joint_nodes[i];
-            const row = id_mapping.get(node.id);
-            if (row === undefined) return false;
-
-            joints[i] = {
-                node: row,
-                // Per-joint slice of the flat matrix array. The
-                // marshaller copies these bytes into the skin-joint
-                // block record; sub-array views are fine — they
-                // share the underlying buffer but write_struct_value
-                // reads by length, not by offset.
-                inverse_bind: inverse_bind_matrices.subarray(i * 16, (i + 1) * 16),
-            };
-        }
-
-        const blocks_table = this.#database.get('animation_skin_joint_blocks');
-        const head_block_id = add_linked_chain(
-            blocks_table,
-            joints,
-            JOINTS_PER_SKIN_BLOCK,
-            (start, count, next) => {
-                const inline_joints = new Array(JOINTS_PER_SKIN_BLOCK);
-                for (let j = 0; j < JOINTS_PER_SKIN_BLOCK; j++) {
-                    inline_joints[j] = j < count ? joints[start + j] : ZERO_SKIN_JOINT;
-                }
-                return {
-                    joints: inline_joints,
-                    count,
-                    next,
-                    skin_matrix_offset: skin_matrix_offset + start,
-                };
-            }
-        );
-
-        // Patch the head pointer onto the already-allocated skin
-        // row. Read-modify-write so any other fields the user might
-        // have changed via mutators (none today, but future-proof)
-        // are preserved.
-        const skins_table = this.#database.get('animation_skins');
-        const current = skins_table.get(skin_id);
-        skins_table.set(skin_id, {
-            joint_block_head: head_block_id,
-            joint_count: current.joint_count,
-        });
-
-        return true;
-    }
-
-    /**
-     * High-level clip registration: consumes a {@link ShadeAnimationClip}
-     * (CPU data with Node3D targets and per-component curves), uploads
-     * curves and tracks, and creates the GPU clip record.
-     *
-     * **Eventual consistency.** The `clip_id` is allocated and
-     * returned synchronously — callers can immediately call
-     * {@link start} / {@link stop} / {@link set_time} /
-     * {@link set_playback_rate} / {@link set_flags} / {@link clear_flags}
-     * / {@link set_playback_weight} / {@link unregister_clip}. If
-     * any channel target's Node3D hasn't been added to a scene yet
-     * (no `id_mapping` row), the bindings chain that drives the
-     * apply pass is queued and built on the next {@link update}
-     * that sees all targets resolved. The clip's table row uses a
-     * placeholder `bound_track_group_head` until then — apply
-     * produces no contributions, so the clip is observationally
-     * inert (still subject to time advancement via the tick shader
-     * if `Playing` is set).
-     *
-     * Curves and tracks are interned synchronously since they're
-     * pure data — no `id_mapping` dependency.
-     *
-     * @param {ShadeAnimationClip} clip
-     * @returns {number} clip id
-     */
-    register_clip(clip) {
-        assert.defined(clip, 'clip');
-        assert.equal(clip.isShadeAnimationClip, true, 'clip.isShadeAnimationClip !== true');
-
-        const channels = clip.channels;
-
-        // Intern every channel's curves + track now. None of this
-        // depends on id_mapping — pure data uploads.
-        //
-        // Each curve goes through #intern_curve so two channels
-        // referencing the same AnimationCurve instance share one
-        // GPU upload. With 324 dancers retargeted at the same base
-        // clip this turns 324 × 195 channel uploads into 1 (the
-        // curves are read-only animation data — identical bytes
-        // wherever they're referenced).
-        const pending_channels = new Array(channels.length);
-        for (let i = 0; i < channels.length; i++) {
-            const channel = channels[i];
-            const curves = channel.curves;
-            const track_channels = {};
-            if (curves.x !== undefined) track_channels.x = this.#intern_curve(curves.x);
-            if (curves.y !== undefined) track_channels.y = this.#intern_curve(curves.y);
-            if (curves.z !== undefined) track_channels.z = this.#intern_curve(curves.z);
-            if (curves.w !== undefined) track_channels.w = this.#intern_curve(curves.w);
-
-            pending_channels[i] = {
-                track: this.#intern_track(track_channels),
-                target: channel.target,
-                property: channel.property,
-            };
-        }
-
-        // Reserve the clip row immediately with a placeholder head
-        // pointer. State mutators and the public id are usable from
-        // this point on; the bindings chain gets patched in once
-        // id_mapping has every target. `time` defaults to 0 (the
-        // playback offset relative to `time_start`; the apply
-        // shader does `effective_time = clip.time + clip.time_start`).
-        const clips_table = this.#database.get('animation_clips');
-        const clip_id = clips_table.add({
-            time: 0,
-            time_start: clip.start_time,
-            time_end: clip.end_time,
-            bound_track_group_head: ANIMATION_BOUND_TRACK_GROUP_NULL,
-            playback_rate: 1,
-            flags: 0,
-            playback_weight: 1,
-        });
-
-        const pending = { clip_id, channels: pending_channels };
-        if (!this.#try_complete_clip(pending)) {
-            this.#pending_clips.push(pending);
-        }
-
-        /*
-         Asked cheaply first: a clip with no scale channel at all — which is every clip a character
-         normally carries — is dismissed in one pass over its channels and remembered by nothing. Only
-         a clip that scales something is worth holding against the skins, now and as more arrive.
-        */
-        if (clip_scale_channels(clip).length > 0) {
-            this.#scaling_clips.set(clip_id, clip);
-
-            for (const skin of this.#skins_by_id.values()) {
-                this.#report_scale_conflicts(skin, clip);
-            }
-        }
-
-        return clip_id;
-    }
-
-    /**
-     * Attempt to build the bindings chain for a pending clip and
-     * patch its head pointer onto the clip row. Returns `true` when
-     * every channel target has resolved to a transforms-table row
-     * (and the chain was built); `false` when at least one is still
-     * missing.
-     *
-     * @param {{
-     *     clip_id: number,
-     *     channels: Array<{ track: number, target: Node3D, property: number }>,
-     * }} pending
-     * @returns {boolean}
-     */
-    #try_complete_clip(pending) {
-        const id_mapping = this.#scene_context.id_mapping;
-        const channels = pending.channels;
-        const clip_id = pending.clip_id;
-
-        const bindings = new Array(channels.length);
-        for (let i = 0; i < channels.length; i++) {
-            const ch = channels[i];
-            const instance = id_mapping.get(ch.target.id);
-            if (instance === undefined) return false;
-
-            bindings[i] = {
-                track: ch.track,
-                instance,
-                property: ch.property,
-            };
-        }
-
-        const groups_table = this.#database.get('animation_bound_track_groups');
-        const head_group_id = add_linked_chain(
-            groups_table,
-            bindings,
-            TRACKS_PER_GROUP_NODE,
-            (start, count, next) => {
-                const inline_bindings = new Array(TRACKS_PER_GROUP_NODE);
-                for (let j = 0; j < TRACKS_PER_GROUP_NODE; j++) {
-                    inline_bindings[j] = j < count ? bindings[start + j] : ZERO_BINDING;
-                }
-                return { bindings: inline_bindings, count, next, clip: clip_id };
-            }
-        );
-
-        // Patch the head pointer onto the already-allocated clip
-        // row. Read-modify-write preserves any user-driven state
-        // changes (set_time, set_flags, etc.) made between
-        // register_clip and the drain.
-        this.#patch_clip_field(clip_id, 'bound_track_group_head', head_group_id);
-
-        return true;
-    }
-
-    /**
-     * Drop a clip from the manager. Walks the bindings chain and
-     * removes every group-node + the clip row. Tolerates the clip
-     * still being pending (drains it from the queue without GPU
-     * touches besides the original row removal).
-     *
-     * Curves and tracks the clip referenced stay alive — they're
-     * shared via {@link #intern_curve} / {@link #intern_track} and
-     * may be in use by other clips. Removing them would need
-     * reference-counting the manager doesn't carry.
-     *
-     * Safe to call repeatedly on the same id (subsequent calls are
-     * no-ops once the row is gone).
-     *
-     * @param {number} clip_id
-     */
-    unregister_clip(clip_id) {
-        assert.isNonNegativeInteger(clip_id, 'clip_id');
-
-        // Drop from pending queue if present (skip-and-keep-others
-        // pattern is cheaper than splice for the rare case of
-        // dozens-of-pending; if pending depth grows this can be
-        // revisited).
-        for (let i = this.#pending_clips.length - 1; i >= 0; i--) {
-            if (this.#pending_clips[i].clip_id === clip_id) {
-                this.#pending_clips.splice(i, 1);
-            }
-        }
-
-        const clips_table = this.#database.get('animation_clips');
-        const groups_table = this.#database.get('animation_bound_track_groups');
-
-        const clip_record = clips_table.get(clip_id);
-        if (clip_record === undefined) return;
-
-        // Walk the bindings chain and remove every node. The chain
-        // may be empty (placeholder head NULL) if the clip is still
-        // pending or has been registered then drained but never
-        // completed; both cases skip the loop.
-        let block_id = clip_record.bound_track_group_head;
-        while (block_id !== ANIMATION_BOUND_TRACK_GROUP_NULL) {
-            const block = groups_table.get(block_id);
-            const next_id = block !== undefined ? block.next : ANIMATION_BOUND_TRACK_GROUP_NULL;
-            groups_table.remove(block_id);
-            block_id = next_id;
-        }
-
-        clips_table.remove(clip_id);
-
-        this.#scaling_clips.delete(clip_id);
-    }
-
-    /**
-     * Drop a skin from the manager. Walks the joint-block chain and
-     * removes every block + the skin row, and tears down every
-     * skinning binding pointing at this skin (so the skinning
-     * context doesn't try to read the now-freed skin's matrix
-     * offset on its next upload).
-     *
-     * The skin's reserved matrix range stays allocated — compaction
-     * isn't supported in the MVP. Re-registering after an
-     * `unregister_skin` therefore costs new matrix slots; long-
-     * running spawn/despawn loops accumulate wasted slots.
-     *
-     * Tolerates the skin still being pending. Safe to call
-     * repeatedly on the same id.
-     *
-     * @param {number} skin_id
-     */
-    unregister_skin(skin_id) {
-        assert.isNonNegativeInteger(skin_id, 'skin_id');
-
-        this.#skins_by_id.delete(skin_id);
-
-        for (let i = this.#pending_skins.length - 1; i >= 0; i--) {
-            if (this.#pending_skins[i].skin_id === skin_id) {
-                this.#pending_skins.splice(i, 1);
-            }
-        }
-
-        // Tear down skinning bindings first so the skinning
-        // context's next upload doesn't reference a freed skin row
-        // (its upload path looks up skin_matrix_offset via
-        // get_skin_matrix_offset, which would assert post-removal).
-        this.#scene_context.skinning.unbind_all_by_skin(skin_id);
-
-        const skins_table = this.#database.get('animation_skins');
-        const blocks_table = this.#database.get('animation_skin_joint_blocks');
-
-        const skin_record = skins_table.get(skin_id);
-        if (skin_record === undefined) {
-            this.#skin_matrix_offsets.delete(skin_id);
-            return;
-        }
-
-        // Walk the joint-block chain, terminating on the NULL
-        // sentinel (also the placeholder for a not-yet-patched head).
-        // Note: 0 is a VALID block row id — the first single-block
-        // skin registered into an empty table gets head 0, and
-        // treating it as a placeholder would leak its block, leaving
-        // the prep shader processing it against a recycled
-        // transforms-table row every frame.
-        let block_id = skin_record.joint_block_head;
-        while (block_id !== ANIMATION_SKIN_JOINT_BLOCK_NULL) {
-            const block = blocks_table.get(block_id);
-            const next_id = block !== undefined ? block.next : ANIMATION_SKIN_JOINT_BLOCK_NULL;
-            blocks_table.remove(block_id);
-            block_id = next_id;
-        }
-
-        skins_table.remove(skin_id);
-        this.#skin_matrix_offsets.delete(skin_id);
-    }
-
-    /**
-     * Cached wrapper around {@link add_curve}: one upload per distinct curve, where distinct means
-     * distinct *content*.
-     *
-     * The instance cache answers first — the common case inside one clip, and free. Otherwise the
-     * curve's keys are hashed and held against every uploaded curve with that hash; a match on
-     * every key, tangents included, reuses that upload, and only a curve nobody has uploaded before
-     * goes through the low-level path. Either way the instance is remembered, so the next look-up
-     * of it is the free one.
-     *
-     * @param {AnimationCurve} curve
-     * @returns {number} curve id (index into the `animation_curves` table)
-     */
-    #intern_curve(curve) {
-        const cached = this.#curve_id_cache.get(curve);
-
-        if (cached !== undefined) {
-            return cached;
-        }
-
-        const hash = curve.hash();
-
-        let bucket = this.#curve_id_by_content.get(hash);
-
-        if (bucket === undefined) {
-            bucket = [];
-
-            this.#curve_id_by_content.set(hash, bucket);
-        } else {
-            for (const entry of bucket) {
-                if (entry.curve.equals(curve)) {
-                    this.#curve_id_cache.set(curve, entry.id);
-
-                    return entry.id;
-                }
-            }
-        }
-
-        const id = this.add_curve(curve);
-
-        this.#curve_id_cache.set(curve, id);
-
-        bucket.push({ curve, id });
-
-        return id;
-    }
-
-    /**
-     * Cache-keyed wrapper around {@link add_track}. Two channels that
-     * end up with the same (x, y, z, w, mask) — typical when their
-     * source curves are shared via {@link #intern_curve} — collapse
-     * to one track row instead of one row per channel.
-     *
-     * @param {{ x?: number, y?: number, z?: number, w?: number }} channels
-     * @returns {number} track id
-     */
-    #intern_track(channels) {
-        // Pack into a deterministic string key. -1 sentinel for
-        // missing channels keeps the (x=undefined) and (x=0) cases
-        // distinct.
-        const cx = channels.x ?? -1;
-        const cy = channels.y ?? -1;
-        const cz = channels.z ?? -1;
-        const cw = channels.w ?? -1;
-        const key = `${cx},${cy},${cz},${cw}`;
-
-        const cached = this.#track_id_cache.get(key);
-        if (cached !== undefined) {
-            return cached;
-        }
-        const id = this.add_track(channels);
-        this.#track_id_cache.set(key, id);
-        return id;
-    }
-
-    /**
-     * Grow the skinning-matrix scratch buffer if `required_count`
-     * exceeds current capacity. Doubles on grow until the requirement
-     * fits. The buffer's contents are scratch (rewritten every frame by
-     * the prep pass), so growth doesn't need to copy old data — but it
-     * does invalidate the previous {@link #skin_matrices_buffer}
-     * reference, which is why callers re-fetch through the getter.
-     *
-     * @param {number} required_count number of matrices that must fit
-     */
-    #ensure_skin_matrices_capacity(required_count) {
-        if (required_count <= this.#skin_matrices_capacity) {
-            return;
-        }
-
-        let new_capacity = Math.max(this.#skin_matrices_capacity, SKIN_MATRICES_INITIAL_CAPACITY);
-        while (new_capacity < required_count) {
-            new_capacity *= 2;
-        }
-
-        // Grow both ping-pong buffers in lockstep — they always share
-        // capacity. After grow both are zero-initialised, so the next
-        // prep dispatch needs to seed "previous" from "current"
-        // (otherwise velocity would interpolate against zero
-        // matrices). The flag below tells dispatch_skin_matrix_prep
-        // to issue that copy.
-        for (let i = 0; i < 2; i++) {
-            if (this.#skin_matrices_buffers[i] !== null) {
-                this.#skin_matrices_buffers[i].destroy();
-            }
-            this.#skin_matrices_buffers[i] = this.#device.createBuffer({
-                label: `${this.#label}/SkinMatrices/${i}`,
-                size: new_capacity * SKIN_MATRIX_BYTES,
-                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
-            });
-        }
-        this.#skin_matrices_capacity = new_capacity;
-        this.#first_frame_skin_matrices = true;
-    }
-
-    /**
-     * Flush all pending uploads (curves, keyframe blocks, tracks, clips,
-     * bound-track groups, skins, skin joint blocks) into the GPU
-     * database. Call once per frame, before any shader that reads from
-     * `database.buffer`.
-     *
-     * Also drains the pending-registration queues: skins and clips
-     * whose dependencies (joint Node3D rows, channel-target rows)
-     * weren't ready at register time get one shot per `update` to
-     * complete. Once `id_mapping` has the missing rows, the
-     * deferred chain build runs and the registration becomes
-     * observationally complete — the next-frame `database.update`
-     * picks up the patched head pointer.
-     *
-     * Does not touch the skin-matrices ping-pong buffers — those
-     * are scratch populated each frame by
-     * {@link dispatch_skin_matrix_prep}, not host data.
-     *
-     * @param {ShadeGPUCommandContext} cmd_ctx
-     */
-    update(cmd_ctx) {
-        this.#drain_pending_skins();
-        this.#drain_pending_clips();
-        this.#database.update(cmd_ctx);
-    }
-
-    #drain_pending_skins() {
-        // Walk back-to-front so successful completions can splice
-        // without disturbing the iteration's remaining indices.
-        for (let i = this.#pending_skins.length - 1; i >= 0; i--) {
-            if (this.#try_complete_skin(this.#pending_skins[i])) {
-                this.#pending_skins.splice(i, 1);
-            }
-        }
-    }
-
-    #drain_pending_clips() {
-        for (let i = this.#pending_clips.length - 1; i >= 0; i--) {
-            if (this.#try_complete_clip(this.#pending_clips[i])) {
-                this.#pending_clips.splice(i, 1);
-            }
-        }
-    }
-
-    /**
-     * Run the per-frame skin-matrix-prep dispatch and advance the
-     * ping-pong. Replaces the manual `shader_skin_matrix_prep.dispatch`
-     * the prototypes used to call — wrapping it here is how we get
-     * correct ping-pong behaviour across frames without leaking the
-     * buffer-role bookkeeping into every caller.
-     *
-     * No-op when no skins are registered (`group_count_x === 0`).
-     *
-     * Per-frame ordering:
-     *  1. Flip {@link #skin_matrices_current_index} — the buffer that
-     *     was last frame's "current" is about to be overwritten with
-     *     this frame's matrices; the other buffer (last frame's prev)
-     *     becomes this frame's "previous" implicit data source for
-     *     {@link prev_skin_matrices_buffer}.
-     *  2. Wait — clarify: we want last frame's "current" to BECOME
-     *     this frame's "previous". So flipping current_index moves
-     *     the role tag the correct way: what was current[i] becomes
-     *     previous (= buffers[1 - i]), and current[1 - i] is the
-     *     write target.
-     *  3. Dispatch the prep shader into the new current.
-     *  4. On the very first frame (or after a grow), copy current →
-     *     previous so the first velocity reads see matching matrices
-     *     and produce zero velocity.
-     *
-     * @param {ShadeGPUCommandContext} cmd_ctx
-     */
-    dispatch_skin_matrix_prep(cmd_ctx) {
-        const groups = this.#database
-            .get('animation_skin_joint_blocks')
-            .dispatch_group_count(SKIN_MATRIX_PREP_WORKGROUP_SIZE);
-        if (groups === 0) {
-            return;
-        }
-
-        // Flip the ping-pong: what was "current" last frame is no
-        // longer current, but it still holds valid matrices — and
-        // through the role flip it becomes this frame's
-        // `prev_skin_matrices_buffer`. The buffer we're flipping TO
-        // (the new "current") held two-frames-old matrices, about to
-        // be overwritten.
-        this.#skin_matrices_current_index = 1 - this.#skin_matrices_current_index;
-
-        const current = this.#skin_matrices_buffers[this.#skin_matrices_current_index];
-        const previous = this.#skin_matrices_buffers[1 - this.#skin_matrices_current_index];
-
-        shader_skin_matrix_prep.dispatch({
-            encoder: cmd_ctx,
-            group_count_x: groups,
-            bindings: {
-                animation_database: this.#database.buffer,
-                scene_database: this.#scene_context.scene_database_buffer,
-                skin_matrices: current,
-            },
-        });
-
-        // First-frame init (or post-grow): "previous" buffer is
-        // zero-initialised, which would have the velocity pass
-        // interpolate against the origin and produce huge nonsense
-        // on the first frame the skin appears. Seed prev from
-        // current — first velocity reads then yield zero, which is
-        // the right answer (no motion has happened yet).
-        if (this.#first_frame_skin_matrices) {
-            cmd_ctx.copyBufferToBuffer(
-                current, 0,
-                previous, 0,
-                current.size,
-            );
-            this.#first_frame_skin_matrices = false;
-        }
-    }
-
-    /**
-     * Per-frame orchestrator: drains pending registrations and the
-     * database queue, runs the GPU tick (advances `clip.time`),
-     * applies tracks into the pose accumulator, resolves the
-     * accumulator into node TRS, propagates the transform
-     * hierarchy, preps skinning matrices, and runs the skinning
-     * compute pass that deforms cloned vertex regions in place.
-     *
-     * One call replaces the ~80-line per-frame dispatch block every
-     * consumer would otherwise duplicate; the shader identities,
-     * workgroup sizes, pose-accumulator sizing, and pass ordering
-     * are all internal.
-     *
-     * `dt_seconds` is wall-clock seconds since the last call (the
-     * caller measures via `performance.now()` or equivalent). It's
-     * clamped to {@link MAX_DT_SECONDS} to keep a stall from
-     * leaking multiple seconds into the next tick.
-     *
-     * Clip tick/apply/resolve gate on bound tracks; hierarchy propagation runs
-     * every frame, before skin matrix prep and skinning. CPU-driven nodes need it
-     * too: scene uploads seed global with the previous pose, and propagation
-     * composes the current one. On idle frames it advances prev_global so motion
-     * vectors settle to zero. Skin passes still gate on registered skins.
-     *
-     * @param {ShadeGPUCommandContext} cmd_ctx
-     * @param {number} dt_seconds wall-clock seconds since last call
-     */
-    tick(cmd_ctx, dt_seconds) {
-        assert.defined(cmd_ctx, 'cmd_ctx');
-        assert.isNumber(dt_seconds, 'dt_seconds');
-
-        // Cap dt so a long stall doesn't fly the clip through dozens
-        // of loops or clamp it past the meaningful range.
-        const dt = Math.min(dt_seconds, MAX_DT_SECONDS);
-
-        // Flush database + drain pending registrations.
-        this.update(cmd_ctx);
-
-        // Only clip evaluation is conditional. Every scene needs current globals.
-        const apply_groups = this.#database
-            .get('animation_bound_track_groups')
-            .dispatch_group_count(ANIMATION_APPLY_WORKGROUP_SIZE);
-
-        if (apply_groups > 0) {
-            this.#encode_clip_passes(cmd_ctx, dt, apply_groups);
-        } else {
-            // CPU uploads seed global with the previous pose. Even without clips,
-            // compose current globals and advance prev_global before skinning/rendering.
-            const graph = new FrameGraph("GPUAnimationManager/TransformHierarchy");
-            graph_scene_update_transform_hierarchy({ graph, scene: this.#scene_context });
-            cmd_ctx.encodeGraph(graph);
-        }
-
-        // Skin matrix prep + skinning deformation. Both no-op when
-        // no skins are registered — and both run independent of the
-        // bound-track gate above: a registered skin whose joints
-        // are host-driven (no clips bound) must still be deformed
-        // each frame, otherwise it renders bind pose forever.
-        this.dispatch_skin_matrix_prep(cmd_ctx);
-        this.#scene_context.skinning.update(cmd_ctx);
-    }
-
-    /**
-     * Encode the clip-driven passes: GPU tick (advances
-     * `clip.time`), track apply into the pose accumulator, pose
-     * resolve into node TRS, and transform-hierarchy propagation.
-     * Split out of {@link tick} so the skin passes there run
-     * independently of the bound-track early-out.
-     *
-     * @param {ShadeGPUCommandContext} cmd_ctx
-     * @param {number} dt clamped delta time, seconds
-     * @param {number} apply_groups dispatch group count for the
-     *     apply pass — caller guarantees `> 0`
-     */
-    #encode_clip_passes(cmd_ctx, dt, apply_groups) {
-        // Tick: advance clip.time on the GPU.
-        const tick_groups = this.#database
-            .get('animation_clips')
-            .dispatch_group_count(ANIMATION_TICK_WORKGROUP_SIZE);
-        if (tick_groups > 0) {
-            shader_animation_tick.dispatch({
-                encoder: cmd_ctx,
-                group_count_x: tick_groups,
-                bindings: {
-                    dt,
-                    animation_database: this.#database.buffer,
-                },
-            });
-        }
-
-        // Size the pose accumulator to cover every allocated row of
-        // the transforms table — apply writes by absolute row index,
-        // resolve iterates the table via page iterator.
-        const transforms_table = this.#scene_context.scene_database.get('transforms');
-        const resolve_groups = transforms_table.dispatch_group_count(
-            ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE
-        );
-        this.ensure_pose_accumulator_capacity(transforms_table.element_capacity);
-
-        // ── Frame graph: apply → pose resolve → hierarchy propagate
-        const graph = new FrameGraph("GPUAnimationManager/Tick");
-        const gr_animation_database = graph_import_buffer(
-            graph, this.#database.buffer, "animation_database"
-        );
-        const gr_scene_database = graph_import_buffer(
-            graph, this.#scene_context.scene_database_buffer, "scene_database"
-        );
-        const gr_materials = graph_import_buffer(
-            graph, this.#scene_context.materials.metadata_table.buffer, "materials"
-        );
-        const gr_pose_accumulator = graph_import_buffer(
-            graph, this.#pose_accumulator_buffer, "pose_accumulator"
-        );
-
-        const apply_data = {};
-        const apply_pass = graph.add("animation/apply", apply_data, (data, resources, ctx) => {
-            shader_animation_apply.dispatch({
-                encoder: ctx.encoder,
-                group_count_x: apply_groups,
-                bindings: {
-                    animation_database: resources.get(data.animation_database),
-                    pose_accumulator: resources.get(data.pose_accumulator),
-                    materials: resources.get(data.materials),
-                },
-            });
-        });
-        apply_data.animation_database = apply_pass.read(gr_animation_database);
-        apply_data.materials = apply_pass.write(apply_pass.read(gr_materials));
-        apply_data.pose_accumulator = apply_pass.write(apply_pass.read(gr_pose_accumulator));
-
-        const resolve_data = {};
-        const resolve_pass = graph.add("animation/pose_resolve", resolve_data, (data, resources, ctx) => {
-            if (resolve_groups === 0) return;
-            shader_animation_pose_resolve.dispatch({
-                encoder: ctx.encoder,
-                group_count_x: resolve_groups,
-                bindings: {
-                    scene_database: resources.get(data.scene_database),
-                    pose_accumulator: resources.get(data.pose_accumulator),
-                },
-            });
-        });
-        resolve_data.scene_database = resolve_pass.write(resolve_pass.read(gr_scene_database));
-        resolve_data.pose_accumulator = resolve_pass.write(resolve_pass.read(apply_data.pose_accumulator));
-
-        graph_scene_update_transform_hierarchy({
-            graph,
-            scene: this.#scene_context,
-            scene_database: resolve_data.scene_database,
-        });
-
-        cmd_ctx.encodeGraph(graph);
-    }
-
-    destroy() {
-        this.#database.destroy();
-        for (let i = 0; i < 2; i++) {
-            if (this.#skin_matrices_buffers[i] !== null) {
-                this.#skin_matrices_buffers[i].destroy();
-                this.#skin_matrices_buffers[i] = null;
-            }
-        }
-        if (this.#pose_accumulator_buffer !== null) {
-            this.#pose_accumulator_buffer.destroy();
-            this.#pose_accumulator_buffer = null;
-        }
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { FrameGraph } from "../../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
+import {
+    graph_scene_update_transform_hierarchy
+} from "../scene/hierarchy/graph_scene_update_transform_hierarchy.js";
+import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
+import {
+    ANIMATION_BOUND_TRACK_GROUP_NULL,
+    TRACKS_PER_GROUP_NODE,
+} from "./ANIMATION_BOUND_TRACK_GROUP_STRUCT.js";
+import { ANIMATION_DATABASE_SPEC } from "./ANIMATION_DATABASE_SPEC.js";
+import { AnimationClipFlags } from "./AnimationClipFlags.js";
+import { KEYFRAMES_PER_BLOCK } from "./ANIMATION_KEYFRAME_BLOCK_STRUCT.js";
+import {
+    ANIMATION_SKIN_JOINT_BLOCK_NULL,
+    JOINTS_PER_SKIN_BLOCK,
+} from "./ANIMATION_SKIN_JOINT_BLOCK_STRUCT.js";
+import { POSE_ACCUMULATOR_SLOT_BYTES } from "./POSE_ACCUMULATOR_LAYOUT.js";
+import {
+    clip_scale_channels,
+    skin_clip_scale_conflicts
+} from "./skin_clip_scale_conflicts.js";
+import { skin_normalize_mesh_frame } from "./skin_normalize_mesh_frame.js";
+import {
+    shader_animation_apply,
+    WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE,
+} from "./shader_animation_apply.js";
+import {
+    shader_animation_pose_resolve,
+    WORKGROUP_SIZE as ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE,
+} from "./shader_animation_pose_resolve.js";
+import {
+    shader_animation_tick,
+    WORKGROUP_SIZE as ANIMATION_TICK_WORKGROUP_SIZE,
+} from "./shader_animation_tick.js";
+import {
+    shader_skin_matrix_prep,
+    WORKGROUP_SIZE as SKIN_MATRIX_PREP_WORKGROUP_SIZE,
+} from "./skinning/shader_skin_matrix_prep.js";
+
+/**
+ * @typedef {import("../../../engine/animation/curve/AnimationCurve.js").AnimationCurve} AnimationCurve
+ * @typedef {import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ * @typedef {import("../scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("./ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ * @typedef {import("./Skin.js").Skin} Skin
+ */
+
+/**
+ * Tail-slot placeholders for the fixed-size inline arrays in chain
+ * nodes. The shader's `count` guard means these bytes are never read,
+ * but the upload buffer doesn't zero unwritten ranges and
+ * `write_struct_value` skips undefined fields — so explicit zeros are
+ * the only way to keep tail bytes deterministic. Frozen so a stray
+ * mutation can't bleed into multiple slots that share the reference.
+ */
+const ZERO_KEYFRAME = Object.freeze({ time: 0, value: 0, inTangent: 0, outTangent: 0 });
+const ZERO_BINDING = Object.freeze({ track: 0, instance: 0, property: 0 });
+// Object.freeze on a typed array with elements throws under V8
+// ("Cannot freeze array buffer views with elements"), so we leave the
+// Float32Array unfrozen — the surrounding placeholder object is still
+// frozen to keep accidental field-level mutation out of bounds.
+const ZERO_INVERSE_BIND = new Float32Array(16);
+const ZERO_SKIN_JOINT = Object.freeze({ node: 0, inverse_bind: ZERO_INVERSE_BIND });
+
+/**
+ * One skinning matrix is a `mat4x4f` — 16 f32s, 64 bytes. The
+ * `skin_matrices` scratch buffer holds one entry per (skin, joint) pair
+ * across every registered skin.
+ */
+const SKIN_MATRIX_BYTES = 64;
+
+/**
+ * Initial capacity of the `skin_matrices` scratch buffer, in matrices.
+ * 256 × 64 = 16 KB — fits a handful of small skeletons before the first
+ * grow. Picked to be wasteful neither at "no skins" nor "one character"
+ * scale; growth doubles, so a few realloc cycles cover anything larger.
+ */
+const SKIN_MATRICES_INITIAL_CAPACITY = 256;
+
+/**
+ * Initial capacity of the {@link #pose_accumulator_buffer} in rows
+ * (= transforms-table slots). 256 × 64 = 16 KB; growth doubles to
+ * fit larger scenes. Resolve always zeroes the slot after draining,
+ * so a fresh buffer (createBuffer is zero-initialised) and a "no
+ * contribution this frame" state are observationally identical.
+ */
+const POSE_ACCUMULATOR_INITIAL_CAPACITY = 256;
+
+/**
+ * Per-frame `dt` cap pushed into the tick shader. Without it, a tab
+ * backgrounded for several seconds (or a paused debugger) would
+ * leak that whole interval into the next tick — either rocketing a
+ * looping clip through dozens of cycles in one step or, for
+ * non-looping clips, clamping them past the meaningful range. The
+ * cap trades a few frames of CSS-smooth animation after a stall
+ * for a deterministic clip state.
+ */
+const MAX_DT_SECONDS = 1 / 15;
+
+/**
+ * Allocate a singly-linked chain of fixed-capacity nodes into `table`,
+ * one node per `items_per_chunk`-sized window of `items`. Builds
+ * tail-first so each node's successor id is known at `add()` time —
+ * the alternative (forward + back-patch) would mean a second `set()`
+ * per node.
+ *
+ * `build_node(start, count, next_id)` constructs the record to add: it
+ * populates the inline array from `items[start..start+count]`, pads
+ * tail slots, and assembles any extra payload the table expects
+ * (including embedding `next_id` as the node's `next` field).
+ *
+ * Returns the head id (the last `add()`'s slot id), or `0xFFFFFFFF` if
+ * `items` is empty.
+ *
+ * @template T
+ * @template R
+ * @param {{ add: (record: R) => number }} table
+ * @param {T[]} items
+ * @param {number} items_per_chunk
+ * @param {(start: number, count: number, next_id: number) => R} build_node
+ * @returns {number}
+ */
+function add_linked_chain(table, items, items_per_chunk, build_node) {
+    const node_count = Math.ceil(items.length / items_per_chunk);
+    let next_id = 0xFFFFFFFF;
+
+    for (let n = node_count - 1; n >= 0; n--) {
+        const start = n * items_per_chunk;
+        const this_count = Math.min(items_per_chunk, items.length - start);
+        next_id = table.add(build_node(start, this_count, next_id));
+    }
+
+    return next_id;
+}
+
+/**
+ * Top-level coordinator for GPU-resident animation.
+ *
+ * Owns a single {@link GPUDatabase} keyed by {@link ANIMATION_DATABASE_SPEC}
+ * with five tables: `animation_curves`, `animation_keyframe_blocks`,
+ * `animation_tracks`, `animation_clips`, `animation_bound_track_groups`.
+ * Every record — including individual keyframes (inlined inside block
+ * nodes) and individual bindings (inlined inside group nodes) — lives in
+ * the database, so the dispatch shader needs only one storage binding.
+ *
+ * Animation *data* (curves, keyframes, tracks) is independent from
+ * *bound clips* (each carrying a `time` and a head pointer to its
+ * bound-track group chain). Bindings are no longer their own table:
+ * each chain node inlines up to {@link TRACKS_PER_GROUP_NODE} bindings
+ * and back-references its owning clip.
+ *
+ * Usage:
+ *  1. (Once at setup) Either low-level (`add_curve`, `add_track`,
+ *     `add_skin`, `add_clip`) or high-level (`register_skin`,
+ *     `register_clip` against the CPU data classes {@link Skin} /
+ *     {@link ShadeAnimationClip}).
+ *  2. (Once) {@link start} per clip to begin GPU-driven playback —
+ *     the {@link shader_animation_tick} pass advances `time` each
+ *     frame thereafter. CPU-driven prototypes can instead call
+ *     {@link set_time} per frame and skip the Playing flag.
+ *  3. (Per frame) {@link update} flushes pending writes for the
+ *     database. The scene context already does this on its own
+ *     update path.
+ */
+export class GPUAnimationManager {
+
+    /** @type {GPUDevice} */
+    #device;
+
+    /** @type {string} */
+    #label;
+
+    /** @type {GPUDatabase} */
+    #database;
+
+    /**
+     * Ping-pong pair of per-frame skinning-matrix buffers — one holds
+     * this frame's matrices (target of the prep dispatch, source for
+     * skinning's current-position write), the other last frame's
+     * (source for skinning's `position_prev` write that feeds the
+     * velocity post-pass).
+     *
+     * Ping-pong rather than a single buffer because the prev-frame
+     * matrices need to survive next frame's prep dispatch — and the
+     * cheapest way to preserve them is to write the new matrices into
+     * the OTHER buffer instead of overwriting the only one we have.
+     *
+     * {@link #skin_matrices_current_index} selects which entry of this
+     * array is "current" for the frame about to be dispatched;
+     * {@link dispatch_skin_matrix_prep} flips it before each frame's
+     * prep so the now-stale slot gets recycled.
+     *
+     * Lazily allocated on first {@link add_skin}; both grow together
+     * by doubling. After a grow both buffers are zero-initialised and
+     * {@link #first_frame_skin_matrices} is set so the next prep
+     * dispatch seeds the "previous" buffer with a copy of the freshly
+     * written "current" — without this, the first velocity readback
+     * after a grow would interpolate against zero matrices.
+     *
+     * @type {Array<GPUBuffer|null>}
+     */
+    #skin_matrices_buffers = [null, null];
+
+    /**
+     * Which entry of {@link #skin_matrices_buffers} is "current" for
+     * the next prep dispatch. Flipped at the start of every prep call.
+     * @type {number}
+     */
+    #skin_matrices_current_index = 0;
+
+    /**
+     * When true, the next prep dispatch will copy the freshly-written
+     * "current" buffer into the "previous" buffer at the end of the
+     * pass — used on first allocation and after every grow so the
+     * very first velocity computation has matching prev/current
+     * matrices (zero velocity).
+     * @type {boolean}
+     */
+    #first_frame_skin_matrices = true;
+
+    /**
+     * Capacity of each of {@link #skin_matrices_buffers} in matrices
+     * (not bytes). Both buffers always have the same capacity.
+     * @type {number}
+     */
+    #skin_matrices_capacity = 0;
+
+    /**
+     * High-water mark of the matrix range: the first index no skin has ever been given.
+     * A skin that cannot be served from {@link #free_skin_matrix_ranges} takes
+     * `joint_count` consecutive entries starting here, and this advances past them.
+     *
+     * Monotonic, but no longer the whole allocator — a range given back is reused before
+     * this advances again, so it tracks peak concurrent joints rather than total
+     * registrations.
+     *
+     * @type {number}
+     */
+    #next_skin_matrix_offset = 0;
+
+    /**
+     * CPU-side `skin_id → skin_matrix_offset` map. Each registered
+     * skin's base address in the shared `skin_matrices` scratch
+     * buffer; the per-block absolute offset (the prep shader's hot
+     * path) is derived as `base + chain_position *
+     * JOINTS_PER_SKIN_BLOCK` at registration. Storing the base on
+     * GPU would duplicate it — the block records already carry the
+     * per-block absolute address, and only the CPU (the skinning-
+     * binding upload path) needs the skin's base value.
+     *
+     * @type {Map<number, number>}
+     */
+    #skin_matrix_offsets = new Map();
+
+    /**
+     * Matrix ranges handed back by {@link unregister_skin}, bucketed by their length in
+     * matrices. Each bucket is a stack of base indices free to give out again.
+     *
+     * A range's base is baked into its skin's joint-block rows on the GPU, so a range can
+     * never be *moved* once handed out — which is what made compaction hard enough to skip,
+     * and left the offset a bump pointer with no way back. Reuse needs no movement: the hole
+     * a despawned character leaves is exactly the size of the next character wearing that
+     * rig, so matching a request to a hole of the same length hands the range straight back
+     * with nothing relocated and nothing to patch.
+     *
+     * Bucketed by length because the match has to be **exact**. The prep pass writes
+     * `base + joint` for `joint` in `[0, joint_count)`, so a skin placed in a shorter hole
+     * would write over whatever lives after it. Splitting a longer hole would fit, but every
+     * split leaves a fragment only an exactly-as-small skin can ever use; a game's rigs come
+     * in a handful of joint counts, so exact buckets stay few and nearly always hit.
+     *
+     * What this does not reclaim is bounded by the number of distinct joint counts ever
+     * registered rather than by the number of registrations: a rig retired for good leaves
+     * its ranges behind, a rig still in use passes the same ranges around forever.
+     *
+     * @type {Map<number, number[]>}
+     */
+    #free_skin_matrix_ranges = new Map();
+
+    /**
+     * Registered skins by id, kept for one reason: a clip registered *after* a skin has to be held
+     * against it, and a clip registered before one has to be held against the skin when it arrives.
+     * The frame a skinned mesh is deformed in is fixed once, at registration, and a clip that scales
+     * a joint is the one thing that can undo it afterwards — see {@link skin_clip_scale_conflicts}
+     * and `SKINNING_FRAME_PLAN.md` §4.
+     *
+     * @type {Map<number, Skin>}
+     */
+    #skins_by_id = new Map();
+
+    /**
+     * Registered clips that scale *something*, by id. Almost always empty — a character's clips
+     * rotate and translate — which is what keeps the pairwise check free in the ordinary case.
+     *
+     * @type {Map<number, ShadeAnimationClip>}
+     */
+    #scaling_clips = new Map();
+
+    /**
+     * Per-frame pose-accumulator scratch buffer. One slot per
+     * `transforms_table` row (slot size = `POSE_ACCUMULATOR_SLOT_BYTES`).
+     * The apply pass atomic-adds weighted TRS contributions into each
+     * dirty row; the resolve pass drains it into `transforms_table.local_*`
+     * and zeros the slot for next frame.
+     *
+     * Lazily allocated on first {@link ensure_pose_accumulator_capacity};
+     * grows by doubling. Grow destroys the old buffer — since resolve
+     * always leaves it zero, no copy is needed on grow.
+     *
+     * @type {GPUBuffer|null}
+     */
+    #pose_accumulator_buffer = null;
+
+    /**
+     * Capacity of {@link #pose_accumulator_buffer} in rows (slot
+     * indices), not bytes.
+     * @type {number}
+     */
+    #pose_accumulator_capacity = 0;
+
+    /**
+     * Back-reference to the owning scene context. Lets the high-level
+     * `register_*` methods resolve `Node3D.id` → transforms-table row
+     * via {@link GPUSceneContext#id_mapping} and bind skinning meshes
+     * via {@link GPUSceneContext#skinning}, without callers having to
+     * thread the context through every call.
+     *
+     * The manager doesn't touch this at construction (the scene
+     * context is itself only partially constructed when it builds the
+     * manager) — only inside `register_*` calls, which happen after
+     * scene.build has populated `id_mapping`.
+     *
+     * @type {GPUSceneContext}
+     */
+    #scene_context;
+
+    /**
+     * Identity-keyed cache of curve-id-on-GPU for every
+     * {@link AnimationCurve} that has been registered via
+     * {@link register_clip}. Lets multiple clips whose channels share
+     * the same curve instance (e.g. one base clip retargeted across
+     * many character instances) reuse the same GPU rows for the
+     * curve header + keyframe blocks rather than uploading
+     * duplicates. At grid-of-dancers scale duplication would balloon
+     * the keyframe-blocks table past its page-table limits.
+     *
+     * Low-level `add_curve` deliberately stays uncached — every call
+     * uploads — so existing callers that pre-build curves with
+     * distinct IDs (e.g. a pre-built track pool)
+     * keep their behavior.
+     *
+     * @type {WeakMap<AnimationCurve, number>}
+     */
+    #curve_id_cache = new WeakMap();
+
+    /**
+     * The curves uploaded so far, by what they are rather than which instance they were: the
+     * `hash()` of a curve's keys, to every uploaded curve with that hash and its GPU id.
+     *
+     * An instance cache alone shares nothing between two parses of one file, and a character
+     * instanced a few hundred times is a few hundred parses — each with its own instances of the
+     * same keys, filling the keyframe-block table with copies of one dance until its page limit
+     * refuses the next dancer. Curves are read-only once uploaded and nothing here releases them,
+     * so equal content can safely mean one upload.
+     *
+     * A hash bucket is a list because a hash is not an identity: a curve is only shared with one
+     * whose every key `equals` its own, tangents included.
+     *
+     * @type {Map<number, {curve: AnimationCurve, id: number}[]>}
+     */
+    #curve_id_by_content = new Map();
+
+    /**
+     * Cache of track-id-on-GPU keyed by `(curve_id_x, curve_id_y,
+     * curve_id_z, curve_id_w, mask)`. With curve dedup already
+     * sharing curve IDs across clips, two channels in different
+     * clips that bind to the same (target_property, curves) end up
+     * with identical track keys — and we can share the track row
+     * too. Each curve_id slot is `-1` when the corresponding channel
+     * is absent.
+     *
+     * Keys are joined into a string for Map lookup; the join cost is
+     * negligible compared to the GPU upload it avoids.
+     *
+     * @type {Map<string, number>}
+     */
+    #track_id_cache = new Map();
+
+    /**
+     * Skins registered via {@link register_skin} whose joint-block
+     * chain hasn't been built yet because one or more joint Node3Ds
+     * lacks an `id_mapping` row. The skin's GPU table row exists
+     * (placeholder `joint_block_head = NULL`, no joints driving the
+     * prep pass yet), and state mutators / unregister already work
+     * — but the deformation only kicks in once {@link update}
+     * successfully drains the entry.
+     *
+     * Each entry: `skin_id`, the CPU {@link Skin} (whose `joints`
+     * array drives the chain build), the `skin_matrix_offset`
+     * reserved at register time, and the `inverse_bind_matrices`
+     * typed array.
+     *
+     * @type {Array<{
+     *     skin_id: number,
+     *     skin: Skin,
+     *     skin_matrix_offset: number,
+     *     inverse_bind_matrices: Float32Array,
+     * }>}
+     */
+    #pending_skins = [];
+
+    /**
+     * Clips registered via {@link register_clip} whose bindings
+     * chain hasn't been built yet because one or more channel
+     * targets lacks an `id_mapping` row. The clip's GPU table row
+     * exists (placeholder `bound_track_group_head = NULL`, no
+     * tracks driving the apply pass yet); time/state mutators and
+     * unregister already work.
+     *
+     * Each entry: `clip_id` plus the per-channel `(track_id,
+     * target, property)` triples — the curves and tracks were
+     * interned at register time so only the (target → instance row)
+     * resolution is deferred.
+     *
+     * @type {Array<{
+     *     clip_id: number,
+     *     channels: Array<{ track: number, target: Node3D, property: number }>,
+     * }>}
+     */
+    #pending_clips = [];
+
+    /**
+     * @param {GPUDevice} device
+     * @param {string} label
+     * @param {GPUSceneContext} scene_context
+     */
+    constructor(device, label, scene_context) {
+        assert.defined(device, 'device');
+        assert.defined(scene_context, 'scene_context');
+
+        this.#device = device;
+        this.#label = label;
+        this.#scene_context = scene_context;
+
+        this.#database = new GPUDatabase({
+            device,
+            definition: ANIMATION_DATABASE_SPEC,
+            label: `${label}/Database`,
+        });
+    }
+
+    /**
+     * @returns {GPUDatabase}
+     */
+    get database() {
+        return this.#database;
+    }
+
+    /**
+     * Per-frame skinning-matrix scratch buffer for the *current*
+     * frame. `null` until the first skin is registered. The
+     * skin-matrix-prep pass writes to it; the skinning compute pass
+     * reads from it to deform current-frame positions. Address `j`
+     * of skin `s` is at matrix index `s.skin_matrix_offset + j`.
+     *
+     * The buffer reference is invalidated on grow AND flips role
+     * every frame as part of the ping-pong with
+     * {@link prev_skin_matrices_buffer} — re-fetch each frame.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get skin_matrices_buffer() {
+        return this.#skin_matrices_buffers[this.#skin_matrices_current_index];
+    }
+
+    /**
+     * Previous-frame counterpart of {@link skin_matrices_buffer} —
+     * holds the matrices the previous frame's prep dispatch wrote.
+     * Read by the skinning compute pass to produce per-vertex
+     * `position_prev` data for the velocity post-pass.
+     *
+     * `null` until the first skin is registered. Flips role with
+     * {@link skin_matrices_buffer} every frame.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get prev_skin_matrices_buffer() {
+        return this.#skin_matrices_buffers[1 - this.#skin_matrices_current_index];
+    }
+
+    /**
+     * Matrices the buffer has to address: the high-water mark, which covers every registered
+     * skin plus any range sitting on the free list between the ones still in use. Independent
+     * of buffer capacity, which is at least this big.
+     *
+     * Not a count of live joints — a skin that unregisters leaves its range addressable for
+     * the next skin of its size, so this falls only when nothing has been registered yet.
+     *
+     * @returns {number}
+     */
+    get skin_matrix_count() {
+        return this.#next_skin_matrix_offset;
+    }
+
+    /**
+     * Pose-accumulator scratch buffer (per-Node3D-row weighted
+     * contribution slots). `null` until {@link ensure_pose_accumulator_capacity}
+     * is called for the first time.
+     *
+     * The buffer reference is invalidated on grow — re-fetch each
+     * frame after {@link ensure_pose_accumulator_capacity} rather
+     * than caching across frames.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get pose_accumulator_buffer() {
+        return this.#pose_accumulator_buffer;
+    }
+
+    /**
+     * Ensure the pose-accumulator scratch buffer can address at least
+     * `row_count` `transforms_table` rows. Grows by doubling from the
+     * initial capacity; idempotent when already big enough. Called
+     * by the per-frame dispatch driver after `scene.build` has
+     * stabilised the transforms-table size for the frame.
+     *
+     * Grow destroys the previous GPU buffer; resolve always leaves the
+     * accumulator zeroed at the end of each frame, so there's nothing
+     * to copy across the realloc.
+     *
+     * @param {number} row_count
+     */
+    ensure_pose_accumulator_capacity(row_count) {
+        assert.isNonNegativeInteger(row_count, 'row_count');
+
+        // Existing buffer fits the request → nothing to do. The null
+        // check guarantees the very first call always allocates,
+        // even when `row_count == 0` (e.g. before any scene content
+        // has been built): downstream binding paths assume the
+        // buffer reference is non-null whenever the apply pass runs.
+        if (this.#pose_accumulator_buffer !== null && row_count <= this.#pose_accumulator_capacity) {
+            return;
+        }
+
+        let new_capacity = Math.max(this.#pose_accumulator_capacity, POSE_ACCUMULATOR_INITIAL_CAPACITY);
+        while (new_capacity < row_count) {
+            new_capacity *= 2;
+        }
+
+        if (this.#pose_accumulator_buffer !== null) {
+            this.#pose_accumulator_buffer.destroy();
+        }
+
+        this.#pose_accumulator_buffer = this.#device.createBuffer({
+            label: `${this.#label}/PoseAccumulator`,
+            size: new_capacity * POSE_ACCUMULATOR_SLOT_BYTES,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        });
+        this.#pose_accumulator_capacity = new_capacity;
+    }
+
+    /**
+     * Read back a skin's record from the database's CPU shadow.
+     *
+     * @param {number} skin_id
+     * @returns {{joint_block_head: number, joint_count: number}}
+     */
+    get_skin(skin_id) {
+        assert.isNonNegativeInteger(skin_id, 'skin_id');
+        return this.#database.get('animation_skins').get(skin_id);
+    }
+
+    /**
+     * Base address of the skin's matrix range in the shared
+     * `skin_matrices` scratch buffer — matrix `j` of the skin lives
+     * at `skin_matrices[get_skin_matrix_offset(skin_id) + j]`.
+     *
+     * Tracked CPU-side rather than on the skin record because the
+     * value is only ever consumed by the skinning-binding upload
+     * path; the prep shader uses the per-block absolute offset
+     * (cheaper than a per-thread skin lookup for that hot path).
+     *
+     * @param {number} skin_id
+     * @returns {number}
+     */
+    get_skin_matrix_offset(skin_id) {
+        assert.isNonNegativeInteger(skin_id, 'skin_id');
+        const offset = this.#skin_matrix_offsets.get(skin_id);
+        assert.defined(offset, `unknown skin_id ${skin_id}`);
+        return offset;
+    }
+
+    /**
+     * Add an animation curve. Keyframes are split into linked-list blocks
+     * of up to {@link KEYFRAMES_PER_BLOCK} entries each; the curve header
+     * points at the head block, and each block's `next` field chains
+     * forward.
+     *
+     * The curve is a cubic Hermite spline — step, linear, and arbitrary
+     * cubic shapes are all expressible by choosing tangents on each keyframe.
+     *
+     * @param {AnimationCurve} curve
+     * @returns {number} curve id (index into the `animation_curves` table)
+     */
+    add_curve(curve) {
+        assert.defined(curve, 'curve');
+        assert.equal(curve.isAnimationCurve, true, 'curve.isAnimationCurve !== true');
+        assert.greaterThanOrEqual(curve.length, 1, 'curve must have at least one keyframe');
+
+        const keys = curve.keys;
+        const blocks_table = this.#database.get('animation_keyframe_blocks');
+
+        const head_block_id = add_linked_chain(
+            blocks_table,
+            keys,
+            KEYFRAMES_PER_BLOCK,
+            (start, count, next) => {
+                const keyframes = new Array(KEYFRAMES_PER_BLOCK);
+                for (let j = 0; j < KEYFRAMES_PER_BLOCK; j++) {
+                    keyframes[j] = j < count ? keys[start + j] : ZERO_KEYFRAME;
+                }
+                return { keyframes, count, next };
+            }
+        );
+
+        const curves_table = this.#database.get('animation_curves');
+        return curves_table.add({
+            kind: 0,
+            keyframe_block_head: head_block_id,
+            keyframe_count: keys.length,
+            time_min: curve.start_time,
+            time_max: curve.end_time,
+        });
+    }
+
+    /**
+     * Add a track. Channels are addressed by name (`x`, `y`, `z`, `w`) — the
+     * provided curves go into the matching slots of the track's `vec4f`
+     * output. Omitted channels are masked off and read as 0.
+     *
+     * The slot meaning is property-specific: for `MeshTranslation`, x/y/z
+     * are the translation components; for `MeshRotation` they're the
+     * quaternion's x/y/z/w. The track's mask travels with the evaluated
+     * value to the apply step, which uses it to decide which destinations
+     * to overwrite.
+     *
+     * @param {{ x?: number, y?: number, z?: number, w?: number }} channels
+     *     curve ids per channel; pass at least one
+     * @returns {number} track id (index into the `animation_tracks` table)
+     */
+    add_track(channels) {
+        assert.defined(channels, 'channels');
+
+        const cx = channels.x;
+        const cy = channels.y;
+        const cz = channels.z;
+        const cw = channels.w;
+
+        let mask = 0;
+        if (cx !== undefined) mask |= 0x1;
+        if (cy !== undefined) mask |= 0x2;
+        if (cz !== undefined) mask |= 0x4;
+        if (cw !== undefined) mask |= 0x8;
+
+        assert.notEqual(mask, 0, 'track must have at least one channel');
+
+        const curves = [
+            cx ?? 0,
+            cy ?? 0,
+            cz ?? 0,
+            cw ?? 0,
+        ];
+
+        const table = this.#database.get('animation_tracks');
+        return table.add({ mask, curves });
+    }
+
+    /**
+     * Create a bound clip — a group of bound tracks that share a single
+     * `time`. Bindings are split into linked-list group nodes of up to
+     * {@link TRACKS_PER_GROUP_NODE} each; the clip points at the head
+     * node and each node back-references the clip so the apply shader
+     * (one thread per group node) can fetch the clip without walking the
+     * chain from the clip end.
+     *
+     * Tracks may be authored on a clock that doesn't align with
+     * `[time_start, time_end]` — their curves are clamped to their own
+     * `[time_min, time_max]` during evaluation.
+     *
+     * Defaults: `time = 0`, `time_start = 0`, `time_end = 0`,
+     * `playback_rate = 1`, `playback_weight = 1`, `flags = 0` (not
+     * playing, not looping). The clip is inert at creation — call
+     * {@link start} to begin GPU-side time advancement.
+     *
+     * @param {{
+     *     time?: number,
+     *     time_start?: number,
+     *     time_end?: number,
+     *     bindings: Array<{ track: number, instance: number, property: number }>,
+     * }} clip
+     * @returns {number} clip id (index into the `animation_clips` table)
+     */
+    add_clip(clip) {
+        assert.defined(clip, 'clip');
+        assert.isArray(clip.bindings, 'clip.bindings');
+        assert.greaterThanOrEqual(clip.bindings.length, 1, 'clip must have at least one binding');
+
+        const time = clip.time ?? 0;
+        const time_start = clip.time_start ?? 0;
+        const time_end = clip.time_end ?? 0;
+        const bindings = clip.bindings;
+
+        const clips_table = this.#database.get('animation_clips');
+        const groups_table = this.#database.get('animation_bound_track_groups');
+
+        // Reserve the clip slot up front so group nodes can back-reference
+        // it via `clip`. The head pointer is patched in once the chain is
+        // built (we don't know its first id until we've allocated every
+        // group node).
+        const clip_id = clips_table.add({
+            time,
+            time_start,
+            time_end,
+            bound_track_group_head: ANIMATION_BOUND_TRACK_GROUP_NULL,
+            playback_rate: 1,
+            flags: 0,
+            playback_weight: 1,
+        });
+
+        const head_group_id = add_linked_chain(
+            groups_table,
+            bindings,
+            TRACKS_PER_GROUP_NODE,
+            (start, count, next) => {
+                const inline_bindings = new Array(TRACKS_PER_GROUP_NODE);
+                for (let j = 0; j < TRACKS_PER_GROUP_NODE; j++) {
+                    if (j < count) {
+                        const b = bindings[start + j];
+
+                        assert.isNonNegativeInteger(b.track, `clip.bindings[${start + j}].track`);
+                        assert.isNonNegativeInteger(b.instance, `clip.bindings[${start + j}].instance`);
+                        assert.isNonNegativeInteger(b.property, `clip.bindings[${start + j}].property`);
+
+                        inline_bindings[j] = b;
+                    } else {
+                        inline_bindings[j] = ZERO_BINDING;
+                    }
+                }
+                return { bindings: inline_bindings, count, next, clip: clip_id };
+            }
+        );
+
+        // Patch the head pointer now that the chain exists. Re-`set` the
+        // whole record because the table API doesn't expose per-field
+        // updates.
+        clips_table.set(clip_id, {
+            time,
+            time_start,
+            time_end,
+            bound_track_group_head: head_group_id,
+            playback_rate: 1,
+            flags: 0,
+            playback_weight: 1,
+        });
+
+        return clip_id;
+    }
+
+    /**
+     * Overwrite a single field of a clip's record by reading the current
+     * record back from the CPU shadow and re-`set`ting with one field
+     * changed. The table API doesn't expose per-field updates, so we
+     * round-trip through a full record; the upload-buffer dedupe
+     * collapses the resulting per-frame write into a single GPU touch
+     * when nothing else changed.
+     *
+     * @param {number} clip_id
+     * @param {string} field
+     * @param {number} value
+     */
+    #patch_clip_field(clip_id, field, value) {
+        assert.isNonNegativeInteger(clip_id, 'clip_id');
+
+        const clips_table = this.#database.get('animation_clips');
+        const current = clips_table.get(clip_id);
+
+        clips_table.set(clip_id, {
+            time: current.time,
+            time_start: current.time_start,
+            time_end: current.time_end,
+            bound_track_group_head: current.bound_track_group_head,
+            playback_rate: current.playback_rate,
+            flags: current.flags,
+            playback_weight: current.playback_weight,
+            [field]: value,
+        });
+    }
+
+    /**
+     * Direct override of a clip's `time`. Bypasses {@link start} /
+     * {@link stop} — `time` is written even if the clip is paused, and
+     * the {@link AnimationClipFlags.Playing} bit is left untouched.
+     * The host typically uses this to scrub or rewind; GPU-driven
+     * playback advances time on its own via the tick shader.
+     *
+     * TODO: race between `start()` and `set_time()` is non-atomic — if
+     * a caller does `start(id); set_time(id, phase)` and the next GPU
+     * tick fires before the page upload from `set_time` lands, the
+     * tick advances from the old `time` for one frame. RIS would be
+     * an atomic `start_at(id, time, ...)` that fuses both field
+     * writes into one record set. For phase offsets the one-frame
+     * skew is invisible; for scrub-and-resume UIs it can show.
+     *
+     * @param {number} clip_id
+     * @param {number} time
+     */
+    set_time(clip_id, time) {
+        assert.isNumber(time, 'time');
+        this.#patch_clip_field(clip_id, 'time', time);
+    }
+
+    /**
+     * Direct override of a clip's per-frame advance scalar. `1.0` =
+     * realtime; `0.0` effectively pauses (independent of the
+     * {@link AnimationClipFlags.Playing} bit); negative values play
+     * in reverse.
+     *
+     * @param {number} clip_id
+     * @param {number} rate
+     */
+    set_playback_rate(clip_id, rate) {
+        assert.isNumber(rate, 'rate');
+        this.#patch_clip_field(clip_id, 'playback_rate', rate);
+    }
+
+    /**
+     * Override a clip's contribution weight into the pose accumulator.
+     * `1.0` is full strength; `0.0` silences the clip without removing
+     * its bindings; values in between blend it against other clips
+     * targeting the same nodes. The apply shader pre-multiplies every
+     * curve-evaluated value by this scalar before atomic-adding into
+     * the accumulator.
+     *
+     * Normalized blends expect weights across all clips driving a
+     * node to sum to `1`; additive layers use weights that don't sum
+     * to `1`. The system doesn't enforce either — host's call.
+     *
+     * @param {number} clip_id
+     * @param {number} weight
+     */
+    set_playback_weight(clip_id, weight) {
+        assert.isNumber(weight, 'weight');
+        this.#patch_clip_field(clip_id, 'playback_weight', weight);
+    }
+
+    /**
+     * Add (OR) one or more flag bits onto a clip's bitfield. Bits
+     * already set stay set; other bits are untouched. Values come
+     * from {@link AnimationClipFlags} and can be combined with `|`:
+     * `set_flags(id, AnimationClipFlags.Loop | AnimationClipFlags.Playing)`.
+     *
+     * Counterpart {@link clear_flags} ANDs the bits out. Together
+     * they cover the common cases without the overwrite footgun
+     * the original version had (where setting Loop would silently
+     * clear Playing).
+     *
+     * For toggling just the playing bit, {@link start} / {@link stop}
+     * are equivalent shortcuts.
+     *
+     * @param {number} clip_id
+     * @param {number} flags bits to set
+     */
+    set_flags(clip_id, flags) {
+        assert.isNonNegativeInteger(flags, 'flags');
+
+        const clips_table = this.#database.get('animation_clips');
+        const current = clips_table.get(clip_id);
+
+        this.#patch_clip_field(clip_id, 'flags', current.flags | flags);
+    }
+
+    /**
+     * Clear (AND-NOT) one or more flag bits from a clip's bitfield.
+     * Bits not present in `flags` are left untouched. Symmetric
+     * with {@link set_flags}.
+     *
+     * @param {number} clip_id
+     * @param {number} flags bits to clear
+     */
+    clear_flags(clip_id, flags) {
+        assert.isNonNegativeInteger(flags, 'flags');
+
+        const clips_table = this.#database.get('animation_clips');
+        const current = clips_table.get(clip_id);
+
+        this.#patch_clip_field(clip_id, 'flags', current.flags & ~flags);
+    }
+
+    /**
+     * Begin GPU-side playback. Sets the {@link AnimationClipFlags.Playing}
+     * bit; preserves every other flag bit, the current `time`, the
+     * `playback_rate`, and so on. Calling {@link stop} and then `start`
+     * back-to-back should feel like a no-op modulo at most one tick's
+     * worth of advance.
+     *
+     * Idempotent: starting an already-playing clip is a no-op (the
+     * upload-buffer dedupe collapses the write).
+     *
+     * @param {number} clip_id
+     */
+    start(clip_id) {
+        assert.isNonNegativeInteger(clip_id, 'clip_id');
+
+        const clips_table = this.#database.get('animation_clips');
+        const current = clips_table.get(clip_id);
+
+        this.#patch_clip_field(clip_id, 'flags', current.flags | AnimationClipFlags.Playing);
+    }
+
+    /**
+     * Pause GPU-side playback. Clears the {@link AnimationClipFlags.Playing}
+     * bit; preserves every other flag bit and the current `time`.
+     * Symmetric with {@link start} — a stop/start pair leaves the clip
+     * where it was (give or take one tick of GPU time loss).
+     *
+     * Idempotent: stopping an already-stopped clip is a no-op.
+     *
+     * @param {number} clip_id
+     */
+    stop(clip_id) {
+        assert.isNonNegativeInteger(clip_id, 'clip_id');
+
+        const clips_table = this.#database.get('animation_clips');
+        const current = clips_table.get(clip_id);
+
+        this.#patch_clip_field(clip_id, 'flags', current.flags & ~AnimationClipFlags.Playing);
+    }
+
+    /**
+     * Register a skin: an ordered list of joints, each pinning a
+     * Node3D row that drives the joint plus the inverse-bind matrix
+     * that takes vertex positions from mesh space into the joint's
+     * bind-pose local space. The skin reserves a contiguous range of
+     * `joints.length` matrices in the {@link #skin_matrices_buffer}
+     * scratch buffer; the prep pass populates that range each frame
+     * with `node.global × inverse_bind` for every joint.
+     *
+     * The skin record carries no mesh-world factor. The rasterizer
+     * applies `mesh.transform_global` to the skinned clone vertex
+     * via the standard mesh transform path
+     * ({@link chunk_mesh_resolve_vertex_position_world}), so adding
+     * an `inverse(mesh.global)` factor in the skin matrix would
+     * double-cancel against that re-application and shrink the rig
+     * back to mesh-local coordinates rendered as world.
+     *
+     * Joints are split into linked-list blocks of up to
+     * {@link JOINTS_PER_SKIN_BLOCK} each — same chain pattern used for
+     * bound-track groups and keyframe blocks. Each block records the
+     * absolute write offset for its slots, so the prep shader's
+     * per-thread work is one block load + a bounded inner loop with no
+     * indirection back through the skin record.
+     *
+     * @param {{
+     *     joints: Array<{ node: number, inverse_bind: Float32Array | number[] }>,
+     * }} skin
+     * @returns {number} skin id (index into the `animation_skins` table)
+     */
+    add_skin(skin) {
+        assert.defined(skin, 'skin');
+        assert.isArray(skin.joints, 'skin.joints');
+        assert.greaterThanOrEqual(skin.joints.length, 1, 'skin must have at least one joint');
+
+        const joints = skin.joints;
+        const joint_count = joints.length;
+
+        // Reserve the matrix range. Each block bakes in its absolute
+        // slot offset (skin_base + chain_position * JOINTS_PER_SKIN_BLOCK)
+        // so the prep shader writes directly without dereferencing
+        // the skin row for the offset; the base is also stashed on
+        // the CPU map so the skinning-binding upload can look it up
+        // without reading the GPU back.
+        const skin_matrix_offset = this.#allocate_skin_matrix_range(joint_count);
+
+        const skins_table = this.#database.get('animation_skins');
+        const blocks_table = this.#database.get('animation_skin_joint_blocks');
+
+        // Reserve the skin row up front. The head pointer is patched
+        // in once the chain exists. NULL placeholder — 0 is a valid
+        // block row id (the first allocation in an empty table).
+        const skin_id = skins_table.add({
+            joint_block_head: ANIMATION_SKIN_JOINT_BLOCK_NULL,
+            joint_count,
+        });
+        this.#skin_matrix_offsets.set(skin_id, skin_matrix_offset);
+
+        const head_block_id = add_linked_chain(
+            blocks_table,
+            joints,
+            JOINTS_PER_SKIN_BLOCK,
+            (start, count, next) => {
+                const inline_joints = new Array(JOINTS_PER_SKIN_BLOCK);
+                for (let j = 0; j < JOINTS_PER_SKIN_BLOCK; j++) {
+                    if (j < count) {
+                        const joint = joints[start + j];
+
+                        assert.isNonNegativeInteger(joint.node, `skin.joints[${start + j}].node`);
+                        assert.defined(joint.inverse_bind, `skin.joints[${start + j}].inverse_bind`);
+
+                        inline_joints[j] = joint;
+                    } else {
+                        inline_joints[j] = ZERO_SKIN_JOINT;
+                    }
+                }
+                return {
+                    joints: inline_joints,
+                    count,
+                    next,
+                    skin_matrix_offset: skin_matrix_offset + start,
+                };
+            }
+        );
+
+        // Patch the head pointer now that the chain exists. Re-`set`
+        // the whole record because the table API doesn't expose
+        // per-field updates.
+        skins_table.set(skin_id, {
+            joint_block_head: head_block_id,
+            joint_count,
+        });
+
+        return skin_id;
+    }
+
+    /**
+     * High-level skin registration: consumes a {@link Skin} (CPU data
+     * with Node3D joint references and a flat inverse-bind matrix
+     * array), allocates a GPU skin record, and binds every entry in
+     * `skin.meshes` through the skinning context.
+     *
+     * **Eventual consistency.** The `skin_id` is allocated and
+     * returned synchronously — callers can immediately pass it to
+     * state mutators or {@link unregister_skin}. If any joint's
+     * Node3D hasn't been added to a scene yet (no `id_mapping` row),
+     * the joint-block chain that drives the deformation is queued
+     * and built on the next {@link update} that sees all joints
+     * resolved. The skin's table row uses a placeholder
+     * `joint_block_head` until then — observationally indistinguishable
+     * from "skin with no joints driving it" (no deformation runs).
+     *
+     * Mesh→skin bindings register immediately via
+     * {@link GPUMeshSkinningContext#bind}; the skinning context
+     * already tolerates pre-scene-build registration. Each mesh also
+     * gets its {@link SkinnedMesh#skin} reference and a fresh set of
+     * bounds off it, synchronously — that part does not wait for
+     * `id_mapping`, because it reads the joints' `transform_global`
+     * rather than any GPU row.
+     *
+     * @param {Skin} skin
+     * @returns {number} skin id (index into the `animation_skins` table)
+     */
+    register_skin(skin) {
+        assert.defined(skin, 'skin');
+        assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+        assert.greaterThanOrEqual(skin.meshes.length, 1, 'skin.meshes must contain at least one mesh');
+
+        const joint_count = skin.joints.length;
+        const inverse_bind_matrices = skin.inverse_bind_matrices;
+
+        // Reserve the matrix range up front — block records carry
+        // their absolute slot offset, so the prep shader writes
+        // directly. The base also lands on #skin_matrix_offsets so
+        // skinning-binding upload can look it up.
+        const skin_matrix_offset = this.#allocate_skin_matrix_range(joint_count);
+
+        // Reserve the skin row immediately with a placeholder head
+        // pointer. State mutators and the public id are usable from
+        // this point on; the joint chain gets patched in once
+        // id_mapping has every joint (possibly synchronously below,
+        // possibly deferred via the pending queue).
+        const skins_table = this.#database.get('animation_skins');
+        const skin_id = skins_table.add({
+            // NULL placeholder — 0 is a valid block row id
+            joint_block_head: ANIMATION_SKIN_JOINT_BLOCK_NULL,
+            joint_count,
+        });
+        this.#skin_matrix_offsets.set(skin_id, skin_matrix_offset);
+
+        // Bind every mesh into the skinning context. Idempotent and
+        // pre-build tolerant — the binding upload defers until
+        // id_mapping is ready.
+        //
+        // Each mesh also takes a reference to the CPU-side skin and
+        // re-derives its bounds off it. From here on the skin's
+        // formula is what places the mesh's vertices, and `Mesh`'s
+        // composition — rest-pose geometry under `transform_global` —
+        // is the wrong one, because the skinning pass cancels that
+        // transform back out (see {@link SkinnedMesh#updateBoundsBasic}).
+        // Nothing else would notice: bounds are refreshed by
+        // `updateMatrices`, and a character does not move again just
+        // because it finished loading.
+        // Before any of that: put the meshes into the frame this skin actually deforms in. The
+        // skinning pass writes each clone's vertices in `inverse(mesh.global)` space, so
+        // `mesh.global` is that frame — and glTF says a skinned mesh's node transform is ignored,
+        // which makes the frame the engine's to choose rather than the exporter's to get right.
+        // Ahead of the bind loop because it moves the mesh, and the bounds published below have to
+        // be the ones that survive. See `SKINNING_FRAME_PLAN.md`.
+        this.#normalize_skin_frame(skin);
+
+        this.#skins_by_id.set(skin_id, skin);
+
+        for (const clip of this.#scaling_clips.values()) {
+            this.#report_scale_conflicts(skin, clip);
+        }
+
+        const skinning = this.#scene_context.skinning;
+        const meshes = skin.meshes;
+        for (let i = 0; i < meshes.length; i++) {
+            const mesh = meshes[i];
+
+            skinning.bind(mesh, skin_id);
+
+            mesh.skin = skin;
+            mesh.updateBoundsBasic();
+
+            // The row the scene context published for this mesh holds the pre-skin bounds, and
+            // nothing about binding a skin looks like movement — `updateBoundsBasic` is not
+            // `updateMatrices` and does not touch the version the sync compares against. Without
+            // this the corrected box sits on the CPU object and never reaches the table.
+            mesh.needsUpdate = true;
+        }
+
+        // Try to complete now. If id_mapping is ready for every
+        // joint, the chain gets built and patched in. Otherwise the
+        // skin lands on #pending_skins and the next update() drain
+        // retries.
+        const pending = {
+            skin_id,
+            skin,
+            skin_matrix_offset,
+            inverse_bind_matrices,
+        };
+        if (!this.#try_complete_skin(pending)) {
+            this.#pending_skins.push(pending);
+        }
+
+        return skin_id;
+    }
+
+    /**
+     * Put a skin's meshes into the frame it deforms in, and say so when they cannot be.
+     *
+     * The correction itself is {@link skin_normalize_mesh_frame}, which is where the argument lives.
+     * This is the reporting: an asset that renders wrong should say which asset and by how much, on
+     * the frame it is registered, rather than reaching a person as a screenshot of soup.
+     *
+     * @param {Skin} skin
+     */
+    #normalize_skin_frame(skin) {
+        const report = skin_normalize_mesh_frame(skin);
+
+        // a glTF skin's `name` is optional and often absent; the mesh it deforms is what a person
+        // would recognise, and is what the asset's own hierarchy calls it
+        const label = skin.name !== '' ? skin.name : (skin.meshes[0]?.name ?? '<unnamed>');
+
+        if (report.unwalked.length > 0) {
+            console.error(
+                `skin '${label}': ${report.unwalked.length} of its nodes have never been walked — `
+                + `'${report.unwalked[0].name}' among them — so their world transforms are the `
+                + `identity by default rather than by derivation. Call updateMatrices on the scene `
+                + `before registering. Nothing was moved; the deformation will be wrong.`
+            );
+
+            return;
+        }
+
+        if (report.frame_defect > 0.001) {
+            console.error(
+                `skin '${label}': no frame can deform it — `
+                + `inverse(frame) × joint.global × inverse_bind is ${report.frame_defect.toFixed(4)} `
+                + `away from rigid at its own bind pose, and a dual quaternion carries a rotation and `
+                + `a translation and nothing else. The rest pose has a non-uniform scale or a shear `
+                + `in it. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §4.`
+            );
+
+            return;
+        }
+
+        if (report.residual > 0.001) {
+            console.error(
+                `skin '${label}': its mesh frame did not land — ${report.residual.toFixed(6)} `
+                + `left over. A correction carrying shear does not survive a Transform64's TRS `
+                + `components. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §3.`
+            );
+
+            return;
+        }
+
+        for (const mesh of report.obstructed) {
+            console.warn(
+                `skin '${label}': mesh node '${mesh.name}' carries the skin's frame now, and its `
+                + `${mesh.children.length} child node(s) inherit it. Sockets belong on bones.`
+            );
+        }
+
+        if (report.corrected > 0) {
+            // verbose rather than a warning: this is a legal asset shape, and a crowd of them would
+            // otherwise be a crowd of log lines
+            console.debug(
+                `skin '${label}': ${report.corrected} mesh frame(s) moved onto the skin's bind `
+                + `transform, absorbing ${report.absorbed.toFixed(4)} of non-rigidity the skinning `
+                + `pass could not have carried.`
+            );
+        }
+    }
+
+    /**
+     * Say so when a clip scales a skin's joints out from under the frame it is deformed in.
+     *
+     * The frame {@link skin_normalize_mesh_frame} chooses is fixed at registration, and it is sound
+     * because the joints and the mesh share their scaling ancestors. A scale that reaches only some
+     * of them breaks that every frame it plays, on the GPU, where nothing can see it —
+     * {@link skin_clip_scale_conflicts} is that question asked off the clip's own curves instead.
+     *
+     * Nothing is refused: the clip is legal animation and the skin is a legal skin, and it is their
+     * combination the skinning pass cannot carry. Refusing either would be picking one to blame.
+     *
+     * @param {Skin} skin
+     * @param {ShadeAnimationClip} clip
+     */
+    #report_scale_conflicts(skin, clip) {
+        const conflicts = skin_clip_scale_conflicts(skin, clip);
+
+        if (conflicts.length === 0) {
+            return;
+        }
+
+        const skin_label = skin.name !== '' ? skin.name : (skin.meshes[0]?.name ?? '<unnamed>');
+
+        const nodes = conflicts.map(conflict => conflict.node.name || '<unnamed>').join(', ');
+
+        const uniform = conflicts.every(conflict => conflict.uniform);
+
+        console.error(
+            `clip '${clip.name}' scales ${conflicts.length} node(s) of skin '${skin_label}' — `
+            + `${nodes} — which reach its joints but not its mesh, so the scale enters the joint `
+            + `matrices and not the frame they are folded against. A dual quaternion cannot carry `
+            + `it and no choice of frame fixes it: the deformation will be wrong while this clip `
+            + `plays. `
+            + (uniform
+                ? `The scale is uniform, which SKINNING_FRAME_PLAN.md §4 has a design for.`
+                : `The scale is non-uniform, which no dual quaternion holds — §4's linear-blend `
+                + `path or an import-time refusal.`)
+        );
+    }
+
+    /**
+     * Attempt to build the joint-block chain for a pending skin and
+     * patch its head pointer onto the skin row. Returns `true` when
+     * every joint Node3D has resolved to a transforms-table row
+     * (and the chain was built); `false` when at least one joint is
+     * still missing.
+     *
+     * @param {{
+     *     skin_id: number,
+     *     skin: Skin,
+     *     skin_matrix_offset: number,
+     *     inverse_bind_matrices: Float32Array,
+     * }} pending
+     * @returns {boolean}
+     */
+    #try_complete_skin(pending) {
+        const id_mapping = this.#scene_context.id_mapping;
+        const joint_nodes = pending.skin.joints;
+        const joint_count = joint_nodes.length;
+        const inverse_bind_matrices = pending.inverse_bind_matrices;
+        const skin_matrix_offset = pending.skin_matrix_offset;
+        const skin_id = pending.skin_id;
+
+        // All-or-nothing: a single missing row leaves the chain
+        // unbuilt — partial chains aren't valid (the prep shader
+        // walks every block).
+        const joints = new Array(joint_count);
+        for (let i = 0; i < joint_count; i++) {
+            const node = joint_nodes[i];
+            const row = id_mapping.get(node.id);
+            if (row === undefined) return false;
+
+            joints[i] = {
+                node: row,
+                // Per-joint slice of the flat matrix array. The
+                // marshaller copies these bytes into the skin-joint
+                // block record; sub-array views are fine — they
+                // share the underlying buffer but write_struct_value
+                // reads by length, not by offset.
+                inverse_bind: inverse_bind_matrices.subarray(i * 16, (i + 1) * 16),
+            };
+        }
+
+        const blocks_table = this.#database.get('animation_skin_joint_blocks');
+        const head_block_id = add_linked_chain(
+            blocks_table,
+            joints,
+            JOINTS_PER_SKIN_BLOCK,
+            (start, count, next) => {
+                const inline_joints = new Array(JOINTS_PER_SKIN_BLOCK);
+                for (let j = 0; j < JOINTS_PER_SKIN_BLOCK; j++) {
+                    inline_joints[j] = j < count ? joints[start + j] : ZERO_SKIN_JOINT;
+                }
+                return {
+                    joints: inline_joints,
+                    count,
+                    next,
+                    skin_matrix_offset: skin_matrix_offset + start,
+                };
+            }
+        );
+
+        // Patch the head pointer onto the already-allocated skin
+        // row. Read-modify-write so any other fields the user might
+        // have changed via mutators (none today, but future-proof)
+        // are preserved.
+        const skins_table = this.#database.get('animation_skins');
+        const current = skins_table.get(skin_id);
+        skins_table.set(skin_id, {
+            joint_block_head: head_block_id,
+            joint_count: current.joint_count,
+        });
+
+        return true;
+    }
+
+    /**
+     * High-level clip registration: consumes a {@link ShadeAnimationClip}
+     * (CPU data with Node3D targets and per-component curves), uploads
+     * curves and tracks, and creates the GPU clip record.
+     *
+     * **Eventual consistency.** The `clip_id` is allocated and
+     * returned synchronously — callers can immediately call
+     * {@link start} / {@link stop} / {@link set_time} /
+     * {@link set_playback_rate} / {@link set_flags} / {@link clear_flags}
+     * / {@link set_playback_weight} / {@link unregister_clip}. If
+     * any channel target's Node3D hasn't been added to a scene yet
+     * (no `id_mapping` row), the bindings chain that drives the
+     * apply pass is queued and built on the next {@link update}
+     * that sees all targets resolved. The clip's table row uses a
+     * placeholder `bound_track_group_head` until then — apply
+     * produces no contributions, so the clip is observationally
+     * inert (still subject to time advancement via the tick shader
+     * if `Playing` is set).
+     *
+     * Curves and tracks are interned synchronously since they're
+     * pure data — no `id_mapping` dependency.
+     *
+     * @param {ShadeAnimationClip} clip
+     * @returns {number} clip id
+     */
+    register_clip(clip) {
+        assert.defined(clip, 'clip');
+        assert.equal(clip.isShadeAnimationClip, true, 'clip.isShadeAnimationClip !== true');
+
+        const channels = clip.channels;
+
+        // Intern every channel's curves + track now. None of this
+        // depends on id_mapping — pure data uploads.
+        //
+        // Each curve goes through #intern_curve so two channels
+        // referencing the same AnimationCurve instance share one
+        // GPU upload. With 324 dancers retargeted at the same base
+        // clip this turns 324 × 195 channel uploads into 1 (the
+        // curves are read-only animation data — identical bytes
+        // wherever they're referenced).
+        const pending_channels = new Array(channels.length);
+        for (let i = 0; i < channels.length; i++) {
+            const channel = channels[i];
+            const curves = channel.curves;
+            const track_channels = {};
+            if (curves.x !== undefined) track_channels.x = this.#intern_curve(curves.x);
+            if (curves.y !== undefined) track_channels.y = this.#intern_curve(curves.y);
+            if (curves.z !== undefined) track_channels.z = this.#intern_curve(curves.z);
+            if (curves.w !== undefined) track_channels.w = this.#intern_curve(curves.w);
+
+            pending_channels[i] = {
+                track: this.#intern_track(track_channels),
+                target: channel.target,
+                property: channel.property,
+            };
+        }
+
+        // Reserve the clip row immediately with a placeholder head
+        // pointer. State mutators and the public id are usable from
+        // this point on; the bindings chain gets patched in once
+        // id_mapping has every target. `time` defaults to 0 (the
+        // playback offset relative to `time_start`; the apply
+        // shader does `effective_time = clip.time + clip.time_start`).
+        const clips_table = this.#database.get('animation_clips');
+        const clip_id = clips_table.add({
+            time: 0,
+            time_start: clip.start_time,
+            time_end: clip.end_time,
+            bound_track_group_head: ANIMATION_BOUND_TRACK_GROUP_NULL,
+            playback_rate: 1,
+            flags: 0,
+            playback_weight: 1,
+        });
+
+        const pending = { clip_id, channels: pending_channels };
+        if (!this.#try_complete_clip(pending)) {
+            this.#pending_clips.push(pending);
+        }
+
+        /*
+         Asked cheaply first: a clip with no scale channel at all — which is every clip a character
+         normally carries — is dismissed in one pass over its channels and remembered by nothing. Only
+         a clip that scales something is worth holding against the skins, now and as more arrive.
+        */
+        if (clip_scale_channels(clip).length > 0) {
+            this.#scaling_clips.set(clip_id, clip);
+
+            for (const skin of this.#skins_by_id.values()) {
+                this.#report_scale_conflicts(skin, clip);
+            }
+        }
+
+        return clip_id;
+    }
+
+    /**
+     * Attempt to build the bindings chain for a pending clip and
+     * patch its head pointer onto the clip row. Returns `true` when
+     * every channel target has resolved to a transforms-table row
+     * (and the chain was built); `false` when at least one is still
+     * missing.
+     *
+     * @param {{
+     *     clip_id: number,
+     *     channels: Array<{ track: number, target: Node3D, property: number }>,
+     * }} pending
+     * @returns {boolean}
+     */
+    #try_complete_clip(pending) {
+        const id_mapping = this.#scene_context.id_mapping;
+        const channels = pending.channels;
+        const clip_id = pending.clip_id;
+
+        const bindings = new Array(channels.length);
+        for (let i = 0; i < channels.length; i++) {
+            const ch = channels[i];
+            const instance = id_mapping.get(ch.target.id);
+            if (instance === undefined) return false;
+
+            bindings[i] = {
+                track: ch.track,
+                instance,
+                property: ch.property,
+            };
+        }
+
+        const groups_table = this.#database.get('animation_bound_track_groups');
+        const head_group_id = add_linked_chain(
+            groups_table,
+            bindings,
+            TRACKS_PER_GROUP_NODE,
+            (start, count, next) => {
+                const inline_bindings = new Array(TRACKS_PER_GROUP_NODE);
+                for (let j = 0; j < TRACKS_PER_GROUP_NODE; j++) {
+                    inline_bindings[j] = j < count ? bindings[start + j] : ZERO_BINDING;
+                }
+                return { bindings: inline_bindings, count, next, clip: clip_id };
+            }
+        );
+
+        // Patch the head pointer onto the already-allocated clip
+        // row. Read-modify-write preserves any user-driven state
+        // changes (set_time, set_flags, etc.) made between
+        // register_clip and the drain.
+        this.#patch_clip_field(clip_id, 'bound_track_group_head', head_group_id);
+
+        return true;
+    }
+
+    /**
+     * Drop a clip from the manager. Walks the bindings chain and
+     * removes every group-node + the clip row. Tolerates the clip
+     * still being pending (drains it from the queue without GPU
+     * touches besides the original row removal).
+     *
+     * Curves and tracks the clip referenced stay alive — they're
+     * shared via {@link #intern_curve} / {@link #intern_track} and
+     * may be in use by other clips. Removing them would need
+     * reference-counting the manager doesn't carry.
+     *
+     * Safe to call repeatedly on the same id: the second call finds the row unoccupied and
+     * returns without walking anything.
+     *
+     * @param {number} clip_id
+     */
+    unregister_clip(clip_id) {
+        assert.isNonNegativeInteger(clip_id, 'clip_id');
+
+        // Drop from pending queue if present (skip-and-keep-others
+        // pattern is cheaper than splice for the rare case of
+        // dozens-of-pending; if pending depth grows this can be
+        // revisited).
+        for (let i = this.#pending_clips.length - 1; i >= 0; i--) {
+            if (this.#pending_clips[i].clip_id === clip_id) {
+                this.#pending_clips.splice(i, 1);
+            }
+        }
+
+        const clips_table = this.#database.get('animation_clips');
+        const groups_table = this.#database.get('animation_bound_track_groups');
+
+        // Occupancy rather than `get` — see {@link unregister_skin}. A removed row reads back as
+        // zeros, and a zeroed `bound_track_group_head` is group 0, which the walk below would
+        // chase into itself forever.
+        if (!clips_table.occupancy.get(clip_id)) return;
+
+        const clip_record = clips_table.get(clip_id);
+
+        // Walk the bindings chain and remove every node. The chain
+        // may be empty (placeholder head NULL) if the clip is still
+        // pending or has been registered then drained but never
+        // completed; both cases skip the loop.
+        let block_id = clip_record.bound_track_group_head;
+        while (block_id !== ANIMATION_BOUND_TRACK_GROUP_NULL) {
+            const block = groups_table.get(block_id);
+            const next_id = block !== undefined ? block.next : ANIMATION_BOUND_TRACK_GROUP_NULL;
+            groups_table.remove(block_id);
+            block_id = next_id;
+        }
+
+        clips_table.remove(clip_id);
+
+        this.#scaling_clips.delete(clip_id);
+    }
+
+    /**
+     * Drop a skin from the manager. Walks the joint-block chain and
+     * removes every block + the skin row, and tears down every
+     * skinning binding pointing at this skin (so the skinning
+     * context doesn't try to read the now-freed skin's matrix
+     * offset on its next upload).
+     *
+     * The skin's matrix range goes back on the free list, for the next skin with the same
+     * joint count to take as-is. A spawn/despawn loop over a fixed cast therefore costs
+     * what the cast costs, not what the loop has run.
+     *
+     * Tolerates the skin still being pending. Safe to call repeatedly on the same id: the
+     * second call finds the row unoccupied and gives no range back twice.
+     *
+     * @param {number} skin_id
+     */
+    unregister_skin(skin_id) {
+        assert.isNonNegativeInteger(skin_id, 'skin_id');
+
+        this.#skins_by_id.delete(skin_id);
+
+        for (let i = this.#pending_skins.length - 1; i >= 0; i--) {
+            if (this.#pending_skins[i].skin_id === skin_id) {
+                this.#pending_skins.splice(i, 1);
+            }
+        }
+
+        // Tear down skinning bindings first so the skinning
+        // context's next upload doesn't reference a freed skin row
+        // (its upload path looks up skin_matrix_offset via
+        // get_skin_matrix_offset, which would assert post-removal).
+        this.#scene_context.skinning.unbind_all_by_skin(skin_id);
+
+        const skins_table = this.#database.get('animation_skins');
+        const blocks_table = this.#database.get('animation_skin_joint_blocks');
+
+        // Occupancy, not `get`, is what says the row is still this skin's. `remove` zero-fills a
+        // slot rather than dropping it and `get` reads those bytes back, so a second call would
+        // find a record whose `joint_block_head` is 0 — a valid block id, not the NULL sentinel —
+        // and the walk below would follow block 0 to block 0 for as long as the process lives.
+        if (!skins_table.occupancy.get(skin_id)) {
+            this.#skin_matrix_offsets.delete(skin_id);
+            return;
+        }
+
+        const skin_record = skins_table.get(skin_id);
+
+        // Walk the joint-block chain, terminating on the NULL
+        // sentinel (also the placeholder for a not-yet-patched head).
+        // Note: 0 is a VALID block row id — the first single-block
+        // skin registered into an empty table gets head 0, and
+        // treating it as a placeholder would leak its block, leaving
+        // the prep shader processing it against a recycled
+        // transforms-table row every frame.
+        let block_id = skin_record.joint_block_head;
+        while (block_id !== ANIMATION_SKIN_JOINT_BLOCK_NULL) {
+            const block = blocks_table.get(block_id);
+            const next_id = block !== undefined ? block.next : ANIMATION_SKIN_JOINT_BLOCK_NULL;
+            blocks_table.remove(block_id);
+            block_id = next_id;
+        }
+
+        skins_table.remove(skin_id);
+
+        // Give the matrix range back while the record that says how long it is still exists.
+        // Reaching here means the row was occupied, and a row is occupied only between the
+        // registration that set this offset and the delete below — the occupancy check at the
+        // top is what keeps a second call from handing the same base out twice.
+        const skin_matrix_offset = this.#skin_matrix_offsets.get(skin_id);
+
+        assert.defined(skin_matrix_offset, `skin ${skin_id} holds a live row but no matrix offset`);
+
+        this.#free_skin_matrix_range(skin_matrix_offset, skin_record.joint_count);
+
+        this.#skin_matrix_offsets.delete(skin_id);
+    }
+
+    /**
+     * Cached wrapper around {@link add_curve}: one upload per distinct curve, where distinct means
+     * distinct *content*.
+     *
+     * The instance cache answers first — the common case inside one clip, and free. Otherwise the
+     * curve's keys are hashed and held against every uploaded curve with that hash; a match on
+     * every key, tangents included, reuses that upload, and only a curve nobody has uploaded before
+     * goes through the low-level path. Either way the instance is remembered, so the next look-up
+     * of it is the free one.
+     *
+     * @param {AnimationCurve} curve
+     * @returns {number} curve id (index into the `animation_curves` table)
+     */
+    #intern_curve(curve) {
+        const cached = this.#curve_id_cache.get(curve);
+
+        if (cached !== undefined) {
+            return cached;
+        }
+
+        const hash = curve.hash();
+
+        let bucket = this.#curve_id_by_content.get(hash);
+
+        if (bucket === undefined) {
+            bucket = [];
+
+            this.#curve_id_by_content.set(hash, bucket);
+        } else {
+            for (const entry of bucket) {
+                if (entry.curve.equals(curve)) {
+                    this.#curve_id_cache.set(curve, entry.id);
+
+                    return entry.id;
+                }
+            }
+        }
+
+        const id = this.add_curve(curve);
+
+        this.#curve_id_cache.set(curve, id);
+
+        bucket.push({ curve, id });
+
+        return id;
+    }
+
+    /**
+     * Cache-keyed wrapper around {@link add_track}. Two channels that
+     * end up with the same (x, y, z, w, mask) — typical when their
+     * source curves are shared via {@link #intern_curve} — collapse
+     * to one track row instead of one row per channel.
+     *
+     * @param {{ x?: number, y?: number, z?: number, w?: number }} channels
+     * @returns {number} track id
+     */
+    #intern_track(channels) {
+        // Pack into a deterministic string key. -1 sentinel for
+        // missing channels keeps the (x=undefined) and (x=0) cases
+        // distinct.
+        const cx = channels.x ?? -1;
+        const cy = channels.y ?? -1;
+        const cz = channels.z ?? -1;
+        const cw = channels.w ?? -1;
+        const key = `${cx},${cy},${cz},${cw}`;
+
+        const cached = this.#track_id_cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const id = this.add_track(channels);
+        this.#track_id_cache.set(key, id);
+        return id;
+    }
+
+    /**
+     * Reserve `joint_count` consecutive matrices and answer with the base index.
+     *
+     * A range of exactly that length that some skin has given back is preferred over fresh
+     * space, which is what keeps a spawn/despawn loop from growing the buffer — see
+     * {@link #free_skin_matrix_ranges} for why the match is exact and never split.
+     *
+     * @param {number} joint_count length of the range, in matrices
+     * @returns {number} base matrix index of the reserved range
+     */
+    #allocate_skin_matrix_range(joint_count) {
+        const reusable = this.#free_skin_matrix_ranges.get(joint_count);
+
+        if (reusable !== undefined && reusable.length > 0) {
+            // Already inside the buffer — it was sized for this range when it was first
+            // handed out, and the buffer only ever grows.
+            return reusable.pop();
+        }
+
+        const skin_matrix_offset = this.#next_skin_matrix_offset;
+
+        this.#next_skin_matrix_offset += joint_count;
+        this.#ensure_skin_matrices_capacity(this.#next_skin_matrix_offset);
+
+        return skin_matrix_offset;
+    }
+
+    /**
+     * Put a matrix range back on the free list.
+     *
+     * The bytes are left as they are: the prep pass rewrites every matrix of a live skin each
+     * frame, so what a dead skin left behind is only ever read by a pass that no longer has a
+     * block pointing at it.
+     *
+     * @param {number} skin_matrix_offset base matrix index of the range
+     * @param {number} joint_count length of the range, in matrices
+     */
+    #free_skin_matrix_range(skin_matrix_offset, joint_count) {
+        let bucket = this.#free_skin_matrix_ranges.get(joint_count);
+
+        if (bucket === undefined) {
+            bucket = [];
+
+            this.#free_skin_matrix_ranges.set(joint_count, bucket);
+        }
+
+        bucket.push(skin_matrix_offset);
+    }
+
+    /**
+     * Grow the skinning-matrix scratch buffer if `required_count`
+     * exceeds current capacity. Doubles on grow until the requirement
+     * fits. The buffer's contents are scratch (rewritten every frame by
+     * the prep pass), so growth doesn't need to copy old data — but it
+     * does invalidate the previous {@link #skin_matrices_buffer}
+     * reference, which is why callers re-fetch through the getter.
+     *
+     * @param {number} required_count number of matrices that must fit
+     */
+    #ensure_skin_matrices_capacity(required_count) {
+        if (required_count <= this.#skin_matrices_capacity) {
+            return;
+        }
+
+        let new_capacity = Math.max(this.#skin_matrices_capacity, SKIN_MATRICES_INITIAL_CAPACITY);
+        while (new_capacity < required_count) {
+            new_capacity *= 2;
+        }
+
+        // Grow both ping-pong buffers in lockstep — they always share
+        // capacity. After grow both are zero-initialised, so the next
+        // prep dispatch needs to seed "previous" from "current"
+        // (otherwise velocity would interpolate against zero
+        // matrices). The flag below tells dispatch_skin_matrix_prep
+        // to issue that copy.
+        for (let i = 0; i < 2; i++) {
+            if (this.#skin_matrices_buffers[i] !== null) {
+                this.#skin_matrices_buffers[i].destroy();
+            }
+            this.#skin_matrices_buffers[i] = this.#device.createBuffer({
+                label: `${this.#label}/SkinMatrices/${i}`,
+                size: new_capacity * SKIN_MATRIX_BYTES,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+            });
+        }
+        this.#skin_matrices_capacity = new_capacity;
+        this.#first_frame_skin_matrices = true;
+    }
+
+    /**
+     * Flush all pending uploads (curves, keyframe blocks, tracks, clips,
+     * bound-track groups, skins, skin joint blocks) into the GPU
+     * database. Call once per frame, before any shader that reads from
+     * `database.buffer`.
+     *
+     * Also drains the pending-registration queues: skins and clips
+     * whose dependencies (joint Node3D rows, channel-target rows)
+     * weren't ready at register time get one shot per `update` to
+     * complete. Once `id_mapping` has the missing rows, the
+     * deferred chain build runs and the registration becomes
+     * observationally complete — the next-frame `database.update`
+     * picks up the patched head pointer.
+     *
+     * Does not touch the skin-matrices ping-pong buffers — those
+     * are scratch populated each frame by
+     * {@link dispatch_skin_matrix_prep}, not host data.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     */
+    update(cmd_ctx) {
+        this.#drain_pending_skins();
+        this.#drain_pending_clips();
+        this.#database.update(cmd_ctx);
+    }
+
+    #drain_pending_skins() {
+        // Walk back-to-front so successful completions can splice
+        // without disturbing the iteration's remaining indices.
+        for (let i = this.#pending_skins.length - 1; i >= 0; i--) {
+            if (this.#try_complete_skin(this.#pending_skins[i])) {
+                this.#pending_skins.splice(i, 1);
+            }
+        }
+    }
+
+    #drain_pending_clips() {
+        for (let i = this.#pending_clips.length - 1; i >= 0; i--) {
+            if (this.#try_complete_clip(this.#pending_clips[i])) {
+                this.#pending_clips.splice(i, 1);
+            }
+        }
+    }
+
+    /**
+     * Run the per-frame skin-matrix-prep dispatch and advance the
+     * ping-pong. Replaces the manual `shader_skin_matrix_prep.dispatch`
+     * the prototypes used to call — wrapping it here is how we get
+     * correct ping-pong behaviour across frames without leaking the
+     * buffer-role bookkeeping into every caller.
+     *
+     * No-op when no skins are registered (`group_count_x === 0`).
+     *
+     * Per-frame ordering:
+     *  1. Flip {@link #skin_matrices_current_index} — the buffer that
+     *     was last frame's "current" is about to be overwritten with
+     *     this frame's matrices; the other buffer (last frame's prev)
+     *     becomes this frame's "previous" implicit data source for
+     *     {@link prev_skin_matrices_buffer}.
+     *  2. Wait — clarify: we want last frame's "current" to BECOME
+     *     this frame's "previous". So flipping current_index moves
+     *     the role tag the correct way: what was current[i] becomes
+     *     previous (= buffers[1 - i]), and current[1 - i] is the
+     *     write target.
+     *  3. Dispatch the prep shader into the new current.
+     *  4. On the very first frame (or after a grow), copy current →
+     *     previous so the first velocity reads see matching matrices
+     *     and produce zero velocity.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     */
+    dispatch_skin_matrix_prep(cmd_ctx) {
+        const groups = this.#database
+            .get('animation_skin_joint_blocks')
+            .dispatch_group_count(SKIN_MATRIX_PREP_WORKGROUP_SIZE);
+        if (groups === 0) {
+            return;
+        }
+
+        // Flip the ping-pong: what was "current" last frame is no
+        // longer current, but it still holds valid matrices — and
+        // through the role flip it becomes this frame's
+        // `prev_skin_matrices_buffer`. The buffer we're flipping TO
+        // (the new "current") held two-frames-old matrices, about to
+        // be overwritten.
+        this.#skin_matrices_current_index = 1 - this.#skin_matrices_current_index;
+
+        const current = this.#skin_matrices_buffers[this.#skin_matrices_current_index];
+        const previous = this.#skin_matrices_buffers[1 - this.#skin_matrices_current_index];
+
+        shader_skin_matrix_prep.dispatch({
+            encoder: cmd_ctx,
+            group_count_x: groups,
+            bindings: {
+                animation_database: this.#database.buffer,
+                scene_database: this.#scene_context.scene_database_buffer,
+                skin_matrices: current,
+            },
+        });
+
+        // First-frame init (or post-grow): "previous" buffer is
+        // zero-initialised, which would have the velocity pass
+        // interpolate against the origin and produce huge nonsense
+        // on the first frame the skin appears. Seed prev from
+        // current — first velocity reads then yield zero, which is
+        // the right answer (no motion has happened yet).
+        if (this.#first_frame_skin_matrices) {
+            cmd_ctx.copyBufferToBuffer(
+                current, 0,
+                previous, 0,
+                current.size,
+            );
+            this.#first_frame_skin_matrices = false;
+        }
+    }
+
+    /**
+     * Per-frame orchestrator: drains pending registrations and the
+     * database queue, runs the GPU tick (advances `clip.time`),
+     * applies tracks into the pose accumulator, resolves the
+     * accumulator into node TRS, propagates the transform
+     * hierarchy, preps skinning matrices, and runs the skinning
+     * compute pass that deforms cloned vertex regions in place.
+     *
+     * One call replaces the ~80-line per-frame dispatch block every
+     * consumer would otherwise duplicate; the shader identities,
+     * workgroup sizes, pose-accumulator sizing, and pass ordering
+     * are all internal.
+     *
+     * `dt_seconds` is wall-clock seconds since the last call (the
+     * caller measures via `performance.now()` or equivalent). It's
+     * clamped to {@link MAX_DT_SECONDS} to keep a stall from
+     * leaking multiple seconds into the next tick.
+     *
+     * Clip tick/apply/resolve gate on bound tracks; hierarchy propagation runs
+     * every frame, before skin matrix prep and skinning. CPU-driven nodes need it
+     * too: scene uploads seed global with the previous pose, and propagation
+     * composes the current one. On idle frames it advances prev_global so motion
+     * vectors settle to zero. Skin passes still gate on registered skins.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     * @param {number} dt_seconds wall-clock seconds since last call
+     */
+    tick(cmd_ctx, dt_seconds) {
+        assert.defined(cmd_ctx, 'cmd_ctx');
+        assert.isNumber(dt_seconds, 'dt_seconds');
+
+        // Cap dt so a long stall doesn't fly the clip through dozens
+        // of loops or clamp it past the meaningful range.
+        const dt = Math.min(dt_seconds, MAX_DT_SECONDS);
+
+        // Flush database + drain pending registrations.
+        this.update(cmd_ctx);
+
+        // Only clip evaluation is conditional. Every scene needs current globals.
+        const apply_groups = this.#database
+            .get('animation_bound_track_groups')
+            .dispatch_group_count(ANIMATION_APPLY_WORKGROUP_SIZE);
+
+        if (apply_groups > 0) {
+            this.#encode_clip_passes(cmd_ctx, dt, apply_groups);
+        } else {
+            // CPU uploads seed global with the previous pose. Even without clips,
+            // compose current globals and advance prev_global before skinning/rendering.
+            const graph = new FrameGraph("GPUAnimationManager/TransformHierarchy");
+            graph_scene_update_transform_hierarchy({ graph, scene: this.#scene_context });
+            cmd_ctx.encodeGraph(graph);
+        }
+
+        // Skin matrix prep + skinning deformation. Both no-op when
+        // no skins are registered — and both run independent of the
+        // bound-track gate above: a registered skin whose joints
+        // are host-driven (no clips bound) must still be deformed
+        // each frame, otherwise it renders bind pose forever.
+        this.dispatch_skin_matrix_prep(cmd_ctx);
+        this.#scene_context.skinning.update(cmd_ctx);
+    }
+
+    /**
+     * Encode the clip-driven passes: GPU tick (advances
+     * `clip.time`), track apply into the pose accumulator, pose
+     * resolve into node TRS, and transform-hierarchy propagation.
+     * Split out of {@link tick} so the skin passes there run
+     * independently of the bound-track early-out.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     * @param {number} dt clamped delta time, seconds
+     * @param {number} apply_groups dispatch group count for the
+     *     apply pass — caller guarantees `> 0`
+     */
+    #encode_clip_passes(cmd_ctx, dt, apply_groups) {
+        // Tick: advance clip.time on the GPU.
+        const tick_groups = this.#database
+            .get('animation_clips')
+            .dispatch_group_count(ANIMATION_TICK_WORKGROUP_SIZE);
+        if (tick_groups > 0) {
+            shader_animation_tick.dispatch({
+                encoder: cmd_ctx,
+                group_count_x: tick_groups,
+                bindings: {
+                    dt,
+                    animation_database: this.#database.buffer,
+                },
+            });
+        }
+
+        // Size the pose accumulator to cover every allocated row of
+        // the transforms table — apply writes by absolute row index,
+        // resolve iterates the table via page iterator.
+        const transforms_table = this.#scene_context.scene_database.get('transforms');
+        const resolve_groups = transforms_table.dispatch_group_count(
+            ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE
+        );
+        this.ensure_pose_accumulator_capacity(transforms_table.element_capacity);
+
+        // ── Frame graph: apply → pose resolve → hierarchy propagate
+        const graph = new FrameGraph("GPUAnimationManager/Tick");
+        const gr_animation_database = graph_import_buffer(
+            graph, this.#database.buffer, "animation_database"
+        );
+        const gr_scene_database = graph_import_buffer(
+            graph, this.#scene_context.scene_database_buffer, "scene_database"
+        );
+        const gr_materials = graph_import_buffer(
+            graph, this.#scene_context.materials.metadata_table.buffer, "materials"
+        );
+        const gr_pose_accumulator = graph_import_buffer(
+            graph, this.#pose_accumulator_buffer, "pose_accumulator"
+        );
+
+        const apply_data = {};
+        const apply_pass = graph.add("animation/apply", apply_data, (data, resources, ctx) => {
+            shader_animation_apply.dispatch({
+                encoder: ctx.encoder,
+                group_count_x: apply_groups,
+                bindings: {
+                    animation_database: resources.get(data.animation_database),
+                    pose_accumulator: resources.get(data.pose_accumulator),
+                    materials: resources.get(data.materials),
+                },
+            });
+        });
+        apply_data.animation_database = apply_pass.read(gr_animation_database);
+        apply_data.materials = apply_pass.write(apply_pass.read(gr_materials));
+        apply_data.pose_accumulator = apply_pass.write(apply_pass.read(gr_pose_accumulator));
+
+        const resolve_data = {};
+        const resolve_pass = graph.add("animation/pose_resolve", resolve_data, (data, resources, ctx) => {
+            if (resolve_groups === 0) return;
+            shader_animation_pose_resolve.dispatch({
+                encoder: ctx.encoder,
+                group_count_x: resolve_groups,
+                bindings: {
+                    scene_database: resources.get(data.scene_database),
+                    pose_accumulator: resources.get(data.pose_accumulator),
+                },
+            });
+        });
+        resolve_data.scene_database = resolve_pass.write(resolve_pass.read(gr_scene_database));
+        resolve_data.pose_accumulator = resolve_pass.write(resolve_pass.read(apply_data.pose_accumulator));
+
+        graph_scene_update_transform_hierarchy({
+            graph,
+            scene: this.#scene_context,
+            scene_database: resolve_data.scene_database,
+        });
+
+        cmd_ctx.encodeGraph(graph);
+    }
+
+    destroy() {
+        this.#database.destroy();
+        for (let i = 0; i < 2; i++) {
+            if (this.#skin_matrices_buffers[i] !== null) {
+                this.#skin_matrices_buffers[i].destroy();
+                this.#skin_matrices_buffers[i] = null;
+            }
+        }
+        if (this.#pose_accumulator_buffer !== null) {
+            this.#pose_accumulator_buffer.destroy();
+            this.#pose_accumulator_buffer = null;
+        }
+    }
+}