@woosh/meep-engine 3.1.0 → 3.3.0

package/src/shade/playground/animation_prototype_skinning.js

@@ -1,647 +1,647 @@
-import Vector3 from "../../core/geom/Vector3.js";
-import { AnimationCurve } from "../../engine/animation/curve/AnimationCurve.js";
-import { Keyframe } from "../../engine/animation/curve/Keyframe.js";
-import { Transform } from "../../engine/ecs/transform/Transform.js";
-import { FrameGraph } from "../../engine/graphics/render/frame_graph/FrameGraph.js";
-import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
-import { shader_animation_apply, WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE } from "../renderer/animation/shader_animation_apply.js";
-import {
-    shader_animation_pose_resolve,
-    WORKGROUP_SIZE as ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE,
-} from "../renderer/animation/shader_animation_pose_resolve.js";
-import {
-    shader_skin_matrix_prep,
-    WORKGROUP_SIZE as SKIN_MATRIX_PREP_WORKGROUP_SIZE
-} from "../renderer/animation/skinning/shader_skin_matrix_prep.js";
-import { mat4x4f } from "../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { inspect_gpu_buffer_typed } from "../renderer/buffer/inspect_gpu_buffer_typed.js";
-import { Attribute } from "../renderer/geometry/Attribute.js";
-import { PlaneGeometry } from "../renderer/geometry/BoxGeometry.js";
-import { meshlet_geometry_build_from_geometry } from "../renderer/geometry/meshlet_geometry_build_from_geometry.js";
-import { make_box_geometry } from "../renderer/geometry/primitives/make_box_geometry.js";
-import { StandardAttributes } from "../renderer/geometry/StandardAttributes.js";
-import { make_sunlight } from "../renderer/light/make_sunlight.js";
-import { load_default_environment } from "./load_default_environment.js";
-import { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../renderer/scene/Mesh.js";
-import { Node3D } from "../renderer/scene/Node3D.js";
-import { SkinnedMesh } from "../renderer/scene/SkinnedMesh.js";
-import { Node3DProperty } from "../renderer/object_property/Node3DProperty.js";
-import { graph_scene_update_transform_hierarchy } from "../renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.js";
-import { graph_import_buffer } from "../renderer/shader/graph/graph_import_buffer.js";
-
-/**
- * Length of one bend cycle, in seconds. Half spent bending, half
- * unbending, smooth at both ends.
- */
-const BEND_PERIOD_SECONDS = 2.5;
-
-/**
- * Maximum bend angle (radians). 90° puts the forearm perpendicular to
- * the upper arm at the apex.
- */
-const MAX_BEND_RADIANS = Math.PI * 0.5;
-
-/**
- * Vertical extent of the arm box, in metres. Centred at scene origin —
- * vertices span Y in `[-ARM_HALF_HEIGHT, +ARM_HALF_HEIGHT]`. The
- * elbow joint sits at Y = 0 (mid-box); the shoulder is at Y =
- * `+ARM_HALF_HEIGHT`. With this layout the upper-arm region
- * (Y in `[0, +ARM_HALF_HEIGHT]`) weights to the shoulder, the
- * forearm (Y in `[-ARM_HALF_HEIGHT, 0]`) weights to the elbow.
- */
-const ARM_HALF_HEIGHT = 1.0;
-
-/**
- * Arm cross-section side length (square box: width = depth).
- */
-const ARM_CROSS_SECTION = 0.4;
-
-/**
- * Half-width of the smooth-blend band around the elbow, in metres.
- * Vertices with |y| < this distance get a linear blend between the
- * two joints' weights; everything outside is fully bound to one.
- * A small band keeps the bend visually crisp without causing the
- * candy-wrapper artifact that single-joint binding around a hinge
- * can produce on the inside of the elbow.
- */
-const BLEND_BAND_HALF_WIDTH = 0.15;
-
-
-/**
- * Build a column-major 4×4 translation matrix as a `Float32Array(16)`.
- * Column-major to match the WGSL `mat4x4<f32>` convention the
- * marshalling code reads.
- */
-function translate_mat4(tx, ty, tz) {
-    const m = new Float32Array(16);
-    m[0] = 1; m[5] = 1; m[10] = 1; m[15] = 1;
-    m[12] = tx; m[13] = ty; m[14] = tz;
-    return m;
-}
-
-/**
- * Identity 4×4.
- */
-function identity_mat4() {
-    const m = new Float32Array(16);
-    m[0] = 1; m[5] = 1; m[10] = 1; m[15] = 1;
-    return m;
-}
-
-/**
- * Build the arm geometry: a tall thin box centred on Y=0 with enough
- * vertical subdivision that the elbow bend is smooth, plus per-vertex
- * skinning attributes that bind the upper half to joint 0 (shoulder)
- * and the lower half to joint 1 (elbow), with a linear blend across a
- * narrow band at the elbow itself.
- */
-function build_arm_geometry() {
-    // Eight Y-segments give nine vertex rows along the arm — a few in
-    // each region and a couple inside the blend band. Coarse enough to
-    // see the meshlet structure if you want to debug it, fine enough
-    // that the elbow looks like a smooth bend rather than a hinge.
-    const HEIGHT_SEGMENTS = 8;
-
-    const geo = make_box_geometry(
-        ARM_CROSS_SECTION, ARM_HALF_HEIGHT * 2, ARM_CROSS_SECTION,
-        1, HEIGHT_SEGMENTS, 1,
-    );
-    geo.name = "Arm";
-
-    const positions = geo.getAttribute(StandardAttributes.Position).data;
-    const vertex_count = positions.length / 3;
-
-    // Joints palette has two entries (0 = shoulder, 1 = elbow). We use
-    // the first two slots of each per-vertex (joint, weight) pair; the
-    // unused tail slots stay zero, with the GPU's blend math cleanly
-    // ignoring them since the weights are zero too.
-    const joints = new Uint16Array(vertex_count * 4);
-    const weights = new Float32Array(vertex_count * 4);
-
-    const blend_lo = -BLEND_BAND_HALF_WIDTH;
-    const blend_hi = +BLEND_BAND_HALF_WIDTH;
-    const blend_width = blend_hi - blend_lo;
-
-    for (let i = 0; i < vertex_count; i++) {
-        const y = positions[i * 3 + 1];
-
-        // Joint indices are constant per vertex — only the weights vary
-        // by Y. Slot 0 always names the shoulder, slot 1 always names
-        // the elbow.
-        joints[i * 4 + 0] = 0; // shoulder
-        joints[i * 4 + 1] = 1; // elbow
-        joints[i * 4 + 2] = 0;
-        joints[i * 4 + 3] = 0;
-
-        let w_shoulder;
-        if (y >= blend_hi) {
-            w_shoulder = 1;
-        } else if (y <= blend_lo) {
-            w_shoulder = 0;
-        } else {
-            // Linear blend across the band — full shoulder at the
-            // band's upper edge, full elbow at the lower edge.
-            w_shoulder = (y - blend_lo) / blend_width;
-        }
-
-        weights[i * 4 + 0] = w_shoulder;
-        weights[i * 4 + 1] = 1 - w_shoulder;
-        weights[i * 4 + 2] = 0;
-        weights[i * 4 + 3] = 0;
-    }
-
-    geo.addAttribute(Attribute.from(joints, 4, StandardAttributes.SkinningJoints));
-    geo.addAttribute(Attribute.from(weights, 4, StandardAttributes.SkinningWeights));
-
-    return meshlet_geometry_build_from_geometry(geo);
-}
-
-/**
- * Build a 4-channel rotation track that bends the elbow around the
- * scene's X axis: angle 0 → MAX_BEND_RADIANS → 0 across one cycle, with
- * smoothed Hermite tangents.
- *
- * Quaternion period equals the visual period (unlike a full revolution,
- * a hinge sweep stays well under 360°), so we can sample the same
- * keyframes for every channel and the curve loops cleanly without
- * needing the half-angle trick the existing rotation prototype uses.
- */
-function build_bend_curves(period_seconds, max_angle) {
-    const SAMPLES = 8;
-
-    const x_keys = [];
-    const y_keys = [];
-    const z_keys = [];
-    const w_keys = [];
-
-    for (let i = 0; i <= SAMPLES; i++) {
-        const t = (i / SAMPLES) * period_seconds;
-
-        // Triangle wave through the bend angle: 0 at t=0, peak at the
-        // half-cycle, back to 0 at the cycle end. A cosine would also
-        // work; the triangle keeps the timing predictable and lets us
-        // see the shape of the Hermite tangent fit.
-        const phase = i / SAMPLES;
-        const angle = phase < 0.5
-            ? max_angle * (phase * 2)
-            : max_angle * ((1 - phase) * 2);
-
-        const half = angle * 0.5;
-        const s = Math.sin(half);
-        const c = Math.cos(half);
-
-        // Rotation around X — quaternion (sin(θ/2), 0, 0, cos(θ/2)).
-        x_keys.push(Keyframe.from(t, s));
-        y_keys.push(Keyframe.from(t, 0));
-        z_keys.push(Keyframe.from(t, 0));
-        w_keys.push(Keyframe.from(t, c));
-    }
-
-    const x = AnimationCurve.from(x_keys);
-    const y = AnimationCurve.from(y_keys);
-    const z = AnimationCurve.from(z_keys);
-    const w = AnimationCurve.from(w_keys);
-
-    x.alignAllTangents();
-    y.alignAllTangents();
-    z.alignAllTangents();
-    w.alignAllTangents();
-
-    return { x, y, z, w };
-}
-
-/**
- * Build a two-bone elbow rig: a tall box bound to a shoulder joint and
- * an elbow joint, with the elbow animated to bend a forearm-shaped
- * lower half around the elbow's X axis.
- *
- * The geometry is built once from `make_box_geometry`, with skinning
- * attributes appended manually. The shoulder Node3D sits at Y=+1 (the
- * top of the box) and the elbow Node3D is its child at local Y=-1
- * (mid-box). At bind pose both joints' world transforms compose to
- * place the elbow at the box midpoint with identity rotation, so the
- * inverse-bind matrices are simple translations.
- *
- * Per-frame the prototype dispatches:
- *  1. animation/apply         — writes elbow's local rotation
- *  2. transform hierarchy     — composes node.global from local TRS
- *  3. skin-matrix prep        — joint.global × inverse_bind → skin matrices
- *  4. skinning/apply (clones) — DQ-blend skinning into the cloned vertex region
- *
- * Rasterization in the next frame picks up the deformed clone.
- *
- * @param {object} args
- * @param {Renderer} args.renderer
- * @param {Scene} args.scene
- * @param {OrbitalCameraController} args.controller
- */
-export function animation_prototype_skinning({ renderer, scene, controller }) {
-
-    // ── Lighting & environment ──────────────────────────────────
-    scene.lights.add(make_sunlight({
-        intensity: 3,
-        direction: new Vector3(-0.4, -1, -0.3),
-    }));
-
-    load_default_environment(scene);
-
-    // ── Ground plane ────────────────────────────────────────────
-    const plane_material = new StandardShadeMaterial();
-    plane_material.diffuse_color.parse("#b5b5b5");
-    plane_material.roughness_factor = 1;
-    plane_material.metallic_factor = 0;
-
-    const plane_transform = Transform.fromJSON({ position: { x: 0, y: -2, z: 0 } });
-    plane_transform.lookAt(Vector3.up);
-
-    const plane = Mesh.from(
-        new PlaneGeometry(20, 20, 1, 1),
-        plane_material,
-        plane_transform.matrix,
-    );
-    plane.name = "Ground";
-
-    // ── Arm geometry + material ─────────────────────────────────
-    const arm_material = new StandardShadeMaterial();
-    arm_material.diffuse_color.parse("#F2994A");
-    arm_material.roughness_factor = 0.5;
-    arm_material.metallic_factor = 0;
-
-    const arm_geometry = build_arm_geometry();
-
-    // SkinnedMesh sits at scene origin with identity transform — joints
-    // are at scene root level (not parented to the mesh) so their
-    // globals live directly in world space, matching the convention
-    // the inverse-bind matrices below assume.
-    const arm = new SkinnedMesh();
-    arm.geometry = arm_geometry;
-    arm.material = arm_material;
-    arm.name = "SkinnedArm";
-    arm.updateMatrices();
-
-    // ── Joint hierarchy ─────────────────────────────────────────
-    // shoulder_joint at Y=+1 (top of the box, where the upper arm
-    // anchors). elbow_joint as its child, with local position (0, -1, 0)
-    // so its world position lands at Y=0 (mid-box, where the bend
-    // happens). Both have identity rotation at bind — animation drives
-    // elbow's rotation to bend.
-    const shoulder_joint = new Node3D();
-    shoulder_joint.name = "ShoulderJoint";
-    shoulder_joint.transform_local.setTranslation(0, ARM_HALF_HEIGHT, 0);
-
-    const elbow_joint = new Node3D();
-    elbow_joint.name = "ElbowJoint";
-    elbow_joint.transform_local.setTranslation(0, -ARM_HALF_HEIGHT, 0);
-
-    shoulder_joint.addChild(elbow_joint);
-    shoulder_joint.updateMatrices();
-
-    // ── Add to scene (order is load-bearing for joint ids) ──────
-    // GPUSceneContext.build assigns transforms-table rows in this
-    // order: scene root (0), meshes (1, 2, …), then non-mesh nodes
-    // (joints) recursively from the InstanceBatch. The constants at
-    // the top of this file capture the resulting row ids.
-    scene.add(plane);            // mesh row 1
-    scene.add(arm);              // mesh row 2
-    scene.add(shoulder_joint);   // non-mesh row 3 (children added via Scene.add recursion)
-                                 // → elbow_joint becomes non-mesh row 4
-
-    // ── Camera ──────────────────────────────────────────────────
-    {
-        const camera_position = new Vector3(3.5, 1.0, 4.0);
-        const arm_center = new Vector3(0, 0, 0);
-        controller.look(camera_position, arm_center);
-        controller.camera.near = 0.05;
-        controller.camera.far = 50;
-    }
-
-    // ── Animation manager (owned by scene context) ──────────────
-    const gpu_scene = renderer.scenes.obtain(scene);
-    const animation_manager = gpu_scene.animation_manager;
-
-    // ── Bend animation tracks (data only; clip wiring is deferred) ──
-    // Curves and tracks can be registered up front because they don't
-    // depend on the scene's transforms-table layout. The clip's
-    // bindings (which name target Node3D rows) need real row ids,
-    // which only exist after the first scene.build populates
-    // gpu_scene.id_mapping.
-    const bend = build_bend_curves(BEND_PERIOD_SECONDS, MAX_BEND_RADIANS);
-    const bend_x = animation_manager.add_curve(bend.x);
-    const bend_y = animation_manager.add_curve(bend.y);
-    const bend_z = animation_manager.add_curve(bend.z);
-    const bend_w = animation_manager.add_curve(bend.w);
-    const bend_track = animation_manager.add_track({
-        x: bend_x, y: bend_y, z: bend_z, w: bend_w,
-    });
-
-    // Expose for debugging from the console.
-    window.animation_manager = animation_manager;
-    window.gpu_scene = gpu_scene;
-    window.skinned_arm = arm;
-
-    /**
-     * Once-per-scene state populated on the first frame the scene
-     * has been built. Holds the clip id we drive each frame plus a
-     * sentinel so the per-frame callback knows we're ready.
-     */
-    let bend_clip = -1;
-    let initialised = false;
-
-    /**
-     * One-shot deferred setup. Resolves real Node3D row ids from
-     * `id_mapping` (populated by the first scene.build), registers
-     * the skin against those rows, and creates the clip whose
-     * binding targets the elbow's row. Re-running scene.build later
-     * doesn't change row ids for nodes that stay in place — id_mapping
-     * is keyed by Node3D.id which persists across rebuilds — so this
-     * setup is genuinely once-and-for-all under the current
-     * lifetime model.
-     */
-    function initialise_skinning() {
-        if (!gpu_scene.id_mapping.has(shoulder_joint.id)) {
-            // Scene hasn't been built yet — try again next frame.
-            return false;
-        }
-
-        const shoulder_row = gpu_scene.id_mapping.get(shoulder_joint.id);
-        const elbow_row = gpu_scene.id_mapping.get(elbow_joint.id);
-
-        console.log(`[skinning prototype] joint rows: shoulder=${shoulder_row}, elbow=${elbow_row}, instance_count=${gpu_scene.scene.instance_count}`);
-
-        // Two joints. inverse-bind matrices are the inverse of each
-        // joint's bind-pose world transform:
-        //   shoulder.bind_global = translate(0, +1, 0) → inverse = translate(0, -1, 0)
-        //   elbow.bind_global    = identity            → inverse = identity
-        // Elbow's bind_global is identity because the chain composes
-        // translate(0, +1, 0) × translate(0, -1, 0) = identity at bind.
-        // No mesh-world factor is needed on the skin — the rasterizer
-        // re-applies the arm's transform_global to the skinned vertex
-        // via the standard mesh transform path.
-        const skin_id = animation_manager.add_skin({
-            joints: [
-                {
-                    node: shoulder_row,
-                    inverse_bind: translate_mat4(0, -ARM_HALF_HEIGHT, 0),
-                },
-                {
-                    node: elbow_row,
-                    inverse_bind: identity_mat4(),
-                },
-            ],
-        });
-        // scene.build already ran, but the binding hadn't been
-        // registered (no skin was assigned at that point). Bind the
-        // mesh to the freshly-added skin now — bind() is idempotent
-        // and reuses the cached clone the build allocated.
-        gpu_scene.skinning.bind(arm, skin_id);
-
-        // One clip with one bound track — the rotation channel of the
-        // elbow joint, addressed by its real (looked-up) transforms-
-        // table row.
-        bend_clip = animation_manager.add_clip({
-            time: 0,
-            bindings: [
-                {
-                    track: bend_track,
-                    instance: elbow_row,
-                    property: Node3DProperty.Rotation,
-                },
-            ],
-        });
-
-        initialised = true;
-        return true;
-    }
-
-    // ── Per-frame: animation + skinning dispatch ────────────────
-    //
-    // Same one-frame-lag pattern as the other prototypes: we hook
-    // `onFrameFinished`, write into the scene/animation databases, and
-    // let the next frame's rasterization read the deformed cache.
-    const start_time_ms = performance.now();
-
-    renderer.onFrameFinished.add(() => {
-        const scene_database_buffer = gpu_scene.scene_database_buffer;
-        if (scene_database_buffer === undefined) {
-            // Scene hasn't been built yet.
-            return;
-        }
-
-        if (!initialised) {
-            // First time we see a built scene — resolve real Node3D row
-            // ids for the joints, register the skin + clip against
-            // them, then fall through to the regular per-frame path.
-            if (!initialise_skinning()) return;
-        }
-
-        const elapsed_s = (performance.now() - start_time_ms) * 1e-3;
-        const clip_time = elapsed_s % BEND_PERIOD_SECONDS;
-
-        animation_manager.set_time(bend_clip, clip_time);
-
-        // Throttled diagnostic — logs once per second across the whole
-        // pipeline to bisect the static-bend bug. The log line follows
-        // the data flow:
-        //   clip_time → cpu_shadow.time → gpu.time → elbow.local_rotation
-        //   → elbow.global → skin_matrices[1]
-        // (the skin matrix prep writes [shoulder, elbow] at offsets 0/1).
-        // The first stage that stops varying frame-to-frame is the one
-        // dropping the update.
-        //
-        // All readbacks are async — they snapshot the buffer state at
-        // the time the readback is queued. Note the previously-observed
-        // 1-frame lag on gpu.time vs cpu_shadow.time: readbacks are
-        // queued before this frame's animation_manager.update runs, so
-        // they see the previous frame's flushed values. Same lag applies
-        // to the elbow_local / elbow_global / skin_matrix readbacks.
-        if (Math.floor(elapsed_s) !== Math.floor(elapsed_s - 0.016)) {
-            const cpu_clip = animation_manager.database.get('animation_clips').get(bend_clip);
-            const elapsed_snapshot = elapsed_s;
-            const clip_time_snapshot = clip_time;
-            const elbow_row_snapshot = gpu_scene.id_mapping.get(elbow_joint.id);
-
-            // Bundle all readbacks in parallel so the throttled log lands
-            // as one line.
-            const p_clip = animation_manager.database.debug_table_read_element('animation_clips', bend_clip);
-            const p_elbow = gpu_scene.scene_database.debug_table_read_element('transforms', elbow_row_snapshot);
-
-            // skin_matrices is a flat scratch buffer (not a GPUDatabase
-            // table), so use inspect_gpu_buffer_typed directly. Read both
-            // matrices: skin[0] (shoulder × inv_bind, expected identity)
-            // serves as a known-good cross-reference for skin[1] (elbow ×
-            // inv_bind, the one that should track the bend).
-            const skin_matrices_buffer = animation_manager.skin_matrices_buffer;
-            const p_skin = skin_matrices_buffer === null
-                ? Promise.resolve(null)
-                : inspect_gpu_buffer_typed({
-                    buffer: skin_matrices_buffer,
-                    device: renderer.device,
-                    type: mat4x4f,
-                    offset: 0,
-                    count: 2,
-                });
-
-            // Float32Array.map returns Float32Array (coerces toFixed
-            // strings → NaN), so spread to plain Array before formatting.
-            const fmt_arr = (a, decimals) => `(${[...a].map(v => v.toFixed(decimals)).join(',')})`;
-
-            // Capture the values from this frame's pre-flush state for
-            // logging — skin_prep_dispatch_groups gates the skin_matrix_prep
-            // dispatch later in this frame, so it tells us if the prep ran
-            // at all.
-            const skin_prep_groups_snapshot = animation_manager.database
-                .get('animation_skin_joint_blocks')
-                .dispatch_group_count(SKIN_MATRIX_PREP_WORKGROUP_SIZE);
-
-            Promise.all([p_clip, p_elbow, p_skin]).then(([gpu_clip, gpu_elbow, gpu_skin]) => {
-                const gpu_time = gpu_clip?.time?.toFixed(3) ?? 'undef';
-                const elbow_rot = gpu_elbow?.local_rotation
-                    ? fmt_arr(gpu_elbow.local_rotation, 3)
-                    : 'undef';
-                // Show ALL columns of the rotation 3x3 — col0 is invariant
-                // for an X-axis rotation (X stays X), so col1/col2 carry
-                // the actual rotation signal. Translation in col3.xyz.
-                const elbow_global = gpu_elbow?.global
-                    ? `c0=${fmt_arr(gpu_elbow.global.slice(0, 3), 2)} c1=${fmt_arr(gpu_elbow.global.slice(4, 7), 2)} c2=${fmt_arr(gpu_elbow.global.slice(8, 11), 2)} t=${fmt_arr(gpu_elbow.global.slice(12, 15), 2)}`
-                    : 'undef';
-                const fmt_mat = (m) => `c0=${fmt_arr(m.slice(0, 3), 2)} c1=${fmt_arr(m.slice(4, 7), 2)} c2=${fmt_arr(m.slice(8, 11), 2)} t=${fmt_arr(m.slice(12, 15), 2)}`;
-                const skin0 = gpu_skin && gpu_skin[0] ? fmt_mat(gpu_skin[0]) : 'undef';
-                const skin1 = gpu_skin && gpu_skin[1] ? fmt_mat(gpu_skin[1]) : 'undef';
-                console.log(
-                    `[skin] elapsed=${elapsed_snapshot.toFixed(2)}s ` +
-                    `clip_time=${clip_time_snapshot.toFixed(3)} ` +
-                    `cpu=${cpu_clip.time.toFixed(3)} ` +
-                    `gpu=${gpu_time} ` +
-                    `prep_groups=${skin_prep_groups_snapshot} ` +
-                    `elbow.rot=${elbow_rot}\n` +
-                    `       elbow.global ${elbow_global}\n` +
-                    `       skin[0]      ${skin0}\n` +
-                    `       skin[1]      ${skin1}`
-                );
-            });
-        }
-
-        const apply_dispatch_groups = animation_manager.database
-            .get('animation_bound_track_groups')
-            .dispatch_group_count(ANIMATION_APPLY_WORKGROUP_SIZE);
-        if (apply_dispatch_groups === 0) {
-            return;
-        }
-
-        const skin_prep_dispatch_groups = animation_manager.database
-            .get('animation_skin_joint_blocks')
-            .dispatch_group_count(SKIN_MATRIX_PREP_WORKGROUP_SIZE);
-
-        // 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 = gpu_scene.scene_database.get('transforms');
-        const resolve_dispatch_groups = transforms_table.dispatch_group_count(
-            ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE
-        );
-        const pose_accumulator_rows = transforms_table.dispatch_page_count
-            * transforms_table.descriptor.elements_per_page;
-        animation_manager.ensure_pose_accumulator_capacity(pose_accumulator_rows);
-
-        const cmd = ShadeGPUCommandContext.create(
-            renderer.graphics,
-            "AnimationPrototypeSkinning/Tick"
-        );
-
-        // Animation database flush picks up the per-frame `set_time`
-        // write. (The scene-context update path also flushes earlier in
-        // the frame; this second flush is the one that catches the
-        // post-render clip-time advance.)
-        animation_manager.update(cmd);
-
-        const graph = new FrameGraph("AnimationPrototypeSkinning/Tick");
-
-        // ── Imported existing resources ────────────────────────
-        const gr_animation_database = graph_import_buffer(
-            graph, animation_manager.database.buffer, "animation_database"
-        );
-        const gr_scene_database = graph_import_buffer(
-            graph, scene_database_buffer, "scene_database"
-        );
-        const gr_materials = graph_import_buffer(
-            graph, gpu_scene.materials.metadata_table.buffer, "materials"
-        );
-        const gr_pose_accumulator = graph_import_buffer(
-            graph, animation_manager.pose_accumulator_buffer, "pose_accumulator"
-        );
-
-        // ── Pass 1: animation apply ───────────────────────────
-        // Atomic-adds elbow's bend contribution into the pose
-        // accumulator (one bound track → one rotation entry on the
-        // elbow row).
-        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_dispatch_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));
-
-        // ── Pass 2: pose resolve ──────────────────────────────
-        // Drains the accumulator into transforms_table.local_*,
-        // normalizes rotation, zeros the slot for next frame.
-        const resolve_data = {};
-        const resolve_pass = graph.add("animation/pose_resolve", resolve_data, (data, resources, ctx) => {
-            if (resolve_dispatch_groups === 0) {
-                return;
-            }
-            shader_animation_pose_resolve.dispatch({
-                encoder: ctx.encoder,
-                group_count_x: resolve_dispatch_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));
-
-        // ── Pass 3: propagate node.local → node.global ─────────
-        // Composes elbow_joint.global from its parent's global × its
-        // newly-resolved local matrix. The skin-matrix-prep pass below
-        // reads these globals.
-        graph_scene_update_transform_hierarchy({
-            graph,
-            scene: gpu_scene,
-            scene_database: resolve_data.scene_database,
-        });
-
-        cmd.encodeGraph(graph);
-
-        // ── Pass 4: skin-matrix prep ──────────────────────────
-        // Reads each registered joint's `node.global` from the scene
-        // database (now post-hierarchy-update) and writes
-        // `node.global × inverse_bind` into the skin-matrices scratch
-        // buffer the skinning pass will read. The manager handles
-        // the ping-pong with last-frame's matrices (used by the
-        // velocity post-pass).
-        animation_manager.dispatch_skin_matrix_prep(cmd);
-
-        // ── Pass 5: skinning apply (deform clone vertex regions) ─
-        // Pulls the binding table + dispatch lookup the skinning
-        // context owns, dispatches one workgroup per (binding, meshlet)
-        // pair, deforms positions/normals/tangents into the clones via
-        // dual-quaternion blending. Idempotent / no-op if no
-        // SkinnedMesh has been registered.
-        gpu_scene.skinning.update(cmd);
-
-        cmd.finish();
-    });
-}
+import Vector3 from "../../core/geom/Vector3.js";
+import { AnimationCurve } from "../../engine/animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../engine/animation/curve/Keyframe.js";
+import { Transform } from "../../engine/ecs/transform/Transform.js";
+import { FrameGraph } from "../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
+import { shader_animation_apply, WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE } from "../renderer/animation/shader_animation_apply.js";
+import {
+    shader_animation_pose_resolve,
+    WORKGROUP_SIZE as ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE,
+} from "../renderer/animation/shader_animation_pose_resolve.js";
+import {
+    shader_skin_matrix_prep,
+    WORKGROUP_SIZE as SKIN_MATRIX_PREP_WORKGROUP_SIZE
+} from "../renderer/animation/skinning/shader_skin_matrix_prep.js";
+import { mat4x4f } from "../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { inspect_gpu_buffer_typed } from "../renderer/buffer/inspect_gpu_buffer_typed.js";
+import { Attribute } from "../renderer/geometry/Attribute.js";
+import { PlaneGeometry } from "../renderer/geometry/BoxGeometry.js";
+import { meshlet_geometry_build_from_geometry } from "../renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { make_box_geometry } from "../renderer/geometry/primitives/make_box_geometry.js";
+import { StandardAttributes } from "../renderer/geometry/StandardAttributes.js";
+import { make_sunlight } from "../renderer/light/make_sunlight.js";
+import { load_default_environment } from "./load_default_environment.js";
+import { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../renderer/scene/Mesh.js";
+import { Node3D } from "../renderer/scene/Node3D.js";
+import { SkinnedMesh } from "../renderer/scene/SkinnedMesh.js";
+import { Node3DProperty } from "../renderer/object_property/Node3DProperty.js";
+import { graph_scene_update_transform_hierarchy } from "../renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.js";
+import { graph_import_buffer } from "../renderer/shader/graph/graph_import_buffer.js";
+
+/**
+ * Length of one bend cycle, in seconds. Half spent bending, half
+ * unbending, smooth at both ends.
+ */
+const BEND_PERIOD_SECONDS = 2.5;
+
+/**
+ * Maximum bend angle (radians). 90° puts the forearm perpendicular to
+ * the upper arm at the apex.
+ */
+const MAX_BEND_RADIANS = Math.PI * 0.5;
+
+/**
+ * Vertical extent of the arm box, in metres. Centred at scene origin —
+ * vertices span Y in `[-ARM_HALF_HEIGHT, +ARM_HALF_HEIGHT]`. The
+ * elbow joint sits at Y = 0 (mid-box); the shoulder is at Y =
+ * `+ARM_HALF_HEIGHT`. With this layout the upper-arm region
+ * (Y in `[0, +ARM_HALF_HEIGHT]`) weights to the shoulder, the
+ * forearm (Y in `[-ARM_HALF_HEIGHT, 0]`) weights to the elbow.
+ */
+const ARM_HALF_HEIGHT = 1.0;
+
+/**
+ * Arm cross-section side length (square box: width = depth).
+ */
+const ARM_CROSS_SECTION = 0.4;
+
+/**
+ * Half-width of the smooth-blend band around the elbow, in metres.
+ * Vertices with |y| < this distance get a linear blend between the
+ * two joints' weights; everything outside is fully bound to one.
+ * A small band keeps the bend visually crisp without causing the
+ * candy-wrapper artifact that single-joint binding around a hinge
+ * can produce on the inside of the elbow.
+ */
+const BLEND_BAND_HALF_WIDTH = 0.15;
+
+
+/**
+ * Build a column-major 4×4 translation matrix as a `Float32Array(16)`.
+ * Column-major to match the WGSL `mat4x4<f32>` convention the
+ * marshalling code reads.
+ */
+function translate_mat4(tx, ty, tz) {
+    const m = new Float32Array(16);
+    m[0] = 1; m[5] = 1; m[10] = 1; m[15] = 1;
+    m[12] = tx; m[13] = ty; m[14] = tz;
+    return m;
+}
+
+/**
+ * Identity 4×4.
+ */
+function identity_mat4() {
+    const m = new Float32Array(16);
+    m[0] = 1; m[5] = 1; m[10] = 1; m[15] = 1;
+    return m;
+}
+
+/**
+ * Build the arm geometry: a tall thin box centred on Y=0 with enough
+ * vertical subdivision that the elbow bend is smooth, plus per-vertex
+ * skinning attributes that bind the upper half to joint 0 (shoulder)
+ * and the lower half to joint 1 (elbow), with a linear blend across a
+ * narrow band at the elbow itself.
+ */
+function build_arm_geometry() {
+    // Eight Y-segments give nine vertex rows along the arm — a few in
+    // each region and a couple inside the blend band. Coarse enough to
+    // see the meshlet structure if you want to debug it, fine enough
+    // that the elbow looks like a smooth bend rather than a hinge.
+    const HEIGHT_SEGMENTS = 8;
+
+    const geo = make_box_geometry(
+        ARM_CROSS_SECTION, ARM_HALF_HEIGHT * 2, ARM_CROSS_SECTION,
+        1, HEIGHT_SEGMENTS, 1,
+    );
+    geo.name = "Arm";
+
+    const positions = geo.getAttribute(StandardAttributes.Position).data;
+    const vertex_count = positions.length / 3;
+
+    // Joints palette has two entries (0 = shoulder, 1 = elbow). We use
+    // the first two slots of each per-vertex (joint, weight) pair; the
+    // unused tail slots stay zero, with the GPU's blend math cleanly
+    // ignoring them since the weights are zero too.
+    const joints = new Uint16Array(vertex_count * 4);
+    const weights = new Float32Array(vertex_count * 4);
+
+    const blend_lo = -BLEND_BAND_HALF_WIDTH;
+    const blend_hi = +BLEND_BAND_HALF_WIDTH;
+    const blend_width = blend_hi - blend_lo;
+
+    for (let i = 0; i < vertex_count; i++) {
+        const y = positions[i * 3 + 1];
+
+        // Joint indices are constant per vertex — only the weights vary
+        // by Y. Slot 0 always names the shoulder, slot 1 always names
+        // the elbow.
+        joints[i * 4 + 0] = 0; // shoulder
+        joints[i * 4 + 1] = 1; // elbow
+        joints[i * 4 + 2] = 0;
+        joints[i * 4 + 3] = 0;
+
+        let w_shoulder;
+        if (y >= blend_hi) {
+            w_shoulder = 1;
+        } else if (y <= blend_lo) {
+            w_shoulder = 0;
+        } else {
+            // Linear blend across the band — full shoulder at the
+            // band's upper edge, full elbow at the lower edge.
+            w_shoulder = (y - blend_lo) / blend_width;
+        }
+
+        weights[i * 4 + 0] = w_shoulder;
+        weights[i * 4 + 1] = 1 - w_shoulder;
+        weights[i * 4 + 2] = 0;
+        weights[i * 4 + 3] = 0;
+    }
+
+    geo.addAttribute(Attribute.from(joints, 4, StandardAttributes.SkinningJoints));
+    geo.addAttribute(Attribute.from(weights, 4, StandardAttributes.SkinningWeights));
+
+    return meshlet_geometry_build_from_geometry(geo);
+}
+
+/**
+ * Build a 4-channel rotation track that bends the elbow around the
+ * scene's X axis: angle 0 → MAX_BEND_RADIANS → 0 across one cycle, with
+ * smoothed Hermite tangents.
+ *
+ * Quaternion period equals the visual period (unlike a full revolution,
+ * a hinge sweep stays well under 360°), so we can sample the same
+ * keyframes for every channel and the curve loops cleanly without
+ * needing the half-angle trick the existing rotation prototype uses.
+ */
+function build_bend_curves(period_seconds, max_angle) {
+    const SAMPLES = 8;
+
+    const x_keys = [];
+    const y_keys = [];
+    const z_keys = [];
+    const w_keys = [];
+
+    for (let i = 0; i <= SAMPLES; i++) {
+        const t = (i / SAMPLES) * period_seconds;
+
+        // Triangle wave through the bend angle: 0 at t=0, peak at the
+        // half-cycle, back to 0 at the cycle end. A cosine would also
+        // work; the triangle keeps the timing predictable and lets us
+        // see the shape of the Hermite tangent fit.
+        const phase = i / SAMPLES;
+        const angle = phase < 0.5
+            ? max_angle * (phase * 2)
+            : max_angle * ((1 - phase) * 2);
+
+        const half = angle * 0.5;
+        const s = Math.sin(half);
+        const c = Math.cos(half);
+
+        // Rotation around X — quaternion (sin(θ/2), 0, 0, cos(θ/2)).
+        x_keys.push(Keyframe.from(t, s));
+        y_keys.push(Keyframe.from(t, 0));
+        z_keys.push(Keyframe.from(t, 0));
+        w_keys.push(Keyframe.from(t, c));
+    }
+
+    const x = AnimationCurve.from(x_keys);
+    const y = AnimationCurve.from(y_keys);
+    const z = AnimationCurve.from(z_keys);
+    const w = AnimationCurve.from(w_keys);
+
+    x.alignAllTangents();
+    y.alignAllTangents();
+    z.alignAllTangents();
+    w.alignAllTangents();
+
+    return { x, y, z, w };
+}
+
+/**
+ * Build a two-bone elbow rig: a tall box bound to a shoulder joint and
+ * an elbow joint, with the elbow animated to bend a forearm-shaped
+ * lower half around the elbow's X axis.
+ *
+ * The geometry is built once from `make_box_geometry`, with skinning
+ * attributes appended manually. The shoulder Node3D sits at Y=+1 (the
+ * top of the box) and the elbow Node3D is its child at local Y=-1
+ * (mid-box). At bind pose both joints' world transforms compose to
+ * place the elbow at the box midpoint with identity rotation, so the
+ * inverse-bind matrices are simple translations.
+ *
+ * Per-frame the prototype dispatches:
+ *  1. animation/apply         — writes elbow's local rotation
+ *  2. transform hierarchy     — composes node.global from local TRS
+ *  3. skin-matrix prep        — joint.global × inverse_bind → skin matrices
+ *  4. skinning/apply (clones) — DQ-blend skinning into the cloned vertex region
+ *
+ * Rasterization in the next frame picks up the deformed clone.
+ *
+ * @param {object} args
+ * @param {Renderer} args.renderer
+ * @param {Scene} args.scene
+ * @param {OrbitalCameraController} args.controller
+ */
+export function animation_prototype_skinning({ renderer, scene, controller }) {
+
+    // ── Lighting & environment ──────────────────────────────────
+    scene.lights.add(make_sunlight({
+        intensity: 3,
+        direction: new Vector3(-0.4, -1, -0.3),
+    }));
+
+    load_default_environment(scene);
+
+    // ── Ground plane ────────────────────────────────────────────
+    const plane_material = new StandardShadeMaterial();
+    plane_material.diffuse_color.parse("#b5b5b5");
+    plane_material.roughness_factor = 1;
+    plane_material.metallic_factor = 0;
+
+    const plane_transform = Transform.fromJSON({ position: { x: 0, y: -2, z: 0 } });
+    plane_transform.lookAt(Vector3.up);
+
+    const plane = Mesh.from(
+        new PlaneGeometry(20, 20, 1, 1),
+        plane_material,
+        plane_transform.matrix,
+    );
+    plane.name = "Ground";
+
+    // ── Arm geometry + material ─────────────────────────────────
+    const arm_material = new StandardShadeMaterial();
+    arm_material.diffuse_color.parse("#F2994A");
+    arm_material.roughness_factor = 0.5;
+    arm_material.metallic_factor = 0;
+
+    const arm_geometry = build_arm_geometry();
+
+    // SkinnedMesh sits at scene origin with identity transform — joints
+    // are at scene root level (not parented to the mesh) so their
+    // globals live directly in world space, matching the convention
+    // the inverse-bind matrices below assume.
+    const arm = new SkinnedMesh();
+    arm.geometry = arm_geometry;
+    arm.material = arm_material;
+    arm.name = "SkinnedArm";
+    arm.updateMatrices();
+
+    // ── Joint hierarchy ─────────────────────────────────────────
+    // shoulder_joint at Y=+1 (top of the box, where the upper arm
+    // anchors). elbow_joint as its child, with local position (0, -1, 0)
+    // so its world position lands at Y=0 (mid-box, where the bend
+    // happens). Both have identity rotation at bind — animation drives
+    // elbow's rotation to bend.
+    const shoulder_joint = new Node3D();
+    shoulder_joint.name = "ShoulderJoint";
+    shoulder_joint.transform_local.setTranslation(0, ARM_HALF_HEIGHT, 0);
+
+    const elbow_joint = new Node3D();
+    elbow_joint.name = "ElbowJoint";
+    elbow_joint.transform_local.setTranslation(0, -ARM_HALF_HEIGHT, 0);
+
+    shoulder_joint.addChild(elbow_joint);
+    shoulder_joint.updateMatrices();
+
+    // ── Add to scene (order is load-bearing for joint ids) ──────
+    // GPUSceneContext.build assigns transforms-table rows in this
+    // order: scene root (0), meshes (1, 2, …), then non-mesh nodes
+    // (joints) recursively from the InstanceBatch. The constants at
+    // the top of this file capture the resulting row ids.
+    scene.add(plane);            // mesh row 1
+    scene.add(arm);              // mesh row 2
+    scene.add(shoulder_joint);   // non-mesh row 3 (children added via Scene.add recursion)
+                                 // → elbow_joint becomes non-mesh row 4
+
+    // ── Camera ──────────────────────────────────────────────────
+    {
+        const camera_position = new Vector3(3.5, 1.0, 4.0);
+        const arm_center = new Vector3(0, 0, 0);
+        controller.look(camera_position, arm_center);
+        controller.camera.near = 0.05;
+        controller.camera.far = 50;
+    }
+
+    // ── Animation manager (owned by scene context) ──────────────
+    const gpu_scene = renderer.scenes.obtain(scene);
+    const animation_manager = gpu_scene.animation_manager;
+
+    // ── Bend animation tracks (data only; clip wiring is deferred) ──
+    // Curves and tracks can be registered up front because they don't
+    // depend on the scene's transforms-table layout. The clip's
+    // bindings (which name target Node3D rows) need real row ids,
+    // which only exist after the first scene.build populates
+    // gpu_scene.id_mapping.
+    const bend = build_bend_curves(BEND_PERIOD_SECONDS, MAX_BEND_RADIANS);
+    const bend_x = animation_manager.add_curve(bend.x);
+    const bend_y = animation_manager.add_curve(bend.y);
+    const bend_z = animation_manager.add_curve(bend.z);
+    const bend_w = animation_manager.add_curve(bend.w);
+    const bend_track = animation_manager.add_track({
+        x: bend_x, y: bend_y, z: bend_z, w: bend_w,
+    });
+
+    // Expose for debugging from the console.
+    window.animation_manager = animation_manager;
+    window.gpu_scene = gpu_scene;
+    window.skinned_arm = arm;
+
+    /**
+     * Once-per-scene state populated on the first frame the scene
+     * has been built. Holds the clip id we drive each frame plus a
+     * sentinel so the per-frame callback knows we're ready.
+     */
+    let bend_clip = -1;
+    let initialised = false;
+
+    /**
+     * One-shot deferred setup. Resolves real Node3D row ids from
+     * `id_mapping` (populated by the first scene.build), registers
+     * the skin against those rows, and creates the clip whose
+     * binding targets the elbow's row. Re-running scene.build later
+     * doesn't change row ids for nodes that stay in place — id_mapping
+     * is keyed by Node3D.id which persists across rebuilds — so this
+     * setup is genuinely once-and-for-all under the current
+     * lifetime model.
+     */
+    function initialise_skinning() {
+        if (!gpu_scene.id_mapping.has(shoulder_joint.id)) {
+            // Scene hasn't been built yet — try again next frame.
+            return false;
+        }
+
+        const shoulder_row = gpu_scene.id_mapping.get(shoulder_joint.id);
+        const elbow_row = gpu_scene.id_mapping.get(elbow_joint.id);
+
+        console.log(`[skinning prototype] joint rows: shoulder=${shoulder_row}, elbow=${elbow_row}, instance_count=${gpu_scene.scene.instance_count}`);
+
+        // Two joints. inverse-bind matrices are the inverse of each
+        // joint's bind-pose world transform:
+        //   shoulder.bind_global = translate(0, +1, 0) → inverse = translate(0, -1, 0)
+        //   elbow.bind_global    = identity            → inverse = identity
+        // Elbow's bind_global is identity because the chain composes
+        // translate(0, +1, 0) × translate(0, -1, 0) = identity at bind.
+        // No mesh-world factor is needed on the skin — the rasterizer
+        // re-applies the arm's transform_global to the skinned vertex
+        // via the standard mesh transform path.
+        const skin_id = animation_manager.add_skin({
+            joints: [
+                {
+                    node: shoulder_row,
+                    inverse_bind: translate_mat4(0, -ARM_HALF_HEIGHT, 0),
+                },
+                {
+                    node: elbow_row,
+                    inverse_bind: identity_mat4(),
+                },
+            ],
+        });
+        // scene.build already ran, but the binding hadn't been
+        // registered (no skin was assigned at that point). Bind the
+        // mesh to the freshly-added skin now — bind() is idempotent
+        // and reuses the cached clone the build allocated.
+        gpu_scene.skinning.bind(arm, skin_id);
+
+        // One clip with one bound track — the rotation channel of the
+        // elbow joint, addressed by its real (looked-up) transforms-
+        // table row.
+        bend_clip = animation_manager.add_clip({
+            time: 0,
+            bindings: [
+                {
+                    track: bend_track,
+                    instance: elbow_row,
+                    property: Node3DProperty.Rotation,
+                },
+            ],
+        });
+
+        initialised = true;
+        return true;
+    }
+
+    // ── Per-frame: animation + skinning dispatch ────────────────
+    //
+    // Same one-frame-lag pattern as the other prototypes: we hook
+    // `onFrameFinished`, write into the scene/animation databases, and
+    // let the next frame's rasterization read the deformed cache.
+    const start_time_ms = performance.now();
+
+    renderer.onFrameFinished.add(() => {
+        const scene_database_buffer = gpu_scene.scene_database_buffer;
+        if (scene_database_buffer === undefined) {
+            // Scene hasn't been built yet.
+            return;
+        }
+
+        if (!initialised) {
+            // First time we see a built scene — resolve real Node3D row
+            // ids for the joints, register the skin + clip against
+            // them, then fall through to the regular per-frame path.
+            if (!initialise_skinning()) return;
+        }
+
+        const elapsed_s = (performance.now() - start_time_ms) * 1e-3;
+        const clip_time = elapsed_s % BEND_PERIOD_SECONDS;
+
+        animation_manager.set_time(bend_clip, clip_time);
+
+        // Throttled diagnostic — logs once per second across the whole
+        // pipeline to bisect the static-bend bug. The log line follows
+        // the data flow:
+        //   clip_time → cpu_shadow.time → gpu.time → elbow.local_rotation
+        //   → elbow.global → skin_matrices[1]
+        // (the skin matrix prep writes [shoulder, elbow] at offsets 0/1).
+        // The first stage that stops varying frame-to-frame is the one
+        // dropping the update.
+        //
+        // All readbacks are async — they snapshot the buffer state at
+        // the time the readback is queued. Note the previously-observed
+        // 1-frame lag on gpu.time vs cpu_shadow.time: readbacks are
+        // queued before this frame's animation_manager.update runs, so
+        // they see the previous frame's flushed values. Same lag applies
+        // to the elbow_local / elbow_global / skin_matrix readbacks.
+        if (Math.floor(elapsed_s) !== Math.floor(elapsed_s - 0.016)) {
+            const cpu_clip = animation_manager.database.get('animation_clips').get(bend_clip);
+            const elapsed_snapshot = elapsed_s;
+            const clip_time_snapshot = clip_time;
+            const elbow_row_snapshot = gpu_scene.id_mapping.get(elbow_joint.id);
+
+            // Bundle all readbacks in parallel so the throttled log lands
+            // as one line.
+            const p_clip = animation_manager.database.debug_table_read_element('animation_clips', bend_clip);
+            const p_elbow = gpu_scene.scene_database.debug_table_read_element('transforms', elbow_row_snapshot);
+
+            // skin_matrices is a flat scratch buffer (not a GPUDatabase
+            // table), so use inspect_gpu_buffer_typed directly. Read both
+            // matrices: skin[0] (shoulder × inv_bind, expected identity)
+            // serves as a known-good cross-reference for skin[1] (elbow ×
+            // inv_bind, the one that should track the bend).
+            const skin_matrices_buffer = animation_manager.skin_matrices_buffer;
+            const p_skin = skin_matrices_buffer === null
+                ? Promise.resolve(null)
+                : inspect_gpu_buffer_typed({
+                    buffer: skin_matrices_buffer,
+                    device: renderer.device,
+                    type: mat4x4f,
+                    offset: 0,
+                    count: 2,
+                });
+
+            // Float32Array.map returns Float32Array (coerces toFixed
+            // strings → NaN), so spread to plain Array before formatting.
+            const fmt_arr = (a, decimals) => `(${[...a].map(v => v.toFixed(decimals)).join(',')})`;
+
+            // Capture the values from this frame's pre-flush state for
+            // logging — skin_prep_dispatch_groups gates the skin_matrix_prep
+            // dispatch later in this frame, so it tells us if the prep ran
+            // at all.
+            const skin_prep_groups_snapshot = animation_manager.database
+                .get('animation_skin_joint_blocks')
+                .dispatch_group_count(SKIN_MATRIX_PREP_WORKGROUP_SIZE);
+
+            Promise.all([p_clip, p_elbow, p_skin]).then(([gpu_clip, gpu_elbow, gpu_skin]) => {
+                const gpu_time = gpu_clip?.time?.toFixed(3) ?? 'undef';
+                const elbow_rot = gpu_elbow?.local_rotation
+                    ? fmt_arr(gpu_elbow.local_rotation, 3)
+                    : 'undef';
+                // Show ALL columns of the rotation 3x3 — col0 is invariant
+                // for an X-axis rotation (X stays X), so col1/col2 carry
+                // the actual rotation signal. Translation in col3.xyz.
+                const elbow_global = gpu_elbow?.global
+                    ? `c0=${fmt_arr(gpu_elbow.global.slice(0, 3), 2)} c1=${fmt_arr(gpu_elbow.global.slice(4, 7), 2)} c2=${fmt_arr(gpu_elbow.global.slice(8, 11), 2)} t=${fmt_arr(gpu_elbow.global.slice(12, 15), 2)}`
+                    : 'undef';
+                const fmt_mat = (m) => `c0=${fmt_arr(m.slice(0, 3), 2)} c1=${fmt_arr(m.slice(4, 7), 2)} c2=${fmt_arr(m.slice(8, 11), 2)} t=${fmt_arr(m.slice(12, 15), 2)}`;
+                const skin0 = gpu_skin && gpu_skin[0] ? fmt_mat(gpu_skin[0]) : 'undef';
+                const skin1 = gpu_skin && gpu_skin[1] ? fmt_mat(gpu_skin[1]) : 'undef';
+                console.log(
+                    `[skin] elapsed=${elapsed_snapshot.toFixed(2)}s ` +
+                    `clip_time=${clip_time_snapshot.toFixed(3)} ` +
+                    `cpu=${cpu_clip.time.toFixed(3)} ` +
+                    `gpu=${gpu_time} ` +
+                    `prep_groups=${skin_prep_groups_snapshot} ` +
+                    `elbow.rot=${elbow_rot}\n` +
+                    `       elbow.global ${elbow_global}\n` +
+                    `       skin[0]      ${skin0}\n` +
+                    `       skin[1]      ${skin1}`
+                );
+            });
+        }
+
+        const apply_dispatch_groups = animation_manager.database
+            .get('animation_bound_track_groups')
+            .dispatch_group_count(ANIMATION_APPLY_WORKGROUP_SIZE);
+        if (apply_dispatch_groups === 0) {
+            return;
+        }
+
+        const skin_prep_dispatch_groups = animation_manager.database
+            .get('animation_skin_joint_blocks')
+            .dispatch_group_count(SKIN_MATRIX_PREP_WORKGROUP_SIZE);
+
+        // 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 = gpu_scene.scene_database.get('transforms');
+        const resolve_dispatch_groups = transforms_table.dispatch_group_count(
+            ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE
+        );
+        const pose_accumulator_rows = transforms_table.dispatch_page_count
+            * transforms_table.descriptor.elements_per_page;
+        animation_manager.ensure_pose_accumulator_capacity(pose_accumulator_rows);
+
+        const cmd = ShadeGPUCommandContext.create(
+            renderer.graphics,
+            "AnimationPrototypeSkinning/Tick"
+        );
+
+        // Animation database flush picks up the per-frame `set_time`
+        // write. (The scene-context update path also flushes earlier in
+        // the frame; this second flush is the one that catches the
+        // post-render clip-time advance.)
+        animation_manager.update(cmd);
+
+        const graph = new FrameGraph("AnimationPrototypeSkinning/Tick");
+
+        // ── Imported existing resources ────────────────────────
+        const gr_animation_database = graph_import_buffer(
+            graph, animation_manager.database.buffer, "animation_database"
+        );
+        const gr_scene_database = graph_import_buffer(
+            graph, scene_database_buffer, "scene_database"
+        );
+        const gr_materials = graph_import_buffer(
+            graph, gpu_scene.materials.metadata_table.buffer, "materials"
+        );
+        const gr_pose_accumulator = graph_import_buffer(
+            graph, animation_manager.pose_accumulator_buffer, "pose_accumulator"
+        );
+
+        // ── Pass 1: animation apply ───────────────────────────
+        // Atomic-adds elbow's bend contribution into the pose
+        // accumulator (one bound track → one rotation entry on the
+        // elbow row).
+        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_dispatch_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));
+
+        // ── Pass 2: pose resolve ──────────────────────────────
+        // Drains the accumulator into transforms_table.local_*,
+        // normalizes rotation, zeros the slot for next frame.
+        const resolve_data = {};
+        const resolve_pass = graph.add("animation/pose_resolve", resolve_data, (data, resources, ctx) => {
+            if (resolve_dispatch_groups === 0) {
+                return;
+            }
+            shader_animation_pose_resolve.dispatch({
+                encoder: ctx.encoder,
+                group_count_x: resolve_dispatch_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));
+
+        // ── Pass 3: propagate node.local → node.global ─────────
+        // Composes elbow_joint.global from its parent's global × its
+        // newly-resolved local matrix. The skin-matrix-prep pass below
+        // reads these globals.
+        graph_scene_update_transform_hierarchy({
+            graph,
+            scene: gpu_scene,
+            scene_database: resolve_data.scene_database,
+        });
+
+        cmd.encodeGraph(graph);
+
+        // ── Pass 4: skin-matrix prep ──────────────────────────
+        // Reads each registered joint's `node.global` from the scene
+        // database (now post-hierarchy-update) and writes
+        // `node.global × inverse_bind` into the skin-matrices scratch
+        // buffer the skinning pass will read. The manager handles
+        // the ping-pong with last-frame's matrices (used by the
+        // velocity post-pass).
+        animation_manager.dispatch_skin_matrix_prep(cmd);
+
+        // ── Pass 5: skinning apply (deform clone vertex regions) ─
+        // Pulls the binding table + dispatch lookup the skinning
+        // context owns, dispatches one workgroup per (binding, meshlet)
+        // pair, deforms positions/normals/tangents into the clones via
+        // dual-quaternion blending. Idempotent / no-op if no
+        // SkinnedMesh has been registered.
+        gpu_scene.skinning.update(cmd);
+
+        cmd.finish();
+    });
+}