Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Cross-rig upright-invariant corpus — the "stays shipped" regression lock.
*
* The lying-down bug shipped because nothing asserted that an animated avatar
* stays upright. michelle.glb (a Mixamo export) rendered flat on its back the
* moment it played `celebrate`, because the retargeter copied the clip's Hips
* rotation verbatim and wiped the rig's −90°X up-axis convention. This suite
* locks the invariant — the Hips world up-axis stays within tolerance of
* vertical at EVERY keyframe — across a corpus of rig conventions × the
* FEATURED clips, using the same world-matrix reconstruction the bug was
* diagnosed with, in plain Node (raw GLB JSON-chunk parse, no GLTFLoader, no
* network) so it gates every Vercel build.
*
* Empirical tilt data (measured on the committed real avatars during
* development; re-derive by logging `max` below):
*
* max Hips tilt across all keyframes, retargeted WITH the bind correction:
* cz: idle 7.2° walk 6.7° jump 14.0° wave 15.4° dance 30.0° celebrate 14.0°
* michelle: idle 7.3° walk 6.7° jump 14.1° wave 15.4° dance 29.9° celebrate 14.1°
* same clips retargeted WITHOUT the correction (the pre-fix, verbatim path):
* cz: identical (cz IS the authoring convention → byte-for-byte no-op)
* michelle: idle 92° walk 93° jump 94° wave 89° dance 115° celebrate 94°
*
* `dance` legitimately leans the hips to ~30° at peak — that's choreography, not
* a fault — so the corpus tolerance must clear it. We use 40°: comfortably above
* the worst healthy clip (dance 30°) yet far below the catastrophe floor (the
* verbatim michelle case never drops below ~89°). The runtime guard fires at
* >45° but only samples the at-rest pose, where healthy clips peak at ~18°.
*/
import { describe, it, expect, beforeAll } from 'vitest';
import { fileURLToPath } from 'node:url';
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import {
Bone,
Object3D,
SkinnedMesh,
Skeleton,
BufferGeometry,
Quaternion,
Vector3,
} from 'three';
import {
canonicalNodeMapFromObject,
canonicalRestMapFromObject,
retargetClip,
parseClipJSON,
MIN_COVERAGE,
} from '../src/animation-retarget.js';
import { FEATURED } from '../src/animation-presets.js';
import { measureHipsTiltDeg } from '../src/animation-manager.js';
import { loadBoneGraph, hipsTiltAcrossClip } from './_helpers/glb-bone-graph.js';
import { liftHipsUpright } from '../scripts/upright-hips.mjs';
const __dirname = dirname(fileURLToPath(import.meta.url));
const repoRoot = resolve(__dirname, '..');
const avatar = (name) => resolve(repoRoot, 'public/avatars', name);
const clipPath = (name) => resolve(repoRoot, 'public/animations/clips', `${name}.json`);
// Clips whose source GLB bakes the up-axis conversion onto the animated Hips
// (three.js Soldier/Michelle) and are corrected by `uprightFix` at build time.
// These never reached FEATURED, which is exactly how they shipped lying flat —
// so they get their own lock against the committed clip data.
const UPRIGHT_FIX_CLIPS = JSON.parse(
readFileSync(resolve(repoRoot, 'scripts/animations.config.json'), 'utf8'),
)
.filter((e) => e.uprightFix)
.map((e) => e.name);
// Tolerance for the upright invariant: see the empirical table in the module
// header. 40° clears the worst healthy clip (dance ~30°) with margin and sits
// well below the catastrophe floor (~89°), so a regression that tips a rig flat
// cannot pass.
const UPRIGHT_TOLERANCE_DEG = 40;
// A retarget that produces a fallen pose lands near 90°. The "this test has
// teeth" assertions prove the pre-fix path crosses this; the runtime guard uses
// 45° (CATASTROPHE_TILT_DEG in src/animation-manager.js) for the same reason.
const CATASTROPHE_DEG = 80;
// Load the featured clips once.
/** @type {Map<string, import('three').AnimationClip>} */
const CLIPS = new Map();
beforeAll(() => {
for (const name of FEATURED) {
const json = JSON.parse(readFileSync(clipPath(name), 'utf8'));
CLIPS.set(name, parseClipJSON(json, name));
}
});
// Retarget a featured clip onto a reconstructed rig the way AnimationManager
// does, then return the Hips tilt scan. `withFix=false` drops the bind
// correction (the pre-fix verbatim path) to prove the fix is load-bearing.
function scanClip(root, clipName, { withFix = true } = {}) {
const map = canonicalNodeMapFromObject(root);
const targetRest = withFix ? canonicalRestMapFromObject(root) : new Map();
const { clip } = retargetClip(CLIPS.get(clipName), map, { targetRest });
const hipsName = map.get('Hips');
if (!hipsName) return null;
return hipsTiltAcrossClip(root, hipsName, clip);
}
// ── Real committed avatars ──────────────────────────────────────────────────
describe('upright invariant — real avatars (cz Avaturn, michelle Mixamo)', () => {
for (const [label, file] of [
['cz.glb (Avaturn, identity convention)', 'cz.glb'],
['michelle.glb (Mixamo, −90°X Hips)', 'michelle.glb'],
]) {
describe(label, () => {
for (const clip of FEATURED) {
it(`${clip} keeps Hips within ${UPRIGHT_TOLERANCE_DEG}° of vertical at every keyframe`, () => {
const { root } = loadBoneGraph(avatar(file));
const scan = scanClip(root, clip);
expect(scan).not.toBeNull();
expect(scan.samples).toBeGreaterThan(0);
expect(scan.max).toBeLessThan(UPRIGHT_TOLERANCE_DEG);
});
}
});
}
});
// ── Named regression lock: the exact bug ────────────────────────────────────
describe('regression lock — the michelle lying-down bug', () => {
it('michelle + celebrate stays upright (regression lock for the lying-down bug)', () => {
const { root } = loadBoneGraph(avatar('michelle.glb'));
const scan = scanClip(root, 'celebrate');
expect(scan).not.toBeNull();
expect(scan.max).toBeLessThan(UPRIGHT_TOLERANCE_DEG);
});
it('the test has teeth: WITHOUT the bind correction, michelle + celebrate falls flat', () => {
// Prove the fix is load-bearing — the verbatim path (no targetRest) must
// reproduce the catastrophe, so this suite would have caught the bug and
// will catch any regression that removes the correction.
const { root } = loadBoneGraph(avatar('michelle.glb'));
const verbatim = scanClip(root, 'celebrate', { withFix: false });
expect(verbatim).not.toBeNull();
expect(verbatim.max).toBeGreaterThan(CATASTROPHE_DEG);
});
});
// ── Synthetic rigs (Bone graph built by hand — no GLB needed) ───────────────
// Build a synthetic rig: an armature root carrying `armatureRot`, a Hips
// carrying `hipsRot`, and a full enough canonical skeleton under it that a
// featured clip clears MIN_COVERAGE. Bone names come from `nameFor` so the same
// builder exercises canonical, DEF-/snake_case, and partial-coverage rigs.
const CANONICAL_LIMBS = [
'Spine', 'Spine1', 'Spine2', 'Neck', 'Head',
'LeftShoulder', 'LeftArm', 'LeftForeArm', 'LeftHand',
'RightShoulder', 'RightArm', 'RightForeArm', 'RightHand',
'LeftUpLeg', 'LeftLeg', 'LeftFoot', 'LeftToeBase',
'RightUpLeg', 'RightLeg', 'RightFoot', 'RightToeBase',
'LeftHandThumb1', 'LeftHandIndex1', 'LeftHandMiddle1',
'RightHandThumb1', 'RightHandIndex1', 'RightHandMiddle1',
];
function buildSyntheticRig({ armatureRot, hipsRot, nameFor, limbs = CANONICAL_LIMBS }) {
const root = new Object3D();
const armature = new Bone();
armature.name = 'Armature';
if (armatureRot) armature.quaternion.copy(armatureRot);
const hips = new Bone();
hips.name = nameFor('Hips');
if (hipsRot) hips.quaternion.copy(hipsRot);
armature.add(hips);
const bones = [armature, hips];
for (const canonical of limbs) {
const b = new Bone();
b.name = nameFor(canonical);
// Slight non-identity rest so limb rest capture is exercised, not all-zero.
b.quaternion.setFromAxisAngle(new Vector3(0, 0, 1), 0.05);
hips.add(b);
bones.push(b);
}
root.add(armature);
const mesh = new SkinnedMesh(new BufferGeometry());
root.add(mesh);
mesh.bind(new Skeleton(bones));
root.updateMatrixWorld(true);
return root;
}
const identityName = (canonical) => canonical;
// DEF-/snake_case vendor names that canonicalizeBoneName still resolves.
const SNAKE = {
Hips: 'DEF-hips', Spine: 'DEF-spine', Spine1: 'DEF-spine1', Spine2: 'DEF-spine2',
Neck: 'DEF-neck', Head: 'DEF-head',
LeftShoulder: 'left_shoulder', LeftArm: 'left_arm', LeftForeArm: 'left_forearm', LeftHand: 'left_hand',
RightShoulder: 'right_shoulder', RightArm: 'right_arm', RightForeArm: 'right_forearm', RightHand: 'right_hand',
LeftUpLeg: 'left_upleg', LeftLeg: 'left_leg', LeftFoot: 'left_foot', LeftToeBase: 'left_toebase',
RightUpLeg: 'right_upleg', RightLeg: 'right_leg', RightFoot: 'right_foot', RightToeBase: 'right_toebase',
LeftHandThumb1: 'left_handthumb1', LeftHandIndex1: 'left_handindex1', LeftHandMiddle1: 'left_handmiddle1',
RightHandThumb1: 'right_handthumb1', RightHandIndex1: 'right_handindex1', RightHandMiddle1: 'right_handmiddle1',
};
const snakeName = (canonical) => SNAKE[canonical] || canonical;
const rotX = (deg) => new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), (deg * Math.PI) / 180);
const rotZ = (deg) => new Quaternion().setFromAxisAngle(new Vector3(0, 0, 1), (deg * Math.PI) / 180);
describe('upright invariant — synthetic rig conventions', () => {
// A non-±90 / non-X convention: +90°Z armature, compensating −90°Z Hips.
// Proves the correction generalises beyond the michelle (−90°X) case.
describe('non-±90X convention (+90°Z armature / −90°Z Hips)', () => {
for (const clip of FEATURED) {
it(`${clip} stays upright`, () => {
const root = buildSyntheticRig({
armatureRot: rotZ(90),
hipsRot: rotZ(-90),
nameFor: identityName,
});
const scan = scanClip(root, clip);
expect(scan).not.toBeNull();
expect(scan.max).toBeLessThan(UPRIGHT_TOLERANCE_DEG);
});
}
it('has teeth: the same rig without the correction tips over', () => {
const root = buildSyntheticRig({
armatureRot: rotZ(90),
hipsRot: rotZ(-90),
nameFor: identityName,
});
const verbatim = scanClip(root, 'celebrate', { withFix: false });
expect(verbatim).not.toBeNull();
expect(verbatim.max).toBeGreaterThan(CATASTROPHE_DEG);
});
});
// DEF-/snake_case bone names (Rigify / Blender exports) that still retarget.
describe('DEF-/snake_case bone names with a −90°X Hips', () => {
for (const clip of FEATURED) {
it(`${clip} maps the vendor names and stays upright`, () => {
const root = buildSyntheticRig({
armatureRot: rotX(90),
hipsRot: rotX(-90),
nameFor: snakeName,
});
const scan = scanClip(root, clip);
expect(scan).not.toBeNull();
expect(scan.max).toBeLessThan(UPRIGHT_TOLERANCE_DEG);
});
}
});
// A rig sharing too few canonical bones to perform the motion: retargetClip
// returns a null clip (coverage below MIN_COVERAGE). That means "this rig
// can't be driven", NOT a fallen pose — the corpus must handle it gracefully
// (no throw) and skip it.
describe('missing-bones rig (coverage below MIN_COVERAGE)', () => {
const FEW = ['Spine', 'Head', 'LeftArm']; // 4 of 52 canonical tracks map → < 0.5
it('retargets to a null clip rather than throwing or producing a fallen pose', () => {
const root = buildSyntheticRig({
armatureRot: rotX(90),
hipsRot: rotX(-90),
nameFor: identityName,
limbs: FEW,
});
const map = canonicalNodeMapFromObject(root);
const targetRest = canonicalRestMapFromObject(root);
const { clip, coverage } = retargetClip(CLIPS.get('celebrate'), map, { targetRest });
expect(coverage).toBeLessThan(MIN_COVERAGE);
expect(clip).toBeNull();
});
it('the corpus scan treats a null clip as skip (returns null, no tilt)', () => {
const root = buildSyntheticRig({
armatureRot: rotX(90),
hipsRot: rotX(-90),
nameFor: identityName,
limbs: FEW,
});
expect(() => scanClip(root, 'celebrate')).not.toThrow();
expect(scanClip(root, 'celebrate')).toBeNull();
});
});
});
// ── No-regression: cz.glb round-trips byte-for-byte ─────────────────────────
describe('no-regression — cz.glb retarget is byte-for-byte the verbatim path', () => {
// cz IS the authoring convention (its Hips rest is identity), so the bind
// correction must be a no-op: every track's values must equal the verbatim
// path's. This is the shipped `cz: 1.7° → 1.7°` invariant in test form.
for (const clip of FEATURED) {
it(`${clip}: bind-correction output equals no-correction output, track for track`, () => {
const { root: r1 } = loadBoneGraph(avatar('cz.glb'));
const map = canonicalNodeMapFromObject(r1);
const targetRest = canonicalRestMapFromObject(r1);
const corrected = retargetClip(CLIPS.get(clip), map, { targetRest }).clip;
const verbatim = retargetClip(CLIPS.get(clip), map, { targetRest: new Map() }).clip;
expect(corrected).not.toBeNull();
expect(verbatim).not.toBeNull();
const names = corrected.tracks.map((t) => t.name);
expect(names).toEqual(verbatim.tracks.map((t) => t.name));
for (let i = 0; i < corrected.tracks.length; i++) {
expect(Array.from(corrected.tracks[i].values)).toEqual(
Array.from(verbatim.tracks[i].values),
);
}
});
}
});
// ── Runtime guard's pure measurement (the actual shipped code) ──────────────
// measureHipsTiltDeg is the exact helper the runtime fallen-pose guard calls
// once per clip in src/animation-manager.js. Exercise it directly so what the
// guard decides on is what the corpus verifies. The guard's threshold is 45°.
const GUARD_THRESHOLD_DEG = 45;
// Retarget the way the manager does and measure with the real guard helper.
function guardTilt(root, clipName, { withFix = true } = {}) {
const map = canonicalNodeMapFromObject(root);
const targetRest = withFix ? canonicalRestMapFromObject(root) : new Map();
const { clip } = retargetClip(CLIPS.get(clipName), map, { targetRest });
return measureHipsTiltDeg(clip, root, map);
}
describe('runtime guard (measureHipsTiltDeg) is silent on healthy rigs', () => {
for (const [label, file] of [
['cz.glb', 'cz.glb'],
['michelle.glb (post-fix)', 'michelle.glb'],
]) {
for (const clip of FEATURED) {
it(`${label} + ${clip}: at-rest tilt stays under the ${GUARD_THRESHOLD_DEG}° guard threshold`, () => {
const tilt = guardTilt(loadBoneGraph(avatar(file)).root, clip);
expect(tilt).not.toBeNull();
expect(tilt).toBeLessThan(GUARD_THRESHOLD_DEG);
});
}
}
});
describe('runtime guard (measureHipsTiltDeg) catches a genuine fallen pose', () => {
it('michelle + celebrate without the fix measures > 45° (the guard would fire)', () => {
const tilt = guardTilt(loadBoneGraph(avatar('michelle.glb')).root, 'celebrate', {
withFix: false,
});
expect(tilt).not.toBeNull();
expect(tilt).toBeGreaterThan(GUARD_THRESHOLD_DEG);
});
it('returns null (can\'t assess, never a false alarm) when there is no clip', () => {
const { root } = loadBoneGraph(avatar('cz.glb'));
const map = canonicalNodeMapFromObject(root);
expect(measureHipsTiltDeg(null, root, map)).toBeNull();
expect(measureHipsTiltDeg(undefined, root, map)).toBeNull();
});
});
// ── uprightFix corpus: the soldier / samba lying-down regression ─────────────
// These four clips reached production lying on their back (the `fallen-pose
// retarget` reports for `michelle-samba-dance` and the soldier idle/walk/run).
// Their source GLBs bake a ~90° up-axis conversion onto the animated Hips, which
// the retargeter copies verbatim. The committed clip data is now corrected at
// build time by `uprightFix`; this corpus asserts the shipped data stays upright
// and that the correction is the load-bearing reason.
describe('uprightFix corpus — committed clip data stays upright on a neutral rig', () => {
it('discovers the flagged clips from animations.config.json', () => {
// Guards the whole suite: if the flags vanish, this fails rather than
// silently testing nothing.
expect(UPRIGHT_FIX_CLIPS).toEqual(
expect.arrayContaining([
'soldier-idle',
'soldier-walk',
'soldier-run',
'michelle-samba-dance',
]),
);
});
for (const name of UPRIGHT_FIX_CLIPS) {
it(`${name}: at-rest Hips tilt is under the ${GUARD_THRESHOLD_DEG}° guard (won't be auto-disabled)`, () => {
const json = JSON.parse(readFileSync(clipPath(name), 'utf8'));
const clip = parseClipJSON(json, name);
const { root } = loadBoneGraph(avatar('cz.glb'));
const map = canonicalNodeMapFromObject(root);
const { clip: retargeted } = retargetClip(clip, map, {
targetRest: canonicalRestMapFromObject(root),
});
const tilt = measureHipsTiltDeg(retargeted, root, map);
expect(tilt).not.toBeNull();
expect(tilt).toBeLessThan(GUARD_THRESHOLD_DEG);
});
it(`${name}: stays within ${UPRIGHT_TOLERANCE_DEG + 5}° of vertical at every keyframe`, () => {
const json = JSON.parse(readFileSync(clipPath(name), 'utf8'));
const clip = parseClipJSON(json, name);
const { root } = loadBoneGraph(avatar('cz.glb'));
const map = canonicalNodeMapFromObject(root);
const { clip: retargeted } = retargetClip(clip, map, {
targetRest: canonicalRestMapFromObject(root),
});
const scan = hipsTiltAcrossClip(root, map.get('Hips'), retargeted);
expect(scan).not.toBeNull();
// Samba legitimately swings the hips to ~24°; the soldier locomotion
// clips sit far lower. The bound clears the dance with margin and is
// nowhere near the ~90° fallen floor the bug produced.
expect(scan.max).toBeLessThan(UPRIGHT_TOLERANCE_DEG + 5);
});
}
it('liftHipsUpright is idempotent and a no-op on already-upright data', () => {
// The committed clips are already corrected, so re-running the lift must
// not move them — proving the build step can be re-applied safely.
for (const name of UPRIGHT_FIX_CLIPS) {
const json = JSON.parse(readFileSync(clipPath(name), 'utf8'));
const result = liftHipsUpright(json);
expect(result.changed).toBe(false);
}
// A genuinely healthy featured clip is untouched too.
const idle = JSON.parse(readFileSync(clipPath('idle'), 'utf8'));
expect(liftHipsUpright(idle).changed).toBe(false);
});
});