@convai/embody 1.0.1-beta.0 → 1.1.0-beta.0

package/dist/clips/retarget.js

@@ -0,0 +1,856 @@
+/**
+ * Load-time retargeting: a clip authored on another skeleton (Mixamo, the
+ * Unreal mannequin, Rigify) → a clip on the body's own skeleton.
+ *
+ * Ported from the coffee-shop studio's camera-tuned retargeter and
+ * generalised: every rig is read through one table of canonical joints
+ * (Mixamo's names), so neither side's bone names are hard-coded into the
+ * method. The posture constants are the ones tuned on convai-mha-1 bodies.
+ *
+ * Method, per sampled frame:
+ *  1. Both rigs are put in one canonical frame (left +X, up +Y, forward +Z),
+ *     measured from their own hip line and the file's vertical.
+ *  2. Rest-pose fix: Mixamo rests in a T-pose, a MetaHuman binds in an
+ *     A-pose. Each target bone gets the shortest-arc rotation that lays its
+ *     rest direction (bone → mapped child) onto the source's. Feet are left
+ *     flat, the neck and head keep their own build, and a clavicle built
+ *     pointing back (Rigify) contributes only its elevation.
+ *  3. Each mapped bone takes the source bone's WORLD rotation change since
+ *     rest; unmapped bones (twists, correctives, extra spine) keep their
+ *     bind-pose local rotation.
+ *  4. The hips move by the source hips' offset, scaled by hip height.
+ *  5. Elbows and hands are kept outside the body's own torso and thighs,
+ *     measured from its skinned vertices (a clip made for a slimmer body
+ *     otherwise rests its hands inside this one).
+ *
+ * The top bone (`pelvis` on convai-mha-1) has a parent outside the skin
+ * (`root002`). It is solved against that parent's bind-frame transform,
+ * `bindMatrix · meshWorld⁻¹ · parent.matrixWorld`; solving it from skin bones
+ * alone writes a constant pelvis and breaks every clip that bends at the hips.
+ */
+import * as THREE from 'three';
+// ── canonical joints and the rigs that are read ─────────────────────────────
+const SIDES = [['Left', 'l', 'L'], ['Right', 'r', 'R']];
+const FINGERS = [['Thumb', 'thumb', 'thumb'], ['Index', 'index', 'f_index'], ['Middle', 'middle', 'f_middle'], ['Ring', 'ring', 'f_ring'], ['Pinky', 'pinky', 'f_pinky']];
+/** Every canonical joint: Mixamo's bone names without the `mixamorig:` prefix. */
+const CANON = new Set(['Hips', 'Spine', 'Spine1', 'Spine2', 'Neck', 'Head']);
+for (const [s] of SIDES) {
+    for (const j of ['Shoulder', 'Arm', 'ForeArm', 'Hand', 'UpLeg', 'Leg', 'Foot', 'ToeBase'])
+        CANON.add(`${s}${j}`);
+    for (const [f] of FINGERS)
+        for (const i of [1, 2, 3])
+            CANON.add(`${s}Hand${f}${i}`);
+}
+/** Which canonical child gives a joint its direction, for the rest-pose fix. */
+const AIM = { Spine: 'Spine1', Spine1: 'Spine2', Spine2: 'Neck', Neck: 'Head' };
+for (const [s] of SIDES) {
+    Object.assign(AIM, {
+        [`${s}Shoulder`]: `${s}Arm`,
+        [`${s}Arm`]: `${s}ForeArm`,
+        [`${s}ForeArm`]: `${s}Hand`,
+        [`${s}Hand`]: `${s}HandMiddle1`,
+        [`${s}UpLeg`]: `${s}Leg`,
+        [`${s}Leg`]: `${s}Foot`,
+    });
+    for (const [f] of FINGERS) {
+        AIM[`${s}Hand${f}1`] = `${s}Hand${f}2`;
+        AIM[`${s}Hand${f}2`] = `${s}Hand${f}3`;
+    }
+}
+/**
+ * Joints whose rest pose already matches (every rig stands flat-footed), so
+ * they take no rest fix. Aligning ankle→toe directions instead pitches the
+ * foot by the difference in the two rigs' ankle heights, and the toes dip
+ * into the floor.
+ */
+const FLAT = new Set(['LeftFoot', 'RightFoot', 'LeftToeBase', 'RightToeBase']);
+/**
+ * Joints whose rest direction differs between rigs by build, not by pose:
+ * every rig rests with the head upright, but where the neck starts and how
+ * far it leans is anatomy. Copying the source's neck direction pushed the
+ * head 10–50° forward of the shoulders. They take the source's rotation
+ * change only, on the body's own bind shape.
+ */
+const OWN_SHAPE = new Set(['Neck', 'Head']);
+/**
+ * Clavicles resting more than this far forward or back of sideways are built
+ * that way (Rigify's start at the sternum and point 30–45° back), not posed:
+ * the source's rest then counts as sideways at its own elevation. Mixamo's
+ * (within ~15°) are taken as they are.
+ */
+const CLAVICLE_BUILD_DEG = 20;
+const ELEVATION_ONLY = new Set(['LeftShoulder', 'RightShoulder']);
+/** The joints a source must have to be read at all. */
+const REQUIRED = ['Hips', 'LeftUpLeg', 'RightUpLeg', 'LeftFoot', 'RightFoot'];
+const stripMixamo = (n) => n.replace(/^mixamorig\d*:?/, '');
+// GLTFLoader and FBXLoader drop '.' and ':' from node names
+// (DEF-thigh.L → DEF-thighL, mixamorig:Hips → mixamorigHips): compare without them.
+const key = (n) => n.replace(/[.:]/g, '');
+/**
+ * Reads a skeleton's bone names as canonical joints: Mixamo (any
+ * `mixamorig` prefix, or none), Unreal (UE4/UE5 mannequin, MetaHuman,
+ * convai-mha-1) and Rigify deform bones. Spines are matched bottom, middle,
+ * top: a 3-bone spine maps 1/2/3, a 5-bone one 1/3/5. `null` when the hips,
+ * thighs and feet cannot all be found.
+ */
+export function readRigNames(names) {
+    const has = new Set(names.map(key));
+    const alias = {};
+    let kind = 'mixamo';
+    if (has.has('pelvis') && has.has('thigh_l')) {
+        kind = 'unreal';
+        const five = has.has('spine_05');
+        Object.assign(alias, { pelvis: 'Hips', spine_01: 'Spine', [five ? 'spine_03' : 'spine_02']: 'Spine1', [five ? 'spine_05' : 'spine_03']: 'Spine2', neck_01: 'Neck', head: 'Head' });
+        for (const [s, t] of SIDES) {
+            Object.assign(alias, {
+                [`clavicle_${t}`]: `${s}Shoulder`,
+                [`upperarm_${t}`]: `${s}Arm`,
+                [`lowerarm_${t}`]: `${s}ForeArm`,
+                [`hand_${t}`]: `${s}Hand`,
+                [`thigh_${t}`]: `${s}UpLeg`,
+                [`calf_${t}`]: `${s}Leg`,
+                [`foot_${t}`]: `${s}Foot`,
+                [`ball_${t}`]: `${s}ToeBase`,
+            });
+            for (const [f, uf] of FINGERS)
+                for (const i of [1, 2, 3])
+                    alias[`${uf}_0${i}_${t}`] = `${s}Hand${f}${i}`;
+        }
+    }
+    else if (has.has('DEF-hips') || has.has('DEF-spine001')) {
+        // Rigify deform bones (Quaternius' Universal Animation Library uses this rig).
+        kind = 'rigify';
+        const sp = (i) => `DEF-spine.${String(i).padStart(3, '0')}`;
+        Object.assign(alias, has.has('DEF-hips')
+            ? { 'DEF-hips': 'Hips', [sp(1)]: 'Spine', [sp(2)]: 'Spine1', [sp(3)]: 'Spine2', 'DEF-neck': 'Neck', 'DEF-head': 'Head' }
+            : { 'DEF-spine': 'Hips', [sp(1)]: 'Spine', [sp(2)]: 'Spine1', [sp(3)]: 'Spine2', [sp(4)]: 'Neck', [sp(6)]: 'Head' });
+        for (const [s, , t] of SIDES) {
+            Object.assign(alias, {
+                [`DEF-shoulder.${t}`]: `${s}Shoulder`,
+                [`DEF-upper_arm.${t}`]: `${s}Arm`,
+                [`DEF-forearm.${t}`]: `${s}ForeArm`,
+                [`DEF-hand.${t}`]: `${s}Hand`,
+                [`DEF-thigh.${t}`]: `${s}UpLeg`,
+                [`DEF-shin.${t}`]: `${s}Leg`,
+                [`DEF-foot.${t}`]: `${s}Foot`,
+                [`DEF-toe.${t}`]: `${s}ToeBase`,
+            });
+            for (const [f, , rf] of FINGERS)
+                for (const i of [1, 2, 3])
+                    alias[`DEF-${rf}.0${i}.${t}`] = `${s}Hand${f}${i}`;
+        }
+    }
+    const byKey = new Map(Object.entries(alias).map(([k, v]) => [key(k), v]));
+    const toCanon = new Map();
+    const fromCanon = new Map();
+    for (const n of names) {
+        const c = kind === 'mixamo' ? stripMixamo(key(n)) : byKey.get(key(n));
+        if (!c || !CANON.has(c) || fromCanon.has(c))
+            continue;
+        toCanon.set(n, c);
+        fromCanon.set(c, n);
+    }
+    if (!REQUIRED.every((c) => fromCanon.has(c)))
+        return null;
+    return { kind, toCanon, fromCanon };
+}
+/** Every bone under `root`, in traversal order. */
+function bonesUnder(root) {
+    const out = [];
+    root.traverse((o) => { if (o.isBone)
+        out.push(o); });
+    return out;
+}
+/** The skeleton under `root` that `readRigNames` reads, or null. */
+export function detectRig(root) {
+    return readRigNames(bonesUnder(root).map((b) => b.name));
+}
+/**
+ * Rotation taking the rig's frame to canonical (left +X, up +Y, forward +Z).
+ * Up is the file's vertical (+Y, both FBX and glTF), not pelvis → head: a
+ * MetaHuman binds with her head ~10° off the hip line, and measuring up from
+ * the spine added that lean to every upright source pose.
+ */
+function canonicalFrame(pos, l, r) {
+    const left = pos.get(l).clone().sub(pos.get(r));
+    left.y = 0;
+    left.normalize();
+    const up = new THREE.Vector3(0, 1, 0);
+    const fwd = new THREE.Vector3().crossVectors(left, up).normalize();
+    left.crossVectors(up, fwd).normalize();
+    const basis = new THREE.Matrix4().makeBasis(left, up, fwd); // canonical → rig
+    return new THREE.Quaternion().setFromRotationMatrix(basis).invert(); // rig → canonical
+}
+const SECTORS = 16;
+/** Hip height of an average adult above the ankle joint, m: converts bind units to metres. */
+const HIP_HEIGHT_M = 0.92;
+/**
+ * Reads the body under `root` as a retarget target: the skinned mesh whose
+ * skeleton `readRigNames` reads (the largest, when several are), its bind
+ * pose from the inverse bind matrices, and its torso and thighs from every
+ * skinned mesh. Nothing is read from the current pose, so a body that is
+ * already animating (or scaled and grounded) gives the same rig. `null` when
+ * no skeleton is recognised.
+ */
+export function createTargetRig(root) {
+    let mesh = null;
+    let names = null;
+    const meshes = [];
+    root.traverse((o) => {
+        const m = o;
+        if (!m.isSkinnedMesh || !m.skeleton)
+            return;
+        meshes.push(m);
+        if (mesh && m.skeleton.bones.length <= mesh.skeleton.bones.length)
+            return;
+        const n = readRigNames(m.skeleton.bones.map((b) => b.name));
+        if (n)
+            [mesh, names] = [m, n];
+    });
+    if (!mesh || !names)
+        return null;
+    const sk = mesh.skeleton;
+    const rig = names;
+    const T = (c) => rig.fromCanon.get(c);
+    const bones = new Map();
+    const bind = { rot: new Map(), pos: new Map() };
+    const bindMatrix = new Map();
+    const p = new THREE.Vector3();
+    const q = new THREE.Quaternion();
+    const s = new THREE.Vector3();
+    sk.bones.forEach((b, i) => {
+        bones.set(b.name, b);
+        const m = sk.boneInverses[i].clone().invert();
+        bindMatrix.set(b.name, m);
+        m.decompose(p, q, s);
+        bind.rot.set(b.name, q.clone());
+        bind.pos.set(b.name, p.clone());
+    });
+    // Bind frame = bindMatrix · meshWorld⁻¹ · world (attached bind mode), so a
+    // static parent outside the skin can be placed in it from its world matrix.
+    root.updateMatrixWorld(true);
+    const toBind = mesh.bindMatrix.clone().multiply(mesh.matrixWorld.clone().invert());
+    const parentBind = (b) => {
+        const parent = b.parent;
+        const i = parent ? sk.bones.indexOf(parent) : -1;
+        if (i >= 0)
+            return sk.boneInverses[i].clone().invert();
+        return toBind.clone().multiply(parent ? parent.matrixWorld : new THREE.Matrix4());
+    };
+    const topParent = new Map();
+    const local = new Map();
+    const offset = new Map();
+    for (const b of sk.bones) {
+        const parent = b.parent;
+        let pq;
+        if (parent && bones.has(parent.name))
+            pq = bind.rot.get(parent.name);
+        else {
+            parentBind(b).decompose(p, q, s);
+            pq = q.clone();
+            topParent.set(b.name, pq);
+        }
+        local.set(b.name, pq.clone().invert().multiply(bind.rot.get(b.name)));
+        if (parent && bind.pos.has(parent.name))
+            offset.set(b.name, bind.pos.get(b.name).clone().sub(bind.pos.get(parent.name)).applyQuaternion(pq.clone().invert()));
+    }
+    const hips = T('Hips');
+    const hipsParentInv = parentBind(bones.get(hips)).invert();
+    const toCanon = canonicalFrame(bind.pos, T('LeftUpLeg'), T('RightUpLeg'));
+    const y = (n) => bind.pos.get(n).clone().applyQuaternion(toCanon).y;
+    const hipHeight = y(hips) - Math.min(y(T('LeftFoot')), y(T('RightFoot')));
+    const order = [];
+    const top = sk.bones.filter((b) => !b.parent || !bones.has(b.parent.name));
+    for (const t of top)
+        t.traverse((o) => { if (o.isBone && bones.has(o.name))
+            order.push(o); });
+    const subtree = new Map();
+    for (const b of order) {
+        const list = [];
+        b.traverse((o) => { if (o.isBone && bones.has(o.name))
+            list.push(o.name); });
+        subtree.set(b.name, list);
+    }
+    const partial = { names: rig, bones, bind, bindMatrix, local, toCanon, order, hipHeight, unitsPerM: hipHeight / HIP_HEIGHT_M, topParent, hipsParentInv, offset, subtree };
+    return { ...partial, colliders: buildColliders(meshes, partial) };
+}
+/** Hips → neck, bone by bone along the skeleton: [bone, its child on the way up]. */
+function trunk(rig) {
+    const hips = rig.names.fromCanon.get('Hips');
+    const neck = rig.names.fromCanon.get('Neck');
+    if (!neck)
+        return [];
+    const chain = [];
+    for (let o = rig.bones.get(neck) ?? null; o && rig.bones.has(o.name); o = o.parent) {
+        chain.unshift(o.name);
+        if (o.name === hips)
+            break;
+    }
+    if (chain[0] !== hips)
+        return [];
+    return chain.slice(0, -1).map((b, i) => [b, chain[i + 1]]);
+}
+/**
+ * The segments hands and elbows must stay outside of: the trunk, bone by
+ * bone, and each thigh. A vertex belongs to the segment of the nearest
+ * collider bone above its main bone, unless a mapped joint (a clavicle, the
+ * neck, a knee) is in between: twists and correctives count with their bone,
+ * arms and the head do not.
+ */
+function buildColliders(meshes, rig) {
+    const T = (c) => rig.names.fromCanon.get(c);
+    const segs = [...trunk(rig)];
+    for (const [s] of SIDES) {
+        const th = T(`${s}UpLeg`);
+        const ca = T(`${s}Leg`);
+        if (th && ca)
+            segs.push([th, ca]);
+    }
+    const segOf = new Map(segs.map(([b], k) => [b, k]));
+    const owner = new Map();
+    for (const name of rig.bones.keys()) {
+        let k = -1;
+        for (let o = rig.bones.get(name); o && rig.bones.has(o.name); o = o.parent) {
+            if (segOf.has(o.name)) {
+                k = segOf.get(o.name);
+                break;
+            }
+            if (rig.names.toCanon.has(o.name))
+                break;
+        }
+        owner.set(name, k);
+    }
+    // Every skinned part (body, clothing) counts. Each vertex goes into the
+    // frame of its main bone through that mesh's own bind, then out into the
+    // rig's bind frame, so meshes bound separately still line up.
+    const per = segs.map(() => []);
+    const v = new THREE.Vector3();
+    for (const mesh of meshes) {
+        const g = mesh.geometry;
+        const pos = g.attributes.position;
+        const si = g.attributes.skinIndex;
+        const sw = g.attributes.skinWeight;
+        if (!pos || !si || !sw)
+            continue;
+        const bones = mesh.skeleton.bones;
+        const boneSeg = bones.map((b) => owner.get(b.name) ?? -1);
+        const boneM = bones.map((b, j) => {
+            const bm = rig.bindMatrix.get(b.name);
+            if (!bm || boneSeg[j] < 0)
+                return null;
+            return bm.clone().multiply(mesh.skeleton.boneInverses[j]).multiply(mesh.bindMatrix);
+        });
+        for (let i = 0; i < pos.count; i++) {
+            let best = -1;
+            let j = 0;
+            for (let c = 0; c < 4; c++) {
+                const w = sw.getComponent(i, c);
+                if (w > best) {
+                    best = w;
+                    j = si.getComponent(i, c);
+                }
+            }
+            const k = boneSeg[j] ?? -1;
+            if (k < 0)
+                continue;
+            per[k].push(v.fromBufferAttribute(pos, i).applyMatrix4(boneM[j]).clone());
+        }
+    }
+    const out = [];
+    segs.forEach(([bone, tip], k) => {
+        const a = rig.bind.pos.get(bone);
+        const b = rig.bind.pos.get(tip);
+        const verts = per[k];
+        if (verts.length < 50)
+            return;
+        const u = b.clone().sub(a);
+        const len = u.length();
+        if (len < 1e-9)
+            return;
+        u.normalize();
+        const e1 = new THREE.Vector3(1, 0, 0).applyQuaternion(rig.bind.rot.get(bone));
+        e1.addScaledVector(u, -e1.dot(u));
+        if (e1.lengthSq() < 1e-8)
+            e1.set(0, 1, 0).applyQuaternion(rig.bind.rot.get(bone)).addScaledVector(u, -new THREE.Vector3(0, 1, 0).applyQuaternion(rig.bind.rot.get(bone)).dot(u));
+        e1.normalize();
+        const e2 = new THREE.Vector3().crossVectors(u, e1);
+        const bins = Array.from({ length: SECTORS }, () => []);
+        const ts = [];
+        const d = new THREE.Vector3();
+        for (const p of verts) {
+            d.copy(p).sub(a);
+            const t = d.dot(u);
+            ts.push(t / len);
+            d.addScaledVector(u, -t);
+            const th = Math.atan2(d.dot(e2), d.dot(e1));
+            bins[Math.floor(((th + Math.PI) / (2 * Math.PI)) * SECTORS) % SECTORS].push(d.length());
+        }
+        const pct = (x, f) => (x.sort((i, j) => i - j), x[Math.min(x.length - 1, Math.floor(x.length * f))]);
+        const radius = new Float32Array(SECTORS);
+        const all = bins.flat();
+        bins.forEach((r, i) => (radius[i] = r.length >= 5 ? pct(r, 0.9) : pct([...all], 0.5)));
+        out.push({ bone, tip, radius, t0: pct(ts, 0.05), t1: pct(ts, 0.95), e1 });
+    });
+    return out;
+}
+/**
+ * Keeps elbows and hands outside the torso and thighs. A clip made for a
+ * slimmer or differently built body rests its hands on a belly or hips that
+ * this one is not, and they sink in. Per frame: an elbow inside swings the
+ * upper arm out about the shoulder; a hand inside swings the forearm out
+ * about the elbow, each by just the depth plus 1 cm. Works on `world`
+ * (bind-frame world rotations) in place; returns the deepest point found
+ * before clearing, in bind units.
+ */
+function clearArms(rig, world) {
+    const T = (c) => rig.names.fromCanon.get(c);
+    const margin = 0.01 * rig.unitsPerM;
+    let memo = new Map();
+    const pos = (n) => {
+        const hit = memo.get(n);
+        if (hit)
+            return hit;
+        const parent = rig.bones.get(n).parent?.name ?? '';
+        const p = !world.has(parent) || !rig.offset.has(n)
+            ? rig.bind.pos.get(n).clone()
+            : pos(parent).clone().add(rig.offset.get(n).clone().applyQuaternion(world.get(parent)));
+        memo.set(n, p);
+        return p;
+    };
+    const inside = (p) => {
+        let depth = -Infinity;
+        const normal = new THREE.Vector3();
+        for (const c of rig.colliders) {
+            const toBind = rig.bind.rot.get(c.bone).clone().multiply(world.get(c.bone).clone().invert());
+            const q = p.clone().sub(pos(c.bone)).applyQuaternion(toBind);
+            const u = rig.bind.pos.get(c.tip).clone().sub(rig.bind.pos.get(c.bone));
+            const len = u.length();
+            u.normalize();
+            const t = q.dot(u) / len;
+            if (t < c.t0 - 0.05 || t > c.t1 + 0.05)
+                continue;
+            const d = q.addScaledVector(u, -t * len);
+            const e2 = new THREE.Vector3().crossVectors(u, c.e1);
+            const x = ((Math.atan2(d.dot(e2), d.dot(c.e1)) + Math.PI) / (2 * Math.PI)) * SECTORS - 0.5;
+            const i = Math.floor(x);
+            const k = x - i;
+            const r = c.radius[((i % SECTORS) + SECTORS) % SECTORS] * (1 - k) + c.radius[(((i + 1) % SECTORS) + SECTORS) % SECTORS] * k;
+            const dd = r + margin - d.length();
+            if (dd > depth) {
+                depth = dd;
+                normal.copy(d).normalize().applyQuaternion(toBind.invert());
+            }
+        }
+        return { depth, normal };
+    };
+    /** Swing `bone`'s subtree about its joint so `points` clear the body. */
+    const push = (bone, points) => {
+        let worst = 0;
+        for (let it = 0; it < 4; it++) {
+            const pivot = pos(bone);
+            let best = null;
+            for (const p of points()) {
+                const h = inside(p);
+                if (h.depth > 0 && (!best || h.depth > best.depth))
+                    best = { ...h, p };
+            }
+            if (!best)
+                break;
+            worst = Math.max(worst, best.depth);
+            const arm = best.p.clone().sub(pivot);
+            const axis = new THREE.Vector3().crossVectors(arm, best.normal);
+            if (axis.lengthSq() < 1e-12 || arm.length() < 1e-9)
+                break;
+            const r = new THREE.Quaternion().setFromAxisAngle(axis.normalize(), best.depth / arm.length());
+            for (const n of rig.subtree.get(bone))
+                world.set(n, r.clone().multiply(world.get(n)));
+            memo = new Map();
+        }
+        return worst;
+    };
+    let deepest = 0;
+    for (const [s] of SIDES) {
+        const upper = T(`${s}Arm`);
+        const lower = T(`${s}ForeArm`);
+        const hand = T(`${s}Hand`);
+        if (!upper || !lower || !hand || !world.has(upper) || !world.has(lower))
+            continue;
+        const f1 = T(`${s}HandMiddle1`) ?? hand;
+        const f3 = T(`${s}HandMiddle3`) ?? f1;
+        deepest = Math.max(deepest, push(upper, () => [pos(lower), pos(upper).clone().lerp(pos(lower), 0.6)]), push(lower, () => [pos(hand), pos(f1), pos(f3), pos(lower).clone().lerp(pos(hand), 0.5)]));
+    }
+    return deepest;
+}
+/**
+ * Wraps a loaded file (an FBXLoader group, or a GLTF's `scene`) as a
+ * retarget source, recording its rest pose. Call before anything animates
+ * it. `null` when its skeleton is not one `readRigNames` reads.
+ */
+export function createAnimationSource(root, clips) {
+    const names = detectRig(root);
+    if (!names)
+        return null;
+    const rest = [];
+    root.traverse((o) => rest.push([o, o.position.clone(), o.quaternion.clone(), o.scale.clone()]));
+    return { root, clips, names, rest };
+}
+function samplePose(root, bones, toCanon) {
+    root.updateMatrixWorld(true);
+    const invM = root.matrixWorld.clone().invert();
+    const pose = { rot: new Map(), pos: new Map() };
+    const m = new THREE.Matrix4();
+    const s = new THREE.Vector3();
+    for (const b of bones) {
+        const n = toCanon.get(b.name);
+        if (!n)
+            continue;
+        const p = new THREE.Vector3();
+        const q = new THREE.Quaternion();
+        m.multiplyMatrices(invM, b.matrixWorld).decompose(p, q, s);
+        pose.rot.set(n, q);
+        pose.pos.set(n, p);
+    }
+    return pose;
+}
+// ── posture, tuned on convai-mha-1 bodies against their own clips ───────────
+/**
+ * Trunk lean (hips → neck, degrees, + = forward) the convai-mha-1 pack idle
+ * holds. Mixamo's idles and talks stand 1–4° further back than Mixamo's rest
+ * pose, which reads as a backward lean on these bodies.
+ */
+export const UPRIGHT_DEG = -3;
+/** Hips at least this share of standing height: a standing frame. */
+const STANDING = 0.85;
+/**
+ * Most the trunk is pitched forward, degrees. Only forward: a clip that
+ * already leans forward is left alone, and a deliberate lean back (pointing,
+ * laughing) is softened, not erased.
+ */
+const MAX_CORRECTION = 6;
+/**
+ * Share of the posture correction each spine joint (and everything above it)
+ * takes. Leaning the upper back forward carries the neck's base forward of
+ * the shoulders, pushing the head out; the neck turns back by the same amount
+ * so the head stays over the shoulders as in the source. The head takes none,
+ * so the gaze stays where the clip put it.
+ */
+const SPINE_SHARE = [['Head', 0], ['Neck', -1], ['Spine2', 1], ['Spine1', 2 / 3], ['Spine', 1 / 3]];
+/**
+ * Knee bend (thigh pitch − shin pitch, degrees) a standing clip's median is
+ * brought to. Mixamo's idles and talks stand with 30–45° of bend; the pack
+ * idle stands at 0°, and the bend pushes the hips back so the body reads as
+ * leaning back. Every frame's bend is scaled by the same factor, so stepping
+ * and weight shifts keep their shape.
+ */
+const KNEE_FLEX_DEG = 8;
+/**
+ * Clavicle elevation (clavicle → upper arm above level, degrees) the pack
+ * clips hold. Mixamo's shoulders sit 3–8° lower; each side is lifted so the
+ * clip's median reaches this, by at most SHOULDER_MAX_DEG and never lowered.
+ */
+const SHOULDER_UP_DEG = -3.4;
+const SHOULDER_MAX_DEG = 6;
+/** Quaternions this close (|dot| ≥) are the same rotation. */
+const SAME = 1 - 1e-9;
+/**
+ * Retargets one clip of `source` onto `rig`: a clip of local rotations for
+ * the target's bones (only those that ever leave their rest) and the hips'
+ * position, sampled at `fps`.
+ */
+export function retargetClip(source, src, rig, opts = {}) {
+    const fps = opts.fps ?? 30;
+    const name = opts.name ?? src.name;
+    for (const [o, p, q, sc] of source.rest) {
+        o.position.copy(p);
+        o.quaternion.copy(q);
+        o.scale.copy(sc);
+    }
+    const sRoot = source.root;
+    const srcBones = bonesUnder(sRoot);
+    const sNames = source.names.toCanon;
+    const T = (c) => rig.names.fromCanon.get(c);
+    const rest = samplePose(sRoot, srcBones, sNames);
+    const sToCanon = canonicalFrame(rest.pos, 'LeftUpLeg', 'RightUpLeg');
+    const sy = (pose, n) => pose.pos.get(n).clone().applyQuaternion(sToCanon).y;
+    const sHip = sy(rest, 'Hips') - Math.min(sy(rest, 'LeftFoot'), sy(rest, 'RightFoot'));
+    if (!(sHip > 1e-9) || !(rig.hipHeight > 1e-9))
+        throw new Error('cannot measure hip height (hips not above the feet)');
+    const scale = rig.hipHeight / sHip;
+    const hips = T('Hips');
+    /** Target bone → canonical joint, for joints both rigs have. */
+    const mapped = new Map();
+    for (const [c, t] of rig.names.fromCanon)
+        if (rest.rot.has(c))
+            mapped.set(t, c);
+    // Rest-pose fix per mapped bone, in canonical space.
+    const ident = new THREE.Quaternion();
+    const fix = new Map();
+    for (const [t, c] of mapped) {
+        const aim = AIM[c];
+        const tAim = aim ? T(aim) : undefined;
+        if (FLAT.has(c) || OWN_SHAPE.has(c) || !aim || !tAim || !rest.pos.has(aim)) {
+            fix.set(t, ident.clone());
+            continue;
+        }
+        const ds = rest.pos.get(aim).clone().sub(rest.pos.get(c)).applyQuaternion(sToCanon).normalize();
+        const dt = rig.bind.pos.get(tAim).clone().sub(rig.bind.pos.get(t)).applyQuaternion(rig.toCanon).normalize();
+        if (ELEVATION_ONLY.has(c) && Math.abs(Math.asin(THREE.MathUtils.clamp(ds.z, -1, 1))) > THREE.MathUtils.degToRad(CLAVICLE_BUILD_DEG))
+            ds.set(Math.sign(dt.x) * Math.sqrt(Math.max(0, 1 - ds.y * ds.y)), ds.y, 0);
+        fix.set(t, new THREE.Quaternion().setFromUnitVectors(dt, ds));
+    }
+    // Ends of chains (fingertips, toes) inherit their nearest fixed ancestor's fix.
+    for (const [t, c] of mapped) {
+        if (FLAT.has(c) || OWN_SHAPE.has(c) || !fix.get(t).equals(ident))
+            continue;
+        for (let p = rig.bones.get(t).parent; p && rig.bones.has(p.name); p = p.parent) {
+            const f = fix.get(p.name);
+            if (f && !f.equals(ident)) {
+                fix.set(t, f.clone());
+                break;
+            }
+        }
+    }
+    const mixer = new THREE.AnimationMixer(sRoot);
+    const sampler = mixer.clipAction(src);
+    // A one-shot that holds its last frame: a looping action wraps
+    // t = duration back to 0, which made every clip end on its first pose.
+    sampler.setLoop(THREE.LoopOnce, 1);
+    sampler.clampWhenFinished = true;
+    const sampleAt = (t) => {
+        sampler.reset().play();
+        mixer.setTime(t);
+        return samplePose(sRoot, srcBones, sNames);
+    };
+    const frames = Math.max(2, Math.round(src.duration * fps) + 1);
+    const times = new Float32Array(frames);
+    const qTracks = new Map();
+    for (const b of rig.order)
+        qTracks.set(b.name, new Float32Array(frames * 4));
+    const hipsPos = new Float32Array(frames * 3);
+    const tCanonInv = rig.toCanon.clone().invert();
+    const sCanonInv = sToCanon.clone().invert();
+    const world = new Map();
+    const restCanonInv = new Map();
+    for (const c of mapped.values())
+        restCanonInv.set(c, sToCanon.clone().multiply(rest.rot.get(c)).multiply(sCanonInv).invert());
+    const restT = new Map();
+    for (const t of mapped.keys())
+        restT.set(t, rig.toCanon.clone().multiply(rig.bind.rot.get(t)).multiply(tCanonInv));
+    const hipsRest = rig.bind.pos.get(hips).clone().applyMatrix4(rig.hipsParentInv);
+    const parentLinear = new THREE.Matrix3().setFromMatrix4(rig.hipsParentInv);
+    /** A bone's vector to `child` (anywhere below it), in its own bind frame. */
+    const segCache = new Map();
+    const seg = (bone, child) => {
+        const k = `${bone}>${child}`;
+        let v = segCache.get(k);
+        if (!v)
+            segCache.set(k, (v = rig.bind.pos.get(child).clone().sub(rig.bind.pos.get(bone)).applyQuaternion(rig.bind.rot.get(bone).clone().invert())));
+        return v;
+    };
+    /** The hip line for the hips' bind-frame rotation, level, in canonical space: the axis the body leans about. */
+    const hipLine = seg(hips, T('LeftUpLeg')).clone().sub(seg(hips, T('RightUpLeg')));
+    const hipAxis = (hipsWorld) => {
+        const v = hipLine.clone().applyQuaternion(hipsWorld).applyQuaternion(rig.toCanon);
+        v.y = 0;
+        return v.normalize();
+    };
+    const share = new Map();
+    const shareBy = new Map(SPINE_SHARE.flatMap(([c, k]) => (T(c) ? [[T(c), k]] : [])));
+    for (const b of rig.order) {
+        for (let o = b; o; o = o.parent) {
+            const k = shareBy.get(o.name);
+            if (k !== undefined) {
+                share.set(b.name, k);
+                break;
+            }
+        }
+    }
+    const legs = SIDES.map(([s]) => [T(`${s}UpLeg`), T(`${s}Leg`), T(`${s}Foot`)])
+        .filter((l) => l.every((n) => n && mapped.has(n)));
+    const clavicles = SIDES.map(([s]) => [T(`${s}Shoulder`), T(`${s}Arm`)])
+        .filter((l) => l.every((n) => n && mapped.has(n)));
+    const trunkChain = trunk(rig);
+    /** Source hips height over the lower foot, as a share of standing height. */
+    const hipShare = (pose) => (sy(pose, 'Hips') - Math.min(sy(pose, 'LeftFoot'), sy(pose, 'RightFoot'))) / sHip;
+    /** A mapped bone's rotation in canonical space, before any posture correction. */
+    const canon = (t, pose) => {
+        const c = mapped.get(t);
+        return sToCanon.clone().multiply(pose.rot.get(c)).multiply(sCanonInv)
+            .multiply(restCanonInv.get(c)).multiply(fix.get(t)).multiply(restT.get(t));
+    };
+    /** A bone's vector to `child`, in canonical space, for canonical rotation c. */
+    const boneVec = (c, bone, child) => seg(bone, child).clone().applyQuaternion(rig.toCanon).applyQuaternion(c);
+    const up = new THREE.Vector3(0, 1, 0);
+    const pitch = (v, fwd) => THREE.MathUtils.radToDeg(Math.atan2(v.dot(fwd), -v.y));
+    const rotAbout = (axis, deg) => new THREE.Quaternion().setFromAxisAngle(axis, THREE.MathUtils.degToRad(deg));
+    const clearHands = opts.clearHands !== false && rig.colliders.length > 0;
+    /**
+     * Target world rotations for the source at time t, with the spine pitched
+     * `corr` degrees forward and each knee's bend scaled by `knee` (fading out
+     * as the hips drop below standing, so a squat keeps its bend). Returns the
+     * source pose, each leg's bend before scaling, how much the straighter
+     * standing leg lifts the hips (canonical units) and each clavicle's
+     * elevation.
+     */
+    let handDepth = 0;
+    /** Bones whose solved local rotation ever leaves their bind (measured before Float32 storage). */
+    const moved = new Set();
+    const solve = (t, corr, knee = 1, f = -1, shoulders = {}) => {
+        const pose = sampleAt(t);
+        world.clear();
+        // Legs first: each bone's rotation is absolute, so the thigh and shin can
+        // be pitched apart without moving the foot's own orientation.
+        const legTurn = new Map();
+        const flex = [];
+        const hipsC = mapped.has(hips) ? canon(hips, pose) : restT.get(hips) ?? ident;
+        const axis = hipAxis(tCanonInv.clone().multiply(hipsC).multiply(rig.toCanon));
+        const fwd = new THREE.Vector3().crossVectors(axis, up);
+        const stand = THREE.MathUtils.smoothstep(hipShare(pose), STANDING - 0.1, STANDING);
+        const k = 1 - (1 - knee) * stand;
+        let lift = 0;
+        let lowest = -Infinity;
+        for (const [thigh, calf, foot] of legs) {
+            const tv = boneVec(canon(thigh, pose), thigh, calf);
+            const sv = boneVec(canon(calf, pose), calf, foot);
+            const bend = pitch(tv, fwd) - pitch(sv, fwd);
+            flex.push(bend);
+            const turn = (bend * (1 - k)) / 2;
+            legTurn.set(thigh, turn);
+            legTurn.set(calf, -turn);
+            const before = -(tv.y + sv.y);
+            if (before > lowest) {
+                lowest = before;
+                lift = -(tv.clone().applyQuaternion(rotAbout(axis, turn)).y + sv.clone().applyQuaternion(rotAbout(axis, -turn)).y) - before;
+            }
+        }
+        for (const b of rig.order) {
+            const n = b.name;
+            const parentWorld = (b.parent && world.get(b.parent.name)) || rig.topParent.get(n) || null;
+            let w;
+            if (mapped.has(n)) {
+                // Δ in canonical space, applied to the rest-fixed target rotation.
+                let c = canon(n, pose);
+                const ks = share.get(n);
+                if (ks && corr)
+                    c = rotAbout(axis, ks * corr).multiply(c);
+                const turn = legTurn.get(n);
+                if (turn)
+                    c = rotAbout(axis, turn).multiply(c);
+                const lifted = shoulders[n];
+                if (lifted) {
+                    const arm = clavicles.find(([cl]) => cl === n)[1];
+                    const v = boneVec(c, n, arm);
+                    c = rotAbout(new THREE.Vector3().crossVectors(v, up).normalize(), lifted).multiply(c);
+                }
+                w = tCanonInv.clone().multiply(c).multiply(rig.toCanon);
+            }
+            else {
+                w = parentWorld ? parentWorld.clone().multiply(rig.local.get(n)) : rig.bind.rot.get(n).clone();
+            }
+            world.set(n, w);
+        }
+        if (f >= 0) {
+            if (clearHands)
+                handDepth = Math.max(handDepth, clearArms(rig, world));
+            const tmp = new THREE.Quaternion();
+            for (const b of rig.order) {
+                const parentWorld = (b.parent && world.get(b.parent.name)) || rig.topParent.get(b.name) || null;
+                const l = parentWorld ? tmp.copy(parentWorld).invert().multiply(world.get(b.name)) : rig.local.get(b.name);
+                if (Math.abs(l.dot(rig.local.get(b.name))) < SAME)
+                    moved.add(b.name);
+                l.toArray(qTracks.get(b.name), f * 4);
+            }
+        }
+        const clav = clavicles.map(([cl, arm]) => {
+            const v = boneVec(canon(cl, pose), cl, arm);
+            return THREE.MathUtils.radToDeg(Math.asin(THREE.MathUtils.clamp(v.y / v.length(), -1, 1)));
+        });
+        return { pose, flex, lift, clav };
+    };
+    /** Hips → neck lean of the solved pose, degrees forward of the hips. */
+    const trunkLean = () => {
+        const v = new THREE.Vector3();
+        for (const [b, child] of trunkChain)
+            v.add(seg(b, child).clone().applyQuaternion(world.get(b)));
+        v.applyQuaternion(rig.toCanon);
+        const fwd = new THREE.Vector3().crossVectors(hipAxis(world.get(hips)), up);
+        return THREE.MathUtils.radToDeg(Math.atan2(v.dot(fwd), v.y));
+    };
+    // Neutral lean = median over the frames where the body stands (a pick-up's
+    // bend or a sit doesn't count). The trunk turns less than the correction
+    // (the lower spine takes a share); the lean is close to linear in it, so
+    // one probe frame gives the gain.
+    const upright = opts.upright === undefined ? UPRIGHT_DEG : opts.upright;
+    const standing = [];
+    const bends = [];
+    const clavs = clavicles.map(() => []);
+    for (let f = 0; f < frames; f++) {
+        const { pose, flex, clav } = solve(Math.min(src.duration, f / fps), 0);
+        clav.forEach((v, i) => clavs[i].push(v));
+        if (hipShare(pose) <= STANDING)
+            continue;
+        if (trunkChain.length)
+            standing.push(trunkLean());
+        bends.push(...flex);
+    }
+    const median = (v) => (v.sort((x, y) => x - y), v.length ? v[Math.floor(v.length / 2)] : NaN);
+    const lean0 = median(standing);
+    const bend0 = median(bends);
+    const isStanding = upright !== null && standing.length >= frames / 2;
+    // A clip whose knees bend well past their usual stance (a squat to pick
+    // something up) means it; leave those knees alone.
+    const crouch = bends.length ? bends[Math.floor(bends.length * 0.95)] - bend0 > 20 : true;
+    const knee = isStanding && !crouch && bend0 > KNEE_FLEX_DEG + 4 ? Math.max(0.15, KNEE_FLEX_DEG / bend0) : 1;
+    const shoulders = {};
+    if (upright !== null)
+        clavicles.forEach(([cl], i) => (shoulders[cl] = THREE.MathUtils.clamp(SHOULDER_UP_DEG - median(clavs[i]), 0, SHOULDER_MAX_DEG)));
+    let corr = 0;
+    if (isStanding && upright - lean0 > 0.25) {
+        const probe = (c) => (solve(0, c, knee), trunkLean());
+        const guess = upright - lean0;
+        const gain = (probe(guess) - probe(0)) / guess;
+        if (gain > 1e-3)
+            corr = Math.min(MAX_CORRECTION, guess) / gain;
+    }
+    for (let f = 0; f < frames; f++) {
+        const t = Math.min(src.duration, f / fps);
+        times[f] = t;
+        const { pose, lift } = solve(t, corr, knee, f, shoulders);
+        // Hips: the source hips' offset from rest, in canonical space, scaled,
+        // raised by what straightening the standing leg added.
+        const d = pose.pos.get('Hips').clone().sub(rest.pos.get('Hips')).applyQuaternion(sToCanon).multiplyScalar(scale);
+        d.y += lift;
+        // Into the hips' parent's frame (bind frame → parent local, with its scale).
+        d.applyQuaternion(tCanonInv).applyMatrix3(parentLinear);
+        hipsRest.clone().add(d).toArray(hipsPos, f * 3);
+    }
+    mixer.stopAllAction();
+    mixer.uncacheRoot(sRoot);
+    for (const [o, p, q, sc] of source.rest) {
+        o.position.copy(p);
+        o.quaternion.copy(q);
+        o.scale.copy(sc);
+    }
+    // Only bones that ever leave their bind get a track: the rest stay as the
+    // scene holds them, and the mixer has fewer bindings to drive.
+    const tracks = [];
+    for (const [n, values] of qTracks)
+        if (moved.has(n))
+            tracks.push(new THREE.QuaternionKeyframeTrack(`${n}.quaternion`, times, values));
+    tracks.push(new THREE.VectorKeyframeTrack(`${hips}.position`, times, hipsPos));
+    for (const t of tracks)
+        if (t.values.some((v) => !Number.isFinite(v)))
+            throw new Error(`non-finite values on ${t.name}`);
+    const clip = new THREE.AnimationClip(name, src.duration, tracks);
+    const report = {
+        source: source.names.kind,
+        neutralLeanDeg: lean0,
+        trunkCorrectionDeg: corr && upright !== null ? Math.min(MAX_CORRECTION, upright - lean0) : 0,
+        kneeBendDeg: bend0,
+        kneeScale: knee,
+        shoulderLiftDeg: shoulders,
+        handsClearedCm: (handDepth / rig.unitsPerM) * 100,
+    };
+    clip.userData = { ...clip.userData, retarget: report };
+    return clip;
+}