@woosh/meep-engine 3.56.0 → 3.58.0

package/src/shade/playground/additive_blending/main.js

@@ -1,529 +1,529 @@
-import Vector3 from "../../../core/geom/Vector3.js";
-import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
-import { AnimationCurve } from "../../../engine/animation/curve/AnimationCurve.js";
-import { Keyframe } from "../../../engine/animation/curve/Keyframe.js";
-import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
-import { Name } from "../../../engine/ecs/name/Name.js";
-import { TransformAttachment } from "../../../engine/ecs/transform-attachment/TransformAttachment.js";
-import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
-import { MeshSkin } from "../../../engine/graphics/ecs/mesh-v2/MeshSkin.js";
-import { AnimationClips } from "../../../engine/graphics3/animation/AnimationClips.js";
-import { prefab_compile } from "../../../engine/graphics3/prefab/prefab_compile.js";
-import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.js";
-import { pose_evaluate_local } from "../../renderer/animation/pose/pose_evaluate_local.js";
-import { PosePlayback } from "../../renderer/animation/pose/PosePlayback.js";
-import { ShadeAnimationChannel } from "../../renderer/animation/ShadeAnimationChannel.js";
-import { ShadeAnimationClip } from "../../renderer/animation/ShadeAnimationClip.js";
-import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.js";
-import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
-import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
-import { create_frame_loop } from "../../renderer/create_frame_loop.js";
-import { make_sunlight } from "../../renderer/light/make_sunlight.js";
-import { place_light } from "../../renderer/light/place_light.js";
-import { load_gltf } from "../../renderer/loader/gltf/load_gltf.js";
-import { Node3DProperty } from "../../renderer/object_property/Node3DProperty.js";
-import { Renderer } from "../../renderer/Renderer.js";
-import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
-import { Scene } from "../../renderer/scene/Scene.js";
-import { load_default_environment } from "../load_default_environment.js";
-import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
-import { render_submitted_frames } from "../render_submitted_frames.js";
-import { add_floor } from "../skinned_blas_refit/add_floor.js";
-import { place_character } from "../skinned_blas_refit/place_character.js";
-
-const CHARACTER_URL = '/test_assets/Michelle.glb';
-const SPACING = 1.25;
-
-/**
- * Multiply two unit quaternions `a * b`.
- * @param {number[]} a
- * @param {number[]} b
- * @returns {number[]}
- */
-function quat_mul(a, b) {
-    return [
-        a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
-        a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
-        a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
-        a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
-    ];
-}
-
-/**
- * Axis-angle unit quaternion.
- * @param {number} ax
- * @param {number} ay
- * @param {number} az
- * @param {number} rad
- * @returns {number[]}
- */
-function quat_axis_angle(ax, ay, az, rad) {
-    const half = rad * 0.5;
-    const s = Math.sin(half);
-    return [ax * s, ay * s, az * s, Math.cos(half)];
-}
-
-/**
- * Build a looping 4-keyframe rotation channel that starts at `ref_q` (`t=0`), swings through
- * `ref_q * delta_a` (`t=0.5`) and `ref_q * delta_b` (`t=1.0`), and returns to `ref_q` (`t=1.5`).
- *
- * @param {number} target
- * @param {number[]} ref_q
- * @param {number[]} delta_a
- * @param {number[]} delta_b
- * @returns {ShadeAnimationChannel}
- */
-function make_wave_rotation_channel(target, ref_q, delta_a, delta_b) {
-    const q0 = ref_q;
-    const q1 = quat_mul(ref_q, delta_a);
-    const q2 = quat_mul(ref_q, delta_b);
-    const q3 = ref_q;
-    const times = [0.0, 0.5, 1.0, 1.5];
-    const qs = [q0, q1, q2, q3];
-
-    // Ensure consecutive hemisphere continuity
-    for (let i = 1; i < qs.length; i++) {
-        const prev = qs[i - 1];
-        const cur = qs[i];
-        if (prev[0] * cur[0] + prev[1] * cur[1] + prev[2] * cur[2] + prev[3] * cur[3] < 0) {
-            qs[i] = [-cur[0], -cur[1], -cur[2], -cur[3]];
-        }
-    }
-
-    return ShadeAnimationChannel.from({
-        target,
-        property: Node3DProperty.Rotation,
-        curves: {
-            x: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][0]))),
-            y: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][1]))),
-            z: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][2]))),
-            w: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][3]))),
-        },
-    });
-}
-
-/**
- * Author a full-body clip where all joints start at `base_clip`'s `t = start_time` reference pose,
- * lower-body joints remain static at that reference pose, and upper-body joints perform a clearly
- * visible wave + torso twist + head nod gesture. Then convert it via `ShadeAnimationClip.from_additive`.
- *
- * @param {import("../../renderer/loader/SceneBundle.js").SceneBundle} bundle
- * @param {ShadeAnimationClip} base_clip
- */
-function build_upper_body_additive_clip(bundle, base_clip) {
-    const ref_time = base_clip.start_time;
-    const nodes = bundle.nodes;
-
-    /** @type {Map<number, Transform64>} */
-    const ref_poses = new Map();
-    for (let i = 0; i < nodes.length; i++) {
-        const p = new Transform64();
-        p.copy(nodes[i].local);
-        ref_poses.set(i, p);
-    }
-    base_clip.apply(ref_time, idx => ref_poses.get(idx));
-
-    // Upper-body gesture definitions keyed by Mixamo joint suffix
-    const upper_gestures = new Map([
-        ['Spine1', [quat_axis_angle(0, 1, 0, 18 * DEG_TO_RAD), quat_axis_angle(0, 1, 0, -18 * DEG_TO_RAD)]],
-        ['Spine2', [quat_axis_angle(0, 0, 1, 14 * DEG_TO_RAD), quat_axis_angle(0, 0, 1, -14 * DEG_TO_RAD)]],
-        ['Neck', [quat_axis_angle(1, 0, 0, 16 * DEG_TO_RAD), quat_axis_angle(1, 0, 0, -12 * DEG_TO_RAD)]],
-        ['Head', [quat_axis_angle(0, 1, 0, 25 * DEG_TO_RAD), quat_axis_angle(0, 1, 0, -25 * DEG_TO_RAD)]],
-        ['RightArm', [quat_axis_angle(0, 0, 1, -55 * DEG_TO_RAD), quat_axis_angle(0, 0, 1, -35 * DEG_TO_RAD)]],
-        ['RightForeArm', [quat_axis_angle(1, 0, 1, 45 * DEG_TO_RAD), quat_axis_angle(1, 0, -1, -35 * DEG_TO_RAD)]],
-        ['LeftArm', [quat_axis_angle(0, 0, 1, 40 * DEG_TO_RAD), quat_axis_angle(0, 0, 1, 15 * DEG_TO_RAD)]],
-    ]);
-
-    const raw_channels = [];
-
-    for (let i = 0; i < nodes.length; i++) {
-        const name = nodes[i].name ?? '';
-        const ref_pose = ref_poses.get(i);
-        const ref_q = [ref_pose.rotation_x, ref_pose.rotation_y, ref_pose.rotation_z, ref_pose.rotation_w];
-
-        let matched = null;
-        for (const [suffix, deltas] of upper_gestures.entries()) {
-            if (name.endsWith(suffix)) {
-                matched = deltas;
-                break;
-            }
-        }
-
-        if (matched !== null) {
-            raw_channels.push(make_wave_rotation_channel(i, ref_q, matched[0], matched[1]));
-        } else if (/UpLeg|Leg|Foot|Hips/i.test(name)) {
-            // Static lower-body channel at the Samba reference pose (not rest pose) —
-            // `ShadeAnimationClip.from_additive` must strip these automatically!
-            raw_channels.push(
-                ShadeAnimationChannel.from({
-                    target: i,
-                    property: Node3DProperty.Rotation,
-                    curves: {
-                        x: AnimationCurve.from([Keyframe.from(0, ref_q[0]), Keyframe.from(1.5, ref_q[0])]),
-                        y: AnimationCurve.from([Keyframe.from(0, ref_q[1]), Keyframe.from(1.5, ref_q[1])]),
-                        z: AnimationCurve.from([Keyframe.from(0, ref_q[2]), Keyframe.from(1.5, ref_q[2])]),
-                        w: AnimationCurve.from([Keyframe.from(0, ref_q[3]), Keyframe.from(1.5, ref_q[3])]),
-                    },
-                })
-            );
-        }
-    }
-
-    const raw_clip = ShadeAnimationClip.from({
-        name: "UpperBodyWave_raw",
-        channels: raw_channels,
-    });
-
-    const additive_clip = ShadeAnimationClip.from_additive(raw_clip, {
-        reference_clip: base_clip,
-        reference_time: ref_time,
-        rest_of: idx => nodes[idx]?.local,
-        name: "UpperBodyWave_additive",
-    });
-
-    return {
-        raw_channel_count: raw_clip.channels.length,
-        additive_channel_count: additive_clip.channels.length,
-        stripped_channel_count: raw_clip.channels.length - additive_clip.channels.length,
-        additive_clip,
-    };
-}
-
-function skinned_meshes_of(dataset, instance) {
-    return Array.from(instance.mesh_entities).filter(entity => dataset.getComponent(entity, MeshSkin) !== undefined);
-}
-
-async function world_bounds_of(scene_context, entity) {
-    const row = row_of_entity(entity);
-    const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
-    const box = record.bounding_box;
-    const low = new Vector3(box[0], box[1], box[2]);
-    const high = new Vector3(box[3], box[4], box[5]);
-    return {
-        low,
-        high,
-        radius: Math.hypot(high.x - low.x, high.y - low.y, high.z - low.z) * 0.5,
-    };
-}
-
-export async function start() {
-    const element = id => document.getElementById(id);
-    const status_el = element('status');
-    const audit_el = element('audit');
-    const stats_el = element('stats');
-
-    function set_status(text, kind = '') {
-        status_el.textContent = text;
-        status_el.className = kind;
-    }
-
-    const canvas = element('view');
-    const context = canvas.getContext('webgpu');
-    if (context === null) {
-        set_status('no WebGPU context available', 'fail');
-        return;
-    }
-
-    const renderer = new Renderer();
-    renderer.feature_path_tracing_enabled = false;
-    renderer.feature_taa_enabled = true;
-
-    set_status('acquiring WebGPU device…');
-    await renderer.initialize({ context });
-
-    const camera = new PerspectiveCamera();
-    camera.near = 0.01;
-    camera.far = 200;
-    camera.fov = 45 * DEG_TO_RAD;
-    camera.aspect = renderer.aspect_ratio;
-
-    const scene = new Scene();
-    const dataset = new EntityComponentDataset();
-    scene.dataset = dataset;
-
-    const controller = new OrbitalCameraController(camera, document.body);
-    const scene_context = renderer.scenes.obtain(scene);
-    const animations = scene_context.animation_manager;
-
-    set_status(`loading ${CHARACTER_URL} & rebasing additive clip…`);
-
-    const asset_manager = await make_playground_asset_manager();
-    const bundle = await load_gltf(CHARACTER_URL, { assetManager: asset_manager });
-    const base_src_clip = bundle.clips.find(c => /samba|dance/i.test(c.name ?? '')) ?? bundle.clips[0];
-
-    const additive_info = build_upper_body_additive_clip(bundle, base_src_clip);
-    bundle.clips.push(additive_info.additive_clip);
-
-    const prefab = prefab_compile(bundle);
-
-    // Spawn 3 characters side by side:
-    //  0 (Left,   x = -SPACING): Base dance only (weight = 1)
-    //  1 (Center, x = 0):        Base dance (weight = base_w) + Additive upper-body (weight = add_w)
-    //  2 (Right,  x = +SPACING): Additive upper-body only (weight = add_w)
-    const placements = [
-        { label: 'Left (Base Only)', x: -SPACING },
-        { label: 'Center (Base + Additive)', x: 0 },
-        { label: 'Right (Additive Only)', x: SPACING },
-    ];
-
-    const characters = [];
-    const all_meshes = [];
-
-    for (let i = 0; i < placements.length; i++) {
-        const { root, instance } = place_character(scene_context, dataset, prefab, placements[i].x, 0);
-        const meshes = skinned_meshes_of(dataset, instance);
-        all_meshes.push(...meshes);
-
-        const clips = dataset.getComponent(root, AnimationClips).clips;
-        const base_clip = clips.find(c => c.name === base_src_clip.name) ?? clips[0];
-        const add_clip = clips.find(c => c.name === "UpperBodyWave_additive");
-
-        let base_id = null;
-        let add_id = null;
-
-        if (i === 0 || i === 1) {
-            base_id = animations.register_clip(base_clip);
-            animations.set_playback_weight(base_id, 1.0);
-            animations.set_flags(base_id, AnimationClipFlags.Loop);
-            animations.start(base_id);
-        }
-
-        if (i === 1 || i === 2) {
-            add_id = animations.register_clip(add_clip);
-            animations.set_playback_weight(add_id, 1.0);
-            animations.set_flags(add_id, AnimationClipFlags.Loop);
-            animations.start(add_id);
-        }
-
-        // Map joint short names to entities for live GPU vs CPU verification
-        const joints_by_name = new Map();
-        for (const ch of base_clip.channels) {
-            const name_comp = dataset.getComponent(ch.target, Name);
-            if (name_comp !== undefined) {
-                joints_by_name.set(name_comp.getValue(), ch.target);
-            }
-        }
-
-        characters.push({
-            label: placements[i].label,
-            root,
-            instance,
-            meshes,
-            base_clip,
-            add_clip,
-            base_id,
-            add_id,
-            joints_by_name,
-        });
-    }
-
-    place_light(scene, make_sunlight({ intensity: 6 }));
-
-    await render_submitted_frames(renderer, camera, scene, 8);
-
-    let low = null;
-    let high = null;
-    for (const mesh_entity of all_meshes) {
-        const bounds = await world_bounds_of(scene_context, mesh_entity);
-        low = low === null ? bounds.low : new Vector3(
-            Math.min(low.x, bounds.low.x), Math.min(low.y, bounds.low.y), Math.min(low.z, bounds.low.z)
-        );
-        high = high === null ? bounds.high : new Vector3(
-            Math.max(high.x, bounds.high.x), Math.max(high.y, bounds.high.y), Math.max(high.z, bounds.high.z)
-        );
-    }
-
-    const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
-    add_floor(scene_context, Math.max(span.x, span.z) * 4, low.y);
-
-    const radius = Math.hypot(span.x, span.y, span.z) * 0.48;
-    camera_frame_sphere(
-        controller,
-        radius,
-        new Vector3((low.x + high.x) / 2, (low.y + high.y) / 2, (low.z + high.z) / 2)
-    );
-    camera.near = radius * 0.01;
-    camera.far = radius * 400;
-
-    load_default_environment(scene).then(applied => {
-        if (applied) renderer.indicate_view_change();
-    });
-
-    let animating = true;
-    let base_weight = 1.0;
-    let additive_weight = 1.0;
-
-    function apply_weights() {
-        const center = characters[1];
-        const right = characters[2];
-        animations.set_playback_weight(center.base_id, base_weight);
-        animations.set_playback_weight(center.add_id, additive_weight);
-        animations.set_playback_weight(right.add_id, additive_weight);
-        renderer.path_tracer.clear_history = true;
-        renderer.indicate_view_change();
-    }
-
-    const slider_add = element('slider_additive_weight');
-    const val_add = element('val_additive_weight');
-    const slider_base = element('slider_base_weight');
-    const val_base = element('val_base_weight');
-
-    slider_add.addEventListener('input', () => {
-        additive_weight = Number.parseFloat(slider_add.value);
-        val_add.textContent = additive_weight.toFixed(2);
-        apply_weights();
-    });
-
-    slider_base.addEventListener('input', () => {
-        base_weight = Number.parseFloat(slider_base.value);
-        val_base.textContent = base_weight.toFixed(2);
-        apply_weights();
-    });
-
-    document.querySelectorAll('.preset').forEach(btn => {
-        btn.addEventListener('click', () => {
-            document.querySelectorAll('.preset').forEach(b => b.classList.remove('active'));
-            btn.classList.add('active');
-            base_weight = Number.parseFloat(btn.dataset.base);
-            additive_weight = Number.parseFloat(btn.dataset.add);
-            slider_base.value = String(base_weight);
-            slider_add.value = String(additive_weight);
-            val_base.textContent = base_weight.toFixed(2);
-            val_add.textContent = additive_weight.toFixed(2);
-            apply_weights();
-        });
-    });
-
-    const toggle_btn = element('toggle_animation');
-    toggle_btn.addEventListener('click', () => {
-        animating = !animating;
-        toggle_btn.textContent = animating ? 'Freeze pose' : 'Resume dance';
-    });
-
-    const pt_checkbox = element('path_tracing');
-    pt_checkbox.addEventListener('change', () => {
-        renderer.feature_path_tracing_enabled = pt_checkbox.checked;
-        renderer.feature_taa_enabled = !pt_checkbox.checked;
-        renderer.path_tracer.clear_history = true;
-        renderer.indicate_view_change();
-    });
-
-    /**
-     * Read back GPU transform rows for Left, Center, and Right characters at deterministic clip times
-     * and verify:
-     *  1. Static lower-body channels were stripped by `ShadeAnimationClip.from_additive`.
-     *  2. Center dancer's lower-body joint (`LeftUpLeg`) matches Left dancer's GPU row.
-     *  3. Center dancer's upper-body joint (`RightArm`) matches the CPU `pose_evaluate_local` twin
-     *     and diverges from Left dancer when `additive_weight > 0`.
-     */
-    async function verify_additive({ sample_base_time = 0.6, sample_add_time = 0.5 } = {}) {
-        const was_animating = animating;
-        animating = false;
-
-        try {
-            const [left, center, right] = characters;
-            animations.set_time(left.base_id, sample_base_time);
-            animations.set_time(center.base_id, sample_base_time);
-            animations.set_time(center.add_id, sample_add_time);
-            animations.set_time(right.add_id, sample_add_time);
-
-            await render_submitted_frames(renderer, camera, scene, 2, 0);
-
-            const find_joint = (char, suffix) => {
-                for (const [name, entity] of char.joints_by_name.entries()) {
-                    if (name.endsWith(suffix)) return entity;
-                }
-                return null;
-            };
-
-            const left_leg = find_joint(left, 'LeftUpLeg');
-            const center_leg = find_joint(center, 'LeftUpLeg');
-            const left_arm = find_joint(left, 'RightArm');
-            const center_arm = find_joint(center, 'RightArm');
-            const right_arm = find_joint(right, 'RightArm');
-
-            const transforms_table = scene_context.scene_database.get('transforms');
-            const read_gpu_rot = async entity => {
-                const rec = await scene_context.scene_database.debug_table_read_element('transforms', row_of_entity(entity));
-                return Array.from(rec.local_rotation);
-            };
-
-            const gpu_left_leg = await read_gpu_rot(left_leg);
-            const gpu_center_leg = await read_gpu_rot(center_leg);
-            const gpu_left_arm = await read_gpu_rot(left_arm);
-            const gpu_center_arm = await read_gpu_rot(center_arm);
-            const gpu_right_arm = await read_gpu_rot(right_arm);
-
-            // CPU twin evaluation on Center dancer's RightArm
-            const center_arm_rest = dataset.getComponent(center_arm, TransformAttachment).transform;
-            const cpu_center_arm = pose_evaluate_local(new Transform64(), center_arm, center_arm_rest, [
-                PosePlayback.from(center.base_clip, sample_base_time, base_weight),
-                PosePlayback.from(center.add_clip, sample_add_time, additive_weight),
-            ]);
-
-            const quat_dot = (a, b) => Math.abs(a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3]);
-            const leg_match_dot = quat_dot(gpu_left_leg, gpu_center_leg);
-            const gpu_cpu_arm_dot = quat_dot(gpu_center_arm, [
-                cpu_center_arm.rotation_x,
-                cpu_center_arm.rotation_y,
-                cpu_center_arm.rotation_z,
-                cpu_center_arm.rotation_w,
-            ]);
-            const arm_delta_deg = Math.acos(Math.min(1, quat_dot(gpu_left_arm, gpu_center_arm))) * 2 * (180 / Math.PI);
-
-            const report = {
-                stripped_lower_channels: additive_info.stripped_channel_count,
-                surviving_upper_channels: additive_info.additive_channel_count,
-                leg_match_dot,
-                gpu_cpu_arm_dot,
-                arm_delta_deg,
-                gpu_center_arm,
-                gpu_right_arm,
-                pass: additive_info.stripped_channel_count > 0 && gpu_cpu_arm_dot > 0.9999,
-            };
-
-            audit_el.textContent =
-                `stripped static channels: ${report.stripped_lower_channels} (kept ${report.surviving_upper_channels} upper)\n` +
-                `GPU vs CPU twin dot (RightArm): ${report.gpu_cpu_arm_dot.toFixed(6)}\n` +
-                `Lower-body (LeftUpLeg) dot:     ${report.leg_match_dot.toFixed(6)}\n` +
-                `Upper-body additive deflection: ${report.arm_delta_deg.toFixed(1)}°`;
-
-            set_status(
-                report.pass
-                    ? `PASS — GPU & CPU twin match (${report.arm_delta_deg.toFixed(1)}° upper-body additive offset)`
-                    : `FAIL — GPU/CPU mismatch`,
-                report.pass ? 'pass' : 'fail'
-            );
-
-            return report;
-        } finally {
-            animating = was_animating;
-        }
-    }
-
-    element('run_verify').addEventListener('click', () => {
-        verify_additive().catch(console.error);
-    });
-
-    globalThis.renderer = renderer;
-    globalThis.scene = scene;
-    globalThis.camera = camera;
-    globalThis.characters = characters;
-    globalThis.verify_additive = verify_additive;
-
-    await verify_additive();
-
-    create_frame_loop((time_delta_s, raf_time_s) => {
-        const width = window.innerWidth;
-        const height = window.innerHeight;
-        renderer.resize(width, height);
-        renderer.pixel_ratio = window.devicePixelRatio;
-        camera.aspect = width / height;
-
-        controller.update();
-        renderer.render(camera, scene, animating ? time_delta_s : 0);
-
-        const fps = raf_time_s > 0 ? (1 / raf_time_s).toFixed(0) : '--';
-        stats_el.textContent = `${(raf_time_s * 1000).toFixed(1)} ms · ${fps} fps · base=${base_weight.toFixed(2)} add=${additive_weight.toFixed(2)}`;
-    }, 60);
-}
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { AnimationCurve } from "../../../engine/animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../../engine/animation/curve/Keyframe.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { Name } from "../../../engine/ecs/name/Name.js";
+import { TransformAttachment } from "../../../engine/ecs/transform-attachment/TransformAttachment.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { MeshSkin } from "../../../engine/graphics/ecs/mesh-v2/MeshSkin.js";
+import { AnimationClips } from "../../../engine/graphics3/animation/AnimationClips.js";
+import { prefab_compile } from "../../../engine/graphics3/prefab/prefab_compile.js";
+import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.js";
+import { pose_evaluate_local } from "../../renderer/animation/pose/pose_evaluate_local.js";
+import { PosePlayback } from "../../renderer/animation/pose/PosePlayback.js";
+import { ShadeAnimationChannel } from "../../renderer/animation/ShadeAnimationChannel.js";
+import { ShadeAnimationClip } from "../../renderer/animation/ShadeAnimationClip.js";
+import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.js";
+import { OrbitalCameraController } from "../../renderer/camera/orbital/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { load_gltf } from "../../renderer/loader/gltf/load_gltf.js";
+import { Node3DProperty } from "../../renderer/object_property/Node3DProperty.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
+import { render_submitted_frames } from "../render_submitted_frames.js";
+import { add_floor } from "../skinned_blas_refit/add_floor.js";
+import { place_character } from "../skinned_blas_refit/place_character.js";
+
+const CHARACTER_URL = '/test_assets/Michelle.glb';
+const SPACING = 1.25;
+
+/**
+ * Multiply two unit quaternions `a * b`.
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number[]}
+ */
+function quat_mul(a, b) {
+    return [
+        a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+        a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+        a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+        a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+    ];
+}
+
+/**
+ * Axis-angle unit quaternion.
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} rad
+ * @returns {number[]}
+ */
+function quat_axis_angle(ax, ay, az, rad) {
+    const half = rad * 0.5;
+    const s = Math.sin(half);
+    return [ax * s, ay * s, az * s, Math.cos(half)];
+}
+
+/**
+ * Build a looping 4-keyframe rotation channel that starts at `ref_q` (`t=0`), swings through
+ * `ref_q * delta_a` (`t=0.5`) and `ref_q * delta_b` (`t=1.0`), and returns to `ref_q` (`t=1.5`).
+ *
+ * @param {number} target
+ * @param {number[]} ref_q
+ * @param {number[]} delta_a
+ * @param {number[]} delta_b
+ * @returns {ShadeAnimationChannel}
+ */
+function make_wave_rotation_channel(target, ref_q, delta_a, delta_b) {
+    const q0 = ref_q;
+    const q1 = quat_mul(ref_q, delta_a);
+    const q2 = quat_mul(ref_q, delta_b);
+    const q3 = ref_q;
+    const times = [0.0, 0.5, 1.0, 1.5];
+    const qs = [q0, q1, q2, q3];
+
+    // Ensure consecutive hemisphere continuity
+    for (let i = 1; i < qs.length; i++) {
+        const prev = qs[i - 1];
+        const cur = qs[i];
+        if (prev[0] * cur[0] + prev[1] * cur[1] + prev[2] * cur[2] + prev[3] * cur[3] < 0) {
+            qs[i] = [-cur[0], -cur[1], -cur[2], -cur[3]];
+        }
+    }
+
+    return ShadeAnimationChannel.from({
+        target,
+        property: Node3DProperty.Rotation,
+        curves: {
+            x: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][0]))),
+            y: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][1]))),
+            z: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][2]))),
+            w: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][3]))),
+        },
+    });
+}
+
+/**
+ * Author a full-body clip where all joints start at `base_clip`'s `t = start_time` reference pose,
+ * lower-body joints remain static at that reference pose, and upper-body joints perform a clearly
+ * visible wave + torso twist + head nod gesture. Then convert it via `ShadeAnimationClip.from_additive`.
+ *
+ * @param {import("../../renderer/loader/SceneBundle.js").SceneBundle} bundle
+ * @param {ShadeAnimationClip} base_clip
+ */
+function build_upper_body_additive_clip(bundle, base_clip) {
+    const ref_time = base_clip.start_time;
+    const nodes = bundle.nodes;
+
+    /** @type {Map<number, Transform64>} */
+    const ref_poses = new Map();
+    for (let i = 0; i < nodes.length; i++) {
+        const p = new Transform64();
+        p.copy(nodes[i].local);
+        ref_poses.set(i, p);
+    }
+    base_clip.apply(ref_time, idx => ref_poses.get(idx));
+
+    // Upper-body gesture definitions keyed by Mixamo joint suffix
+    const upper_gestures = new Map([
+        ['Spine1', [quat_axis_angle(0, 1, 0, 18 * DEG_TO_RAD), quat_axis_angle(0, 1, 0, -18 * DEG_TO_RAD)]],
+        ['Spine2', [quat_axis_angle(0, 0, 1, 14 * DEG_TO_RAD), quat_axis_angle(0, 0, 1, -14 * DEG_TO_RAD)]],
+        ['Neck', [quat_axis_angle(1, 0, 0, 16 * DEG_TO_RAD), quat_axis_angle(1, 0, 0, -12 * DEG_TO_RAD)]],
+        ['Head', [quat_axis_angle(0, 1, 0, 25 * DEG_TO_RAD), quat_axis_angle(0, 1, 0, -25 * DEG_TO_RAD)]],
+        ['RightArm', [quat_axis_angle(0, 0, 1, -55 * DEG_TO_RAD), quat_axis_angle(0, 0, 1, -35 * DEG_TO_RAD)]],
+        ['RightForeArm', [quat_axis_angle(1, 0, 1, 45 * DEG_TO_RAD), quat_axis_angle(1, 0, -1, -35 * DEG_TO_RAD)]],
+        ['LeftArm', [quat_axis_angle(0, 0, 1, 40 * DEG_TO_RAD), quat_axis_angle(0, 0, 1, 15 * DEG_TO_RAD)]],
+    ]);
+
+    const raw_channels = [];
+
+    for (let i = 0; i < nodes.length; i++) {
+        const name = nodes[i].name ?? '';
+        const ref_pose = ref_poses.get(i);
+        const ref_q = [ref_pose.rotation_x, ref_pose.rotation_y, ref_pose.rotation_z, ref_pose.rotation_w];
+
+        let matched = null;
+        for (const [suffix, deltas] of upper_gestures.entries()) {
+            if (name.endsWith(suffix)) {
+                matched = deltas;
+                break;
+            }
+        }
+
+        if (matched !== null) {
+            raw_channels.push(make_wave_rotation_channel(i, ref_q, matched[0], matched[1]));
+        } else if (/UpLeg|Leg|Foot|Hips/i.test(name)) {
+            // Static lower-body channel at the Samba reference pose (not rest pose) —
+            // `ShadeAnimationClip.from_additive` must strip these automatically!
+            raw_channels.push(
+                ShadeAnimationChannel.from({
+                    target: i,
+                    property: Node3DProperty.Rotation,
+                    curves: {
+                        x: AnimationCurve.from([Keyframe.from(0, ref_q[0]), Keyframe.from(1.5, ref_q[0])]),
+                        y: AnimationCurve.from([Keyframe.from(0, ref_q[1]), Keyframe.from(1.5, ref_q[1])]),
+                        z: AnimationCurve.from([Keyframe.from(0, ref_q[2]), Keyframe.from(1.5, ref_q[2])]),
+                        w: AnimationCurve.from([Keyframe.from(0, ref_q[3]), Keyframe.from(1.5, ref_q[3])]),
+                    },
+                })
+            );
+        }
+    }
+
+    const raw_clip = ShadeAnimationClip.from({
+        name: "UpperBodyWave_raw",
+        channels: raw_channels,
+    });
+
+    const additive_clip = ShadeAnimationClip.from_additive(raw_clip, {
+        reference_clip: base_clip,
+        reference_time: ref_time,
+        rest_of: idx => nodes[idx]?.local,
+        name: "UpperBodyWave_additive",
+    });
+
+    return {
+        raw_channel_count: raw_clip.channels.length,
+        additive_channel_count: additive_clip.channels.length,
+        stripped_channel_count: raw_clip.channels.length - additive_clip.channels.length,
+        additive_clip,
+    };
+}
+
+function skinned_meshes_of(dataset, instance) {
+    return Array.from(instance.mesh_entities).filter(entity => dataset.getComponent(entity, MeshSkin) !== undefined);
+}
+
+async function world_bounds_of(scene_context, entity) {
+    const row = row_of_entity(entity);
+    const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
+    const box = record.bounding_box;
+    const low = new Vector3(box[0], box[1], box[2]);
+    const high = new Vector3(box[3], box[4], box[5]);
+    return {
+        low,
+        high,
+        radius: Math.hypot(high.x - low.x, high.y - low.y, high.z - low.z) * 0.5,
+    };
+}
+
+export async function start() {
+    const element = id => document.getElementById(id);
+    const status_el = element('status');
+    const audit_el = element('audit');
+    const stats_el = element('stats');
+
+    function set_status(text, kind = '') {
+        status_el.textContent = text;
+        status_el.className = kind;
+    }
+
+    const canvas = element('view');
+    const context = canvas.getContext('webgpu');
+    if (context === null) {
+        set_status('no WebGPU context available', 'fail');
+        return;
+    }
+
+    const renderer = new Renderer();
+    renderer.feature_path_tracing_enabled = false;
+    renderer.feature_taa_enabled = true;
+
+    set_status('acquiring WebGPU device…');
+    await renderer.initialize({ context });
+
+    const camera = new PerspectiveCamera();
+    camera.near = 0.01;
+    camera.far = 200;
+    camera.fov = 45 * DEG_TO_RAD;
+    camera.aspect = renderer.aspect_ratio;
+
+    const scene = new Scene();
+    const dataset = new EntityComponentDataset();
+    scene.dataset = dataset;
+
+    const controller = new OrbitalCameraController(camera, document.body);
+    const scene_context = renderer.scenes.obtain(scene);
+    const animations = scene_context.animation_manager;
+
+    set_status(`loading ${CHARACTER_URL} & rebasing additive clip…`);
+
+    const asset_manager = await make_playground_asset_manager();
+    const bundle = await load_gltf(CHARACTER_URL, { assetManager: asset_manager });
+    const base_src_clip = bundle.clips.find(c => /samba|dance/i.test(c.name ?? '')) ?? bundle.clips[0];
+
+    const additive_info = build_upper_body_additive_clip(bundle, base_src_clip);
+    bundle.clips.push(additive_info.additive_clip);
+
+    const prefab = prefab_compile(bundle);
+
+    // Spawn 3 characters side by side:
+    //  0 (Left,   x = -SPACING): Base dance only (weight = 1)
+    //  1 (Center, x = 0):        Base dance (weight = base_w) + Additive upper-body (weight = add_w)
+    //  2 (Right,  x = +SPACING): Additive upper-body only (weight = add_w)
+    const placements = [
+        { label: 'Left (Base Only)', x: -SPACING },
+        { label: 'Center (Base + Additive)', x: 0 },
+        { label: 'Right (Additive Only)', x: SPACING },
+    ];
+
+    const characters = [];
+    const all_meshes = [];
+
+    for (let i = 0; i < placements.length; i++) {
+        const { root, instance } = place_character(scene_context, dataset, prefab, placements[i].x, 0);
+        const meshes = skinned_meshes_of(dataset, instance);
+        all_meshes.push(...meshes);
+
+        const clips = dataset.getComponent(root, AnimationClips).clips;
+        const base_clip = clips.find(c => c.name === base_src_clip.name) ?? clips[0];
+        const add_clip = clips.find(c => c.name === "UpperBodyWave_additive");
+
+        let base_id = null;
+        let add_id = null;
+
+        if (i === 0 || i === 1) {
+            base_id = animations.register_clip(base_clip);
+            animations.set_playback_weight(base_id, 1.0);
+            animations.set_flags(base_id, AnimationClipFlags.Loop);
+            animations.start(base_id);
+        }
+
+        if (i === 1 || i === 2) {
+            add_id = animations.register_clip(add_clip);
+            animations.set_playback_weight(add_id, 1.0);
+            animations.set_flags(add_id, AnimationClipFlags.Loop);
+            animations.start(add_id);
+        }
+
+        // Map joint short names to entities for live GPU vs CPU verification
+        const joints_by_name = new Map();
+        for (const ch of base_clip.channels) {
+            const name_comp = dataset.getComponent(ch.target, Name);
+            if (name_comp !== undefined) {
+                joints_by_name.set(name_comp.getValue(), ch.target);
+            }
+        }
+
+        characters.push({
+            label: placements[i].label,
+            root,
+            instance,
+            meshes,
+            base_clip,
+            add_clip,
+            base_id,
+            add_id,
+            joints_by_name,
+        });
+    }
+
+    place_light(scene, make_sunlight({ intensity: 6 }));
+
+    await render_submitted_frames(renderer, camera, scene, 8);
+
+    let low = null;
+    let high = null;
+    for (const mesh_entity of all_meshes) {
+        const bounds = await world_bounds_of(scene_context, mesh_entity);
+        low = low === null ? bounds.low : new Vector3(
+            Math.min(low.x, bounds.low.x), Math.min(low.y, bounds.low.y), Math.min(low.z, bounds.low.z)
+        );
+        high = high === null ? bounds.high : new Vector3(
+            Math.max(high.x, bounds.high.x), Math.max(high.y, bounds.high.y), Math.max(high.z, bounds.high.z)
+        );
+    }
+
+    const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
+    add_floor(scene_context, Math.max(span.x, span.z) * 4, low.y);
+
+    const radius = Math.hypot(span.x, span.y, span.z) * 0.48;
+    camera_frame_sphere(
+        controller,
+        radius,
+        new Vector3((low.x + high.x) / 2, (low.y + high.y) / 2, (low.z + high.z) / 2)
+    );
+    camera.near = radius * 0.01;
+    camera.far = radius * 400;
+
+    load_default_environment(scene).then(applied => {
+        if (applied) renderer.indicate_view_change();
+    });
+
+    let animating = true;
+    let base_weight = 1.0;
+    let additive_weight = 1.0;
+
+    function apply_weights() {
+        const center = characters[1];
+        const right = characters[2];
+        animations.set_playback_weight(center.base_id, base_weight);
+        animations.set_playback_weight(center.add_id, additive_weight);
+        animations.set_playback_weight(right.add_id, additive_weight);
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+    }
+
+    const slider_add = element('slider_additive_weight');
+    const val_add = element('val_additive_weight');
+    const slider_base = element('slider_base_weight');
+    const val_base = element('val_base_weight');
+
+    slider_add.addEventListener('input', () => {
+        additive_weight = Number.parseFloat(slider_add.value);
+        val_add.textContent = additive_weight.toFixed(2);
+        apply_weights();
+    });
+
+    slider_base.addEventListener('input', () => {
+        base_weight = Number.parseFloat(slider_base.value);
+        val_base.textContent = base_weight.toFixed(2);
+        apply_weights();
+    });
+
+    document.querySelectorAll('.preset').forEach(btn => {
+        btn.addEventListener('click', () => {
+            document.querySelectorAll('.preset').forEach(b => b.classList.remove('active'));
+            btn.classList.add('active');
+            base_weight = Number.parseFloat(btn.dataset.base);
+            additive_weight = Number.parseFloat(btn.dataset.add);
+            slider_base.value = String(base_weight);
+            slider_add.value = String(additive_weight);
+            val_base.textContent = base_weight.toFixed(2);
+            val_add.textContent = additive_weight.toFixed(2);
+            apply_weights();
+        });
+    });
+
+    const toggle_btn = element('toggle_animation');
+    toggle_btn.addEventListener('click', () => {
+        animating = !animating;
+        toggle_btn.textContent = animating ? 'Freeze pose' : 'Resume dance';
+    });
+
+    const pt_checkbox = element('path_tracing');
+    pt_checkbox.addEventListener('change', () => {
+        renderer.feature_path_tracing_enabled = pt_checkbox.checked;
+        renderer.feature_taa_enabled = !pt_checkbox.checked;
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+    });
+
+    /**
+     * Read back GPU transform rows for Left, Center, and Right characters at deterministic clip times
+     * and verify:
+     *  1. Static lower-body channels were stripped by `ShadeAnimationClip.from_additive`.
+     *  2. Center dancer's lower-body joint (`LeftUpLeg`) matches Left dancer's GPU row.
+     *  3. Center dancer's upper-body joint (`RightArm`) matches the CPU `pose_evaluate_local` twin
+     *     and diverges from Left dancer when `additive_weight > 0`.
+     */
+    async function verify_additive({ sample_base_time = 0.6, sample_add_time = 0.5 } = {}) {
+        const was_animating = animating;
+        animating = false;
+
+        try {
+            const [left, center, right] = characters;
+            animations.set_time(left.base_id, sample_base_time);
+            animations.set_time(center.base_id, sample_base_time);
+            animations.set_time(center.add_id, sample_add_time);
+            animations.set_time(right.add_id, sample_add_time);
+
+            await render_submitted_frames(renderer, camera, scene, 2, 0);
+
+            const find_joint = (char, suffix) => {
+                for (const [name, entity] of char.joints_by_name.entries()) {
+                    if (name.endsWith(suffix)) return entity;
+                }
+                return null;
+            };
+
+            const left_leg = find_joint(left, 'LeftUpLeg');
+            const center_leg = find_joint(center, 'LeftUpLeg');
+            const left_arm = find_joint(left, 'RightArm');
+            const center_arm = find_joint(center, 'RightArm');
+            const right_arm = find_joint(right, 'RightArm');
+
+            const transforms_table = scene_context.scene_database.get('transforms');
+            const read_gpu_rot = async entity => {
+                const rec = await scene_context.scene_database.debug_table_read_element('transforms', row_of_entity(entity));
+                return Array.from(rec.local_rotation);
+            };
+
+            const gpu_left_leg = await read_gpu_rot(left_leg);
+            const gpu_center_leg = await read_gpu_rot(center_leg);
+            const gpu_left_arm = await read_gpu_rot(left_arm);
+            const gpu_center_arm = await read_gpu_rot(center_arm);
+            const gpu_right_arm = await read_gpu_rot(right_arm);
+
+            // CPU twin evaluation on Center dancer's RightArm
+            const center_arm_rest = dataset.getComponent(center_arm, TransformAttachment).transform;
+            const cpu_center_arm = pose_evaluate_local(new Transform64(), center_arm, center_arm_rest, [
+                PosePlayback.from(center.base_clip, sample_base_time, base_weight),
+                PosePlayback.from(center.add_clip, sample_add_time, additive_weight),
+            ]);
+
+            const quat_dot = (a, b) => Math.abs(a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3]);
+            const leg_match_dot = quat_dot(gpu_left_leg, gpu_center_leg);
+            const gpu_cpu_arm_dot = quat_dot(gpu_center_arm, [
+                cpu_center_arm.rotation_x,
+                cpu_center_arm.rotation_y,
+                cpu_center_arm.rotation_z,
+                cpu_center_arm.rotation_w,
+            ]);
+            const arm_delta_deg = Math.acos(Math.min(1, quat_dot(gpu_left_arm, gpu_center_arm))) * 2 * (180 / Math.PI);
+
+            const report = {
+                stripped_lower_channels: additive_info.stripped_channel_count,
+                surviving_upper_channels: additive_info.additive_channel_count,
+                leg_match_dot,
+                gpu_cpu_arm_dot,
+                arm_delta_deg,
+                gpu_center_arm,
+                gpu_right_arm,
+                pass: additive_info.stripped_channel_count > 0 && gpu_cpu_arm_dot > 0.9999,
+            };
+
+            audit_el.textContent =
+                `stripped static channels: ${report.stripped_lower_channels} (kept ${report.surviving_upper_channels} upper)\n` +
+                `GPU vs CPU twin dot (RightArm): ${report.gpu_cpu_arm_dot.toFixed(6)}\n` +
+                `Lower-body (LeftUpLeg) dot:     ${report.leg_match_dot.toFixed(6)}\n` +
+                `Upper-body additive deflection: ${report.arm_delta_deg.toFixed(1)}°`;
+
+            set_status(
+                report.pass
+                    ? `PASS — GPU & CPU twin match (${report.arm_delta_deg.toFixed(1)}° upper-body additive offset)`
+                    : `FAIL — GPU/CPU mismatch`,
+                report.pass ? 'pass' : 'fail'
+            );
+
+            return report;
+        } finally {
+            animating = was_animating;
+        }
+    }
+
+    element('run_verify').addEventListener('click', () => {
+        verify_additive().catch(console.error);
+    });
+
+    globalThis.renderer = renderer;
+    globalThis.scene = scene;
+    globalThis.camera = camera;
+    globalThis.characters = characters;
+    globalThis.verify_additive = verify_additive;
+
+    await verify_additive();
+
+    create_frame_loop((time_delta_s, raf_time_s) => {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+        renderer.resize(width, height);
+        renderer.pixel_ratio = window.devicePixelRatio;
+        camera.aspect = width / height;
+
+        controller.update();
+        renderer.render(camera, scene, animating ? time_delta_s : 0);
+
+        const fps = raf_time_s > 0 ? (1 / raf_time_s).toFixed(0) : '--';
+        stats_el.textContent = `${(raf_time_s * 1000).toFixed(1)} ms · ${fps} fps · base=${base_weight.toFixed(2)} add=${additive_weight.toFixed(2)}`;
+    }, 60);
+}