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
// @ts-check
// Motion seeding: turn a text prompt from data/motion-prompts.json into a clip
// the animation library can serve, and refuse the ones that would embarrass us.
//
// The text2motion worker (workers/model-text2motion) already returns a three.js
// AnimationClip JSON on the canonical Wolf3D skeleton, so no format conversion
// is needed: a generated clip's track names are a strict subset of the Mixamo
// library's (the 23 body bones, no finger bones). What IS needed is a gate.
// A motion-diffusion sampler fails in ways that look fine in JSON and terrible
// on a rig: a frozen clip with no motion, a limb that snaps a full turn between
// two frames, a "walk" whose planted foot slides across the floor, quaternions
// that drifted off the unit sphere, a NaN that turns the whole avatar inside
// out. Every one of those is measurable here, before anything is published.
//
// The foot-slide check is real forward kinematics, not a heuristic on the hips:
// CANONICAL_REST_POSITION + CANONICAL_PARENT + CANONICAL_REST_WORLD
// (src/animation-canonical-rest.js, generated from the reference rig) are enough
// to replay a clip's world-space joint positions frame by frame. We find the
// planted foot per frame (the lower toe), measure how far it travels across the
// floor while planted, and compare that against the stride the clip actually
// covers. A clip whose planted foot outruns its own stride is skating.
import { readFileSync } from 'node:fs';
import { createHash } from 'node:crypto';
import { fileURLToPath } from 'node:url';
import {
CANONICAL_REST,
CANONICAL_REST_WORLD,
CANONICAL_REST_POSITION,
CANONICAL_PARENT,
} from '../../src/animation-canonical-rest.js';
const PROMPTS_PATH = fileURLToPath(new URL('../../data/motion-prompts.json', import.meta.url));
/** The prompt library is data, never a hardcoded list (work order B6). */
function loadPromptLibrary() {
const parsed = JSON.parse(readFileSync(PROMPTS_PATH, 'utf8'));
const prompts = Array.isArray(parsed?.prompts) ? parsed.prompts : [];
return Object.freeze({
version: parsed?.version ?? null,
defaults: Object.freeze(parsed?.defaults ?? {}),
categories: Object.freeze(parsed?.categories ?? {}),
prompts: Object.freeze(prompts.map((p) => Object.freeze({ ...p }))),
});
}
let cachedLibrary = null;
export function motionPromptLibrary() {
if (!cachedLibrary) cachedLibrary = loadPromptLibrary();
return cachedLibrary;
}
export function motionPrompts() {
return motionPromptLibrary().prompts;
}
export function motionPromptById(id) {
return motionPrompts().find((p) => p.id === id) ?? null;
}
// Generated clips carry their own prefix so the library, the gallery and every
// report can tell a sampled clip from the `mx-` Mixamo import at a glance.
export const GENERATED_PREFIX = 'gen-';
export const GENERATED_CLIP_DIR = 'animations/library/clips/';
export const LIBRARY_MANIFEST_KEY = 'animations/library/manifest.json';
/** Stable, collision-free clip name: gen-<prompt id>-<12 hex of the task id>. */
export function libraryClipName(promptId, taskId) {
const slug = String(promptId)
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-|-$/g, '')
.slice(0, 48);
const hash = createHash('sha256').update(String(taskId)).digest('hex').slice(0, 12);
return `${GENERATED_PREFIX}${slug}-${hash}`;
}
export function isGeneratedClipName(name) {
return typeof name === 'string' && name.startsWith(GENERATED_PREFIX);
}
// ── Minimal quaternion / vector math ────────────────────────────────────────
// Four operations on 4 floats each. three.js is a browser dependency and far
// too heavy to pull into a cron for this, and a dependency for four functions
// is the kind of thing CLAUDE.md tells us to just write.
function quatMul(a, b) {
const [ax, ay, az, aw] = a;
const [bx, by, bz, bw] = b;
return [
aw * bx + ax * bw + ay * bz - az * by,
aw * by - ax * bz + ay * bw + az * bx,
aw * bz + ax * by - ay * bx + az * bw,
aw * bw - ax * bx - ay * by - az * bz,
];
}
function quatConjugate(q) {
return [-q[0], -q[1], -q[2], q[3]];
}
function quatApply(q, v) {
const [qx, qy, qz, qw] = q;
const [vx, vy, vz] = v;
// t = 2 * cross(q.xyz, v); v' = v + qw * t + cross(q.xyz, t)
const tx = 2 * (qy * vz - qz * vy);
const ty = 2 * (qz * vx - qx * vz);
const tz = 2 * (qx * vy - qy * vx);
return [
vx + qw * tx + (qy * tz - qz * ty),
vy + qw * ty + (qz * tx - qx * tz),
vz + qw * tz + (qx * ty - qy * tx),
];
}
function quatLength(q) {
return Math.hypot(q[0], q[1], q[2], q[3]);
}
/** Angle in radians between two unit quaternions, sign-insensitive (q and -q are the same rotation). */
function quatAngleBetween(a, b) {
const dot = Math.abs(a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3]);
return 2 * Math.acos(Math.min(1, dot));
}
// ── Clip access ─────────────────────────────────────────────────────────────
function tracksByName(clip) {
const map = new Map();
for (const track of clip?.tracks ?? []) {
if (track && typeof track.name === 'string') map.set(track.name, track);
}
return map;
}
function boneOf(trackName) {
const dot = trackName.lastIndexOf('.');
return dot === -1 ? trackName : trackName.slice(0, dot);
}
/**
* Sample a quaternion track at frame index i, falling back to the bone's rest
* rotation when the clip does not animate it (an unanimated bone holds bind
* pose, exactly as three.js plays it).
*/
function quatAt(track, i, restQuat) {
if (!track) return restQuat;
const n = Math.floor(track.values.length / 4);
if (n === 0) return restQuat;
const k = Math.min(Math.max(i, 0), n - 1) * 4;
return [track.values[k], track.values[k + 1], track.values[k + 2], track.values[k + 3]];
}
function vec3At(track, i, fallback) {
if (!track) return fallback;
const n = Math.floor(track.values.length / 3);
if (n === 0) return fallback;
const k = Math.min(Math.max(i, 0), n - 1) * 3;
return [track.values[k], track.values[k + 1], track.values[k + 2]];
}
// Bone-local rest offset, expressed in the parent's world rest frame. The
// generated table stores WORLD rest positions, so the local offset is the world
// delta rotated back into the parent's bind orientation.
const LOCAL_REST_OFFSET = (() => {
const out = {};
for (const bone of Object.keys(CANONICAL_REST_POSITION)) {
const parent = CANONICAL_PARENT[bone];
const here = CANONICAL_REST_POSITION[bone];
if (!parent) {
out[bone] = [...here];
continue;
}
const there = CANONICAL_REST_POSITION[parent];
const delta = [here[0] - there[0], here[1] - there[1], here[2] - there[2]];
const parentWorld = CANONICAL_REST_WORLD[parent] ?? [0, 0, 0, 1];
out[bone] = quatApply(quatConjugate(parentWorld), delta);
}
return Object.freeze(out);
})();
/** Bones ordered parents-before-children so one pass of FK is enough. */
const FK_ORDER = (() => {
const order = [];
const seen = new Set();
const visit = (bone) => {
if (seen.has(bone)) return;
const parent = CANONICAL_PARENT[bone];
if (parent) visit(parent);
seen.add(bone);
order.push(bone);
};
for (const bone of Object.keys(CANONICAL_PARENT)) visit(bone);
return Object.freeze(order);
})();
/**
* World-space joint positions for one frame of a clip.
* @returns {Record<string, [number, number, number]>}
*/
export function forwardKinematicsFrame(clip, frameIndex) {
const tracks = tracksByName(clip);
const worldQuat = {};
const worldPos = {};
for (const bone of FK_ORDER) {
const local = quatAt(tracks.get(`${bone}.quaternion`), frameIndex, CANONICAL_REST[bone] ?? [0, 0, 0, 1]);
const parent = CANONICAL_PARENT[bone];
if (!parent) {
worldQuat[bone] = local;
worldPos[bone] = vec3At(tracks.get(`${bone}.position`), frameIndex, CANONICAL_REST_POSITION[bone] ?? [0, 0, 0]);
continue;
}
const pq = worldQuat[parent] ?? [0, 0, 0, 1];
const pp = worldPos[parent] ?? [0, 0, 0];
const offset = quatApply(pq, LOCAL_REST_OFFSET[bone] ?? [0, 0, 0]);
worldQuat[bone] = quatMul(pq, local);
worldPos[bone] = [pp[0] + offset[0], pp[1] + offset[1], pp[2] + offset[2]];
}
return worldPos;
}
function frameCount(clip) {
let frames = 0;
for (const track of clip?.tracks ?? []) {
const times = track?.times;
if (Array.isArray(times) || ArrayBuffer.isView(times)) frames = Math.max(frames, times.length);
}
return frames;
}
/**
* Foot-contact metrics over the whole clip.
*
* For each frame the lower toe is treated as the planted foot. While a foot
* stays planted across consecutive frames, the horizontal distance it covers is
* slide. `slidePerStride` compares that slide against the horizontal distance
* the hips actually travelled: a clip that moves the body forward earns its foot
* travel, a clip that pins the body and skates the feet does not.
*/
export function footContactMetrics(clip) {
const frames = frameCount(clip);
if (frames < 2) {
return { frames, slide: 0, stride: 0, slidePerStride: 0, plantedFrames: 0, floorY: 0 };
}
// One FK pass, kept, so the floor level can be derived from the whole clip
// before any frame is judged against it.
const lower = new Array(frames);
const hipsY = new Array(frames);
const hips = new Array(frames);
for (let i = 0; i < frames; i += 1) {
const world = forwardKinematicsFrame(clip, i);
const left = world.LeftToeBase ?? world.LeftFoot;
const right = world.RightToeBase ?? world.RightFoot;
hips[i] = world.Hips ?? null;
hipsY[i] = world.Hips ? world.Hips[1] : Number.NaN;
if (!left || !right) {
lower[i] = null;
continue;
}
lower[i] = left[1] <= right[1] ? { side: 'Left', pos: left } : { side: 'Right', pos: right };
}
// The floor is where this clip's feet actually get to, not y=0: a clip can be
// authored with any root offset, and the reference rig's toes sit above zero.
let floorY = Infinity;
for (const entry of lower) {
if (entry && Number.isFinite(entry.pos[1])) floorY = Math.min(floorY, entry.pos[1]);
}
if (!Number.isFinite(floorY)) floorY = 0;
let slide = 0;
let plantedFrames = 0;
let prevPlanted = null;
let prevPos = null;
let hipsPath = 0;
let hipsFirst = null;
let hipsLast = null;
let prevHips = null;
for (let i = 0; i < frames; i += 1) {
const h = hips[i];
if (h) {
if (!hipsFirst) hipsFirst = h;
hipsLast = h;
if (prevHips) hipsPath += Math.hypot(h[0] - prevHips[0], h[2] - prevHips[2]);
prevHips = h;
}
const entry = lower[i];
// A foot only counts as planted when it is actually down on the floor AND
// the body is upright over it. Without that test a breakdance flair, a
// fall, a crawl or any aerial reads as a foot skating across the ground,
// because the "lower" foot is simply the one that happens to be less high.
const grounded =
entry != null &&
entry.pos[1] - floorY <= MOTION_GATE.PLANT_BAND &&
Number.isFinite(hipsY[i]) &&
hipsY[i] - floorY >= MOTION_GATE.UPRIGHT_HIP_HEIGHT;
if (!grounded) {
prevPlanted = null;
prevPos = null;
continue;
}
if (entry.side === prevPlanted && prevPos) {
slide += Math.hypot(entry.pos[0] - prevPos[0], entry.pos[2] - prevPos[2]);
plantedFrames += 1;
}
prevPlanted = entry.side;
prevPos = entry.pos;
}
// Stride credit is the greater of net displacement and the path the hips
// walked: a clip that turns in place still travels, and a clip that moves out
// and back should not be scored as if it never moved.
const net =
hipsFirst && hipsLast ? Math.hypot(hipsLast[0] - hipsFirst[0], hipsLast[2] - hipsFirst[2]) : 0;
const stride = Math.max(net, hipsPath);
// A stationary clip (an idle, a wave) has no stride to earn slide against, so
// it is scored on absolute slide instead of a ratio against roughly zero.
const slidePerStride = stride > 0.05 ? slide / stride : slide;
return { frames, slide, stride, slidePerStride, plantedFrames, floorY };
}
// Joints a viewer actually watches. A discontinuity anywhere in the skeleton
// shows up at one of these, and they are the extremities where a bad frame is
// most visible.
const WITNESS_JOINTS = Object.freeze([
'LeftHand',
'RightHand',
'LeftToeBase',
'RightToeBase',
'Head',
'LeftFoot',
'RightFoot',
'Hips',
]);
/**
* World-space smoothness and liveliness.
*
* This is deliberately NOT a check on the local quaternion tracks. The sampler
* routinely emits a 180 degree twist about a bone's own axis which the child
* bone cancels: measured on the local rotations that looks like a catastrophic
* pop, and it is invisible on the rendered mesh (a shoulder + forearm pair can
* flip together on a third of the frames of an idle clip while the hand never
* moves more than a centimetre a frame). Judging a clip by what the viewer sees
* means judging joint POSITIONS.
*
* continuity: the largest single-frame joint step over that joint's own 95th
* percentile step. Scale-free, so a sprint and an idle are held to
* the same standard, and a real discontinuity stands out no matter
* how fast the clip is.
* travel: the longest path any witness joint walks over the whole clip,
* which separates an animation from a static pose.
*/
export function worldMotionMetrics(clip) {
const frames = frameCount(clip);
if (frames < 3) return { frames, continuity: 0, continuityJoint: null, continuityFrame: -1, travel: 0 };
const poses = new Array(frames);
for (let i = 0; i < frames; i += 1) poses[i] = forwardKinematicsFrame(clip, i);
let continuity = 0;
let continuityJoint = null;
let continuityFrame = -1;
let travel = 0;
for (const joint of WITNESS_JOINTS) {
const steps = [];
let path = 0;
let worst = 0;
let worstAt = -1;
for (let i = 1; i < frames; i += 1) {
const a = poses[i - 1][joint];
const b = poses[i][joint];
if (!a || !b) continue;
const d = Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
if (!Number.isFinite(d)) continue;
steps.push(d);
path += d;
if (d > worst) {
worst = d;
worstAt = i;
}
}
if (steps.length < 8) continue;
travel = Math.max(travel, path);
const sorted = [...steps].sort((x, y) => x - y);
const p95 = sorted[Math.floor(0.95 * (sorted.length - 1))];
// Floor the reference: a joint that barely moves all clip must not be able
// to manufacture a huge ratio out of one millimetre of noise.
const ratio = worst / Math.max(p95, 0.01);
if (ratio > continuity) {
continuity = ratio;
continuityJoint = joint;
continuityFrame = worstAt;
}
}
return { frames, continuity, continuityJoint, continuityFrame, travel };
}
// ── The gate ────────────────────────────────────────────────────────────────
// Every threshold is a measured property of a clip that plays correctly on the
// reference rig, not a taste call.
export const MOTION_GATE = Object.freeze({
// The body chain a retarget needs to produce a readable pose. Fingers are
// deliberately absent: the sampler does not animate them and a bind-pose hand
// is correct, not a defect.
REQUIRED_BONES: Object.freeze([
'Hips',
'Spine',
'Spine1',
'Spine2',
'Neck',
'Head',
'LeftArm',
'LeftForeArm',
'RightArm',
'RightForeArm',
'LeftUpLeg',
'LeftLeg',
'LeftFoot',
'RightUpLeg',
'RightLeg',
'RightFoot',
]),
MIN_FRAMES: 16,
MIN_DURATION: 0.5,
MAX_DURATION: 12,
// The sampler is asked for a duration; more than a second off means the clip
// is not the clip we ordered.
DURATION_TOLERANCE: 1.0,
// Unit-quaternion drift. Past this the rotation is no longer a rotation and
// three.js renders a sheared limb.
QUAT_NORM_EPSILON: 0.02,
// Largest single-frame joint step, over that joint's own p95 step. Measured
// across a 60-clip sample of the authored library the worst real clip scores
// 5.79 (a heavy push) and the median 1.69, so 6.5 leaves headroom above
// anything an animator shipped while still catching a true discontinuity.
MAX_WORLD_STEP_RATIO: 6.5,
// Longest path any witness joint walks, in metres. The authored library's
// static POSE assets score 0.00 and its quietest real animation 0.11, so this
// floor rejects a collapsed sampler without touching a subtle idle.
MIN_WORLD_TRAVEL: 0.35,
// How close to the clip's own floor a foot must be to count as planted.
PLANT_BAND: 0.06,
// How high the hips must sit above that floor for the body to be standing on
// the planted foot at all. Below this the clip is floor work (a fall, a
// crawl, a breakdance flair) where no foot bears weight and foot travel is
// choreography rather than skating.
UPRIGHT_HIP_HEIGHT: 0.55,
// Planted-foot slide, as a multiple of the stride the clip actually covers.
MAX_SLIDE_PER_STRIDE: 0.85,
// Absolute slide ceiling in metres for a clip that does not travel.
MAX_STATIONARY_SLIDE: 0.55,
// Rest-basis check, and the rule whose absence let 133 clips ship with their
// legs folded up over the body. Every other threshold here measures a clip
// against ITSELF, so a clip expressed in the wrong rest basis is perfectly
// self-consistent and passes all of them.
//
// It takes TWO signals, because neither alone is safe. A clip that is never
// upright is suspicious but might be a pushup or a swim stroke, which are
// prone by definition. A clip whose upper legs sit near identity is
// suspicious but a single published clip reached 148 degrees. Requiring both
// leaves real margin on the measured distributions: over the published set,
// clips in the wrong basis peak at 0.435 m of head clearance with a median
// leg angle of 23.6 degrees, while the same clips rebased clear 0.939 m at
// p05 and never fall below 74.9 degrees.
MIN_UPRIGHT_GAP: 0.5,
MIN_LEG_BASIS_DEGREES: 60,
// Frames sampled when looking for the clip's most upright moment. Twelve is
// enough to catch a squat standing back up without walking every frame.
UPRIGHT_SAMPLES: 12,
});
function isFiniteSeq(seq) {
for (let i = 0; i < seq.length; i += 1) {
if (!Number.isFinite(seq[i])) return false;
}
return true;
}
/**
* Decide whether a generated clip is fit to publish.
*
* @param {any} clip raw AnimationClip JSON from the text2motion worker
* @param {{ expectedDuration?: number, loop?: boolean }} [opts]
* @returns {{ ok: boolean, reasons: string[], metrics: Record<string, number> }}
*/
export function gateMotionClip(clip, opts = {}) {
const reasons = [];
const metrics = {};
const tracks = Array.isArray(clip?.tracks) ? clip.tracks : null;
if (!tracks || tracks.length === 0) {
return { ok: false, reasons: ['no_tracks'], metrics };
}
const duration = Number(clip?.duration);
metrics.duration = Number.isFinite(duration) ? duration : 0;
if (!Number.isFinite(duration) || duration < MOTION_GATE.MIN_DURATION || duration > MOTION_GATE.MAX_DURATION) {
reasons.push('duration_out_of_range');
}
const expected = Number(opts.expectedDuration);
if (Number.isFinite(expected) && Number.isFinite(duration)) {
metrics.durationDelta = Math.abs(duration - expected);
if (metrics.durationDelta > MOTION_GATE.DURATION_TOLERANCE) reasons.push('duration_mismatch');
}
const names = new Set(tracks.map((t) => t?.name).filter((n) => typeof n === 'string'));
const bones = new Set([...names].map(boneOf));
const missing = MOTION_GATE.REQUIRED_BONES.filter((b) => !bones.has(b));
metrics.trackCount = tracks.length;
metrics.missingBones = missing.length;
if (missing.length) reasons.push(`missing_bones:${missing.slice(0, 4).join(',')}`);
// A track naming a bone the canonical skeleton does not have would land on
// nothing after retarget, so it is a format failure rather than a quality one.
const foreign = [...bones].filter((b) => !(b in CANONICAL_PARENT));
metrics.foreignBones = foreign.length;
if (foreign.length) reasons.push(`foreign_bones:${foreign.slice(0, 3).join(',')}`);
let frames = 0;
let worstNormDrift = 0;
let worstJump = 0;
let totalMotion = 0;
let nonFinite = false;
let nonMonotonic = false;
for (const track of tracks) {
const times = track?.times ?? [];
const values = track?.values ?? [];
if (!isFiniteSeq(times) || !isFiniteSeq(values)) {
nonFinite = true;
continue;
}
frames = Math.max(frames, times.length);
for (let i = 1; i < times.length; i += 1) {
if (times[i] < times[i - 1]) {
nonMonotonic = true;
break;
}
}
if (track.type !== 'quaternion') continue;
let prev = null;
const n = Math.floor(values.length / 4);
for (let i = 0; i < n; i += 1) {
const q = [values[i * 4], values[i * 4 + 1], values[i * 4 + 2], values[i * 4 + 3]];
worstNormDrift = Math.max(worstNormDrift, Math.abs(quatLength(q) - 1));
if (prev) {
const step = quatAngleBetween(prev, q);
worstJump = Math.max(worstJump, step);
totalMotion += step;
}
prev = q;
}
}
metrics.frames = frames;
metrics.quatNormDrift = worstNormDrift;
// Reported, never gated: local-rotation travel is inflated by twist flips the
// child bone cancels, so it describes the representation, not the animation.
metrics.maxFrameJumpRad = worstJump;
metrics.totalMotionRad = totalMotion;
if (nonFinite) reasons.push('non_finite_keyframes');
if (nonMonotonic) reasons.push('non_monotonic_times');
if (frames < MOTION_GATE.MIN_FRAMES) reasons.push('too_few_frames');
if (worstNormDrift > MOTION_GATE.QUAT_NORM_EPSILON) reasons.push('quaternions_not_normalized');
// World-space checks only mean something once the skeleton itself is sane,
// and running FK over NaN values would only produce NaN metrics.
if (!nonFinite && !missing.length && !foreign.length) {
const world = worldMotionMetrics(clip);
metrics.worldStepRatio = world.continuity;
metrics.worldTravel = world.travel;
metrics.worstJoint = world.continuityJoint;
if (world.continuity > MOTION_GATE.MAX_WORLD_STEP_RATIO) reasons.push(`world_discontinuity:${world.continuityJoint}`);
if (world.travel < MOTION_GATE.MIN_WORLD_TRAVEL) reasons.push('frozen_clip');
const foot = footContactMetrics(clip);
metrics.footSlide = foot.slide;
metrics.stride = foot.stride;
metrics.slidePerStride = foot.slidePerStride;
const travels = foot.stride > 0.05;
if (travels && foot.slidePerStride > MOTION_GATE.MAX_SLIDE_PER_STRIDE) reasons.push('foot_sliding');
if (!travels && foot.slide > MOTION_GATE.MAX_STATIONARY_SLIDE) reasons.push('foot_sliding_in_place');
// Rest basis. A clip that never gets upright AND whose upper legs never
// leave the identity basis is not choreography, it is a clip expressed in
// the wrong rest frame, and it will play with the legs folded over the
// body on every rig. Either signal alone would reject real prone motion,
// so both have to agree.
const upright = maxUprightGap(clip);
const legs = legBasisDegrees(clip);
metrics.uprightGap = upright;
metrics.legBasisDegrees = legs;
if (
Number.isFinite(upright) &&
Number.isFinite(legs) &&
upright < MOTION_GATE.MIN_UPRIGHT_GAP &&
legs < MOTION_GATE.MIN_LEG_BASIS_DEGREES
) {
reasons.push('wrong_rest_basis');
}
}
return { ok: reasons.length === 0, reasons, metrics };
}
// ── Publishing shape ────────────────────────────────────────────────────────
/**
* Rewrite a raw generated clip into the exact object the library already serves:
* same top-level keys, same track shape, library-style name, and a userData
* record of where the clip came from (the Mixamo import carries an empty
* userData object, so the key is expected and the extra provenance is additive).
*/
export function toLibraryClip(raw, { name, promptId, prompt, category, loop, taskId }) {
return {
name,
duration: raw.duration,
tracks: raw.tracks,
uuid: raw.uuid,
blendMode: raw.blendMode ?? 0,
userData: {
source: 'text2motion',
basis: CLIP_BASIS,
prompt_id: promptId,
prompt,
category,
loop: Boolean(loop),
task_id: taskId,
generated_at: new Date().toISOString(),
},
};
}
/** A manifest row in the shape api/animations/library.js already returns. */
export function manifestEntryFor(clip, { label, icon, loop, bytes, url, thumb }) {
return {
name: clip.name,
label,
icon: icon || '🎬',
loop: Boolean(loop),
duration: clip.duration,
bytes,
url,
thumb: thumb ?? null,
};
}
/**
* Merge generated rows into the existing manifest without disturbing the Mixamo
* import: entries are matched by name, so re-running a batch replaces a row
* rather than duplicating it, and the array stays stably ordered (the library
* endpoint pages it by index, so a reorder would shuffle every caller's page).
*/
export function mergeManifest(existing, additions) {
const out = Array.isArray(existing) ? [...existing] : [];
const index = new Map(out.map((entry, i) => [entry?.name, i]));
for (const entry of additions) {
const at = index.get(entry.name);
if (at === undefined) {
index.set(entry.name, out.length);
out.push(entry);
} else {
out[at] = entry;
}
}
return out;
}
// ── Rotating free subset (work order B8) ────────────────────────────────────
//
// Policy: the generated collection is paid by default, and a fixed-size subset
// is free for one epoch at a time. The subset is chosen by hashing the clip name
// together with the epoch number, so it is deterministic (every server instance
// and the client agree without coordination or a DB write), stable for the whole
// epoch (a visitor does not watch a clip's price flicker on reload), and evenly
// spread over time (each clip's hash ordering differs per epoch, so the free
// slot rotates rather than favouring the same names).
export const FREE_ROTATION = Object.freeze({
EPOCH_MS: 7 * 24 * 60 * 60 * 1000,
SIZE: 12,
});
export function rotationEpoch(now = Date.now()) {
return Math.floor(now / FREE_ROTATION.EPOCH_MS);
}
function rotationRank(name, epoch) {
const digest = createHash('sha256').update(`${epoch}:${name}`).digest();
return digest.readUInt32BE(0);
}
/**
* The names free this epoch, given every generated clip name in the collection.
* @param {string[]} names
*/
export function freeClipNames(names, { now = Date.now(), size = FREE_ROTATION.SIZE } = {}) {
const epoch = rotationEpoch(now);
return [...new Set(names)]
.map((name) => ({ name, rank: rotationRank(name, epoch) }))
.sort((a, b) => a.rank - b.rank || (a.name < b.name ? -1 : 1))
.slice(0, Math.max(0, size))
.map((entry) => entry.name);
}
export function isFreeThisEpoch(name, allNames, opts = {}) {
return freeClipNames(allNames, opts).includes(name);
}
// ── Lane assertion ──────────────────────────────────────────────────────────
//
// The GCP provider packs its job id as base64url JSON naming the worker it
// dispatched to (packJobId in api/_providers/gcp.js). Reading that back out is
// how a bulk run proves it is spending credits on our own fleet rather than
// quietly billing a paid third party for a few hundred clips. Being unable to
// tell which lane billed a job is itself a reason to stop, so an unreadable
// envelope throws rather than passing.
export function decodeJobEnvelope(jobId) {
try {
const parsed = JSON.parse(Buffer.from(String(jobId), 'base64url').toString('utf8'));
return parsed && typeof parsed === 'object' ? parsed : null;
} catch {
return null;
}
}
export function assertSelfHostedLane(jobId) {
const envelope = decodeJobEnvelope(jobId);
if (!envelope) throw new Error('lane assertion failed: job id is not a provider envelope');
if (envelope.mode !== 'text2motion') throw new Error(`lane assertion failed: mode ${envelope.mode}`);
let host;
try {
host = new URL(envelope.baseUrl).host;
} catch {
throw new Error(`lane assertion failed: unusable baseUrl ${envelope.baseUrl}`);
}
if (!/\.run\.app$/.test(host)) {
throw new Error(`lane assertion failed: ${host} is not a self-hosted Cloud Run lane`);
}
if (!/^model-text2motion/.test(host)) {
throw new Error(`lane assertion failed: unexpected worker ${host}`);
}
return { host, taskId: envelope.taskId };
}
// ── Loop seams ──────────────────────────────────────────────────────────────
//
// A motion-diffusion sampler does not produce seamless loops: it samples a
// window, and the last frame has no reason to meet the first. Measured on real
// output, a generated walk ends 25 cm (per joint, hips-relative) away from where
// it started, while the authored library's loop clips sit at 0.000. Since 41% of
// data/motion-prompts.json is tagged `loop`, publishing generated clips as loops
// without closing the seam would ship a library that visibly pops every cycle.
//
// Seam distance is measured in world space, hips-relative, for the same reason
// the continuity test is: comparing the first and last LOCAL rotations reports a
// 178 degree seam on a clip whose joints are actually 2.9 cm apart, because the
// twist flips the child bone cancels land in that comparison too.
const SEAM_JOINTS = Object.freeze([
'LeftHand',
'RightHand',
'LeftToeBase',
'RightToeBase',
'Head',
'LeftFoot',
'RightFoot',
'Spine2',
]);
/**
* How far frame `a` is from frame `b`, per joint, ignoring where the body has
* travelled to (a travelling walk loop is still a loop).
*/
function seamDistanceBetween(clip, a, b) {
const pa = forwardKinematicsFrame(clip, a);
const pb = forwardKinematicsFrame(clip, b);
const ha = pa.Hips;
const hb = pb.Hips;
if (!ha || !hb) return Infinity;
let worst = 0;
for (const joint of SEAM_JOINTS) {
if (!pa[joint] || !pb[joint]) continue;
const d = Math.hypot(
pb[joint][0] - hb[0] - (pa[joint][0] - ha[0]),
pb[joint][1] - hb[1] - (pa[joint][1] - ha[1]),
pb[joint][2] - hb[2] - (pa[joint][2] - ha[2]),
);
worst = Math.max(worst, d);
}
return worst;
}
/** World-space seam of a clip as it stands: frame 0 against the final frame. */
export function loopSeamDistance(clip) {
const frames = frameCount(clip);
if (frames < 2) return 0;
return seamDistanceBetween(clip, 0, frames - 1);
}
function slerp(a, b, t) {
let [bx, by, bz, bw] = b;
let dot = a[0] * bx + a[1] * by + a[2] * bz + a[3] * bw;
// Take the short way round; q and -q are the same rotation.
if (dot < 0) {
bx = -bx;
by = -by;
bz = -bz;
bw = -bw;
dot = -dot;
}
if (dot > 0.9995) {
const out = [
a[0] + (bx - a[0]) * t,
a[1] + (by - a[1]) * t,
a[2] + (bz - a[2]) * t,
a[3] + (bw - a[3]) * t,
];
const len = Math.hypot(...out) || 1;
return out.map((v) => v / len);
}
const theta = Math.acos(Math.min(1, dot));
const sin = Math.sin(theta);
const wa = Math.sin((1 - t) * theta) / sin;
const wb = Math.sin(t * theta) / sin;
return [a[0] * wa + bx * wb, a[1] * wa + by * wb, a[2] * wa + bz * wb, a[3] * wa + bw * wb];
}
// ── Rest basis ──────────────────────────────────────────────────────────────
//
// Library clips are authored in the `cz` rig's rest basis: every per-bone
// quaternion is a local rotation RELATIVE TO THAT REST, which is why a Mixamo
// walk carries roughly 180 degrees on each upper leg (cz rests with the leg
// bones pointing up, so the clip has to turn them down). Everything downstream
// assumes that basis: forwardKinematicsFrame below composes the clip's
// quaternions onto CANONICAL_REST, and src/animation-retarget.js builds its bind
// correction from cz to whatever rig the page loaded.
//
// The text2motion lane does not produce that basis. Its clips come out of a
// Kabsch fit against the HumanML3D skeleton's own raw offsets
// (workers/model-text2motion/mdm_sampler.py `_positions_to_local_quats`), where
// a joint at rest yields the IDENTITY quaternion, and smpl_to_clip.py's own
// `rest_offsets` hook, the place that difference was meant to be calibrated
// away, was never given a value. So a generated clip carries 29 degrees on the
// upper legs where an authored one carries 176, and playing it composes the
// missing half-turn into the legs: measured on all 133 clips published before
// 2026-09-09, forward kinematics puts the FEET AT 1.71 m and the HEAD AT 1.45 m.
// Every one of them plays with the legs folded up over the body.
//
// The conversion is bindCorrections (src/animation-retarget.js) with the source
// rest set to identity, which is what the Kabsch formulation means:
//
// L = Rt * Wt^-1 * Ws * Rs^-1 -> Rt * Wt^-1 (Ws = Rs = identity)
// R = Ws^-1 * Wt -> Wt
// q <- L * q * R
//
// Verified against the whole published set: head-above-feet goes from -0.26 m to
// +1.38 m, and 127 of 133 clear a 0.6 m upright bar. The six that do not are a
// pushup, a squat, a swim stroke, a crouch, a sneak and a meditation, which are
// low-posture by definition and correct as they are.
// ── The source skeleton's rest SHAPE (added 2026-09-18) ─────────────────────
//
// Treating the generator's rest as "identity, in the same shape as cz" fixed the
// legs and nothing else, and it was measured, not guessed: rendered on the
// default rig on 2026-09-18, every generated clip, including all 39 published by
// the repair pass, played with the head thrown back about 90 degrees and the
// arms raised where they should hang. The legs were right because the one thing
// the two skeletons agree on is that legs point down.
//
// The Kabsch fit in mdm_sampler.py measures each joint's rotation against
// HumanML3D's `paramUtil.t2m_raw_offsets`, and those are directions, not a
// posed human: the upper arm, forearm and hand hang STRAIGHT DOWN, the collars
// point straight out, and the head sits straight FORWARD of the neck. The cz rig
// rests in a T-pose with the head above the neck. So a clip whose arms hang at
// the sides carries identity on the arms, which the identity-shape conversion
// played as a T-pose, and a clip whose head is upright carries a 90 degree
// rotation on the neck that turns "forward" into "up", which it played on top
// of a neck that already points up.
//
// The general conversion aligns the two rest shapes per joint. For joint j, A_j
// is the rotation that carries the cz rest directions of j's children onto the
// source's rest directions of the same children. Then a source world rotation
// G_s maps onto the target as G_t = G_s * A_j * Wt_j, which puts every child
// exactly where the source put it, and in local terms:
//
// q_t = (Wt_p^-1 * A_p^-1) * q_s * (A_j * Wt_j)
//
// With A = identity this is exactly the old conversion, which is why it was
// right for the legs. A leaf joint (hand, head, toe) has no children in the
// 22-joint source, so it carries identity there and inherits its parent's A,
// which leaves it at its cz rest relative to its parent: the only honest pose
// for a joint the source never measured.
// t2m_raw_offsets from HumanML3D's paramUtil, keyed by the cz bone each SMPL
// joint maps to (workers/model-text2motion/smpl_to_clip.py SMPL_TO_WOLF3D):
// the direction from the parent joint to this joint in the source's rest.
// Verified 2026-09-18 by running source forward kinematics over a live idle
// take with these offsets: head above neck, arms hanging, toes forward.
export const HUMANML3D_REST_DIRECTION = Object.freeze({
Spine: [0, 1, 0],
Spine1: [0, 1, 0],
Spine2: [0, 1, 0],
Neck: [0, 1, 0],
Head: [0, 0, 1],
LeftShoulder: [1, 0, 0],
RightShoulder: [-1, 0, 0],
LeftArm: [0, -1, 0],
RightArm: [0, -1, 0],
LeftForeArm: [0, -1, 0],
RightForeArm: [0, -1, 0],
LeftHand: [0, -1, 0],
RightHand: [0, -1, 0],
LeftUpLeg: [1, 0, 0],
RightUpLeg: [-1, 0, 0],
LeftLeg: [0, -1, 0],
RightLeg: [0, -1, 0],
LeftFoot: [0, -1, 0],
RightFoot: [0, -1, 0],
LeftToeBase: [0, 0, 1],
RightToeBase: [0, 0, 1],
});
// For a joint with several children, the child whose direction is matched
// exactly; the others only settle the twist about it.
const PRIMARY_CHILD = Object.freeze({ Hips: 'Spine', Spine2: 'Neck' });
function normalize(v) {
const len = Math.hypot(v[0], v[1], v[2]) || 1;
return [v[0] / len, v[1] / len, v[2] / len];
}
function cross(a, b) {
return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
}
function dot(a, b) {
return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
}
/** Shortest-arc rotation carrying unit vector a onto unit vector b. */
function arcBetween(a, b) {
const d = dot(a, b);
if (d < -0.999999) {
// Opposite vectors: any perpendicular axis is a valid half turn.
const axis = normalize(Math.abs(a[0]) < 0.9 ? cross(a, [1, 0, 0]) : cross(a, [0, 1, 0]));
return [axis[0], axis[1], axis[2], 0];
}
const c = cross(a, b);
const q = [c[0], c[1], c[2], 1 + d];
const len = Math.hypot(...q);
return q.map((v) => v / len);
}
/** Rotation of `angle` radians about unit axis. */
function axisAngle(axis, angle) {
const s = Math.sin(angle / 2);
return [axis[0] * s, axis[1] * s, axis[2] * s, Math.cos(angle / 2)];
}
// A_j for every joint the source animates, computed once from the two rest
// skeletons. Parents are resolved before children (FK_ORDER), so a leaf can
// inherit its parent's alignment.
const REST_ALIGNMENT = (() => {
const mapped = new Set(['Hips', ...Object.keys(HUMANML3D_REST_DIRECTION)]);
const out = {};
for (const bone of FK_ORDER) {
if (!mapped.has(bone)) continue;
const here = CANONICAL_REST_POSITION[bone];
const kids = Object.keys(CANONICAL_PARENT).filter((b) => CANONICAL_PARENT[b] === bone && mapped.has(b));
if (kids.length === 0) {
out[bone] = out[CANONICAL_PARENT[bone]] ?? [0, 0, 0, 1];
continue;
}
const cz = (b) => normalize(CANONICAL_REST_POSITION[b].map((v, k) => v - here[k]));
const src = (b) => normalize(HUMANML3D_REST_DIRECTION[b]);
const primary = PRIMARY_CHILD[bone] ?? kids[0];
let align = arcBetween(cz(primary), src(primary));
const others = kids.filter((b) => b !== primary);
if (others.length) {
// Twist about the primary direction so the other children land as close
// to their source directions as a rotation about that axis allows.
const axis = src(primary);
let sinSum = 0;
let cosSum = 0;
for (const b of others) {
const moved = quatApply(align, cz(b));
const target = src(b);
const u = normalize(moved.map((v, k) => v - axis[k] * dot(moved, axis)));
const w = normalize(target.map((v, k) => v - axis[k] * dot(target, axis)));
sinSum += dot(cross(u, w), axis);
cosSum += dot(u, w);
}
align = quatMul(axisAngle(axis, Math.atan2(sinSum, cosSum)), align);
}
out[bone] = align;
}
return Object.freeze(out);
})();
// Stamped on every clip written in the library's basis, so a repair pass can
// tell a converted clip from one that predates the conversion and never
// rebases the same clip twice. v1 is the identity-shape conversion (legs right,
// arms and head wrong); a v1 clip is converted back to the source basis and
// forward again, which is exact because both conversions are fixed rotations.
export const CLIP_BASIS = 'canonical-rest-v2';
export const LEGACY_CLIP_BASIS = 'canonical-rest-v1';
function corrections(bone) {
const parent = CANONICAL_PARENT[bone];
const restWorld = CANONICAL_REST_WORLD[bone];
const align = REST_ALIGNMENT[bone];
if (!restWorld || !align) return null;
const parentWorld = parent ? CANONICAL_REST_WORLD[parent] ?? [0, 0, 0, 1] : [0, 0, 0, 1];
const parentAlign = parent ? REST_ALIGNMENT[parent] ?? [0, 0, 0, 1] : [0, 0, 0, 1];
return {
// q_t = L * q_s * R
L: quatMul(quatConjugate(parentWorld), quatConjugate(parentAlign)),
R: quatMul(align, restWorld),
// The v1 conversion, q1 = Wt_p^-1 * q_s * Wt_j, undone: q_s = Wt_p * q1 * Wt_j^-1.
undoL: parentWorld,
undoR: quatConjugate(restWorld),
};
}
/**
* Rewrite a clip's rotations from the generator's HumanML3D basis into the
* library's canonical (cz) rest basis, so it composes correctly with every other
* library clip. A clip stamped with the legacy v1 basis is converted back first.
* Returns a NEW clip; the input is not modified.
*
* @param {any} clip
* @returns {{ clip: any, rebasedTracks: number }}
*/
export function rebaseToCanonicalRest(clip) {
const source = clip?.tracks;
if (!Array.isArray(source)) return { clip, rebasedTracks: 0 };
const legacy = clip?.userData?.basis === LEGACY_CLIP_BASIS;
let rebasedTracks = 0;
const tracks = source.map((track) => {
const name = String(track?.name || '');
if (!name.endsWith('.quaternion')) return track;
const c = corrections(name.slice(0, name.lastIndexOf('.')));
if (!c) return track;
const values = Array.from(track.values ?? []);
for (let i = 0; i + 3 < values.length; i += 4) {
let q = [values[i], values[i + 1], values[i + 2], values[i + 3]];
if (legacy) q = quatMul(quatMul(c.undoL, q), c.undoR);
const out = quatMul(quatMul(c.L, q), c.R);
values[i] = out[0];
values[i + 1] = out[1];
values[i + 2] = out[2];
values[i + 3] = out[3];
}
rebasedTracks += 1;
return { ...track, values };
});
const userData = clip.userData && typeof clip.userData === 'object' ? { ...clip.userData } : undefined;
if (userData && legacy) delete userData.basis;
return { clip: { ...clip, tracks, ...(userData ? { userData } : {}) }, rebasedTracks };
}
/** True when a clip is not yet in the current library basis. */
export function needsRebase(clip) {
return clip?.userData?.basis !== CLIP_BASIS;
}
/**
* Mean angle, in degrees, that the upper-leg bones sit away from identity across
* the whole clip. The library's canonical rest points the leg bones up, so an
* authored clip has to turn them down and carries roughly 180 degrees on them;
* a clip still in the generator's identity-rest basis carries almost nothing.
*
* @param {any} clip
* @returns {number} NaN when the clip animates neither upper leg
*/
export function legBasisDegrees(clip) {
let total = 0;
let count = 0;
for (const track of clip?.tracks ?? []) {
if (!/^(Left|Right)UpLeg\.quaternion$/.test(String(track?.name || ''))) continue;
const values = track.values ?? [];
for (let i = 0; i + 3 < values.length; i += 4) {
total += (2 * Math.acos(Math.min(1, Math.abs(values[i + 3])) ) * 180) / Math.PI;
count += 1;
}
}
return count === 0 ? NaN : total / count;
}
/**
* The clip's most upright moment: the largest head clearance over the higher
* foot, in metres, sampled across the clip. Sampling rather than reading frame 0
* is what lets a squat or a bow through, since both stand up again.
*
* @param {any} clip
* @returns {number} NaN when the clip lacks the bones to judge
*/
export function maxUprightGap(clip) {
const frames = frameCount(clip);
if (frames === 0) return NaN;
const step = Math.max(1, Math.floor(frames / MOTION_GATE.UPRIGHT_SAMPLES));
let best = -Infinity;
for (let frame = 0; frame < frames; frame += step) {
const gap = uprightGap(clip, frame);
if (Number.isFinite(gap)) best = Math.max(best, gap);
}
return Number.isFinite(best) ? best : NaN;
}
/**
* Head height above the higher foot at a given frame, in metres. The cheapest
* check that a clip is the right way up, and the one whose absence let an
* entire inverted library through the gate.
*
* @param {any} clip
* @param {number} [frameIndex]
* @returns {number} NaN when the clip lacks the bones to judge
*/
export function uprightGap(clip, frameIndex = 0) {
const joints = forwardKinematicsFrame(clip, frameIndex);
const head = joints.Head?.[1];
const left = joints.LeftFoot?.[1];
const right = joints.RightFoot?.[1];
if (!Number.isFinite(head) || (!Number.isFinite(left) && !Number.isFinite(right))) return NaN;
return head - Math.max(Number.isFinite(left) ? left : -Infinity, Number.isFinite(right) ? right : -Infinity);
}
// ── Root drift ──────────────────────────────────────────────────────────────
//
// The text2motion lane's root translation channel carries a constant forward
// ramp that is not part of the motion. Measured over the 133 clips published on
// 2026-09-09, every clip travels forward at 0.2577 m/s (sd 0.0248) regardless of
// what was asked for: emotes fit a straight line to a residual of 0.0002 m, and
// idles (0.2502 m/s) drift FASTER than locomotion (0.2841 m/s). A channel where
// "a person stands still breathing" and "a person sprints at full speed" travel
// at the same speed carries no prompt signal at all.
//
// The cause is denormalization, and it is upstream of us. MDM samples in
// HumanML3D's normalized feature space and mdm_sampler denormalizes with the
// dataset's own mean and std before recover_from_ric integrates the root
// velocity (workers/model-text2motion/mdm_sampler.py). Feature 2 is the root's
// forward velocity, and most of HumanML3D walks, so that feature's dataset MEAN
// is a brisk walk. When the model has no strong locomotion signal to express it
// emits a normalized value near zero, and denormalizing "near zero" yields
// exactly the dataset's average walking speed. The integration then turns a
// constant velocity into a straight ramp.
//
// So the fix is to remove the component that is indistinguishable from a
// constant-velocity ramp and keep everything else. Fitting the horizontal root
// track by least squares and subtracting the fitted line leaves the residual
// intact, which is where the real signal lives: a pirouette's sway and a walk's
// per-step surge survive (locomotion residual 0.0051 m) while a clip whose root
// track is a straight line flattens to nothing (emote residual 0.0002 m).
// Vertical travel is never touched, because a crouch, a jump and a fall are all
// real motion in Y.
//
// This is also what makes the library's convention honest: three.ws clips play
// on an avatar standing where the page put it, and a game engine expects an
// in-place clip it can drive from its own character controller. Run this BEFORE
// gating and before closing a loop seam. Before gating, because the foot-slide
// rule measures planted-foot slide against the stride the clip covers, and a
// fake 1 m stride makes that rule far too lenient. Before the seam, because the
// seam search is looking for the frame whose pose repeats frame 0, and a ramp
// guarantees no frame ever does.
export const ROOT_DRIFT = Object.freeze({
// Below this the fitted ramp is not worth removing: a clip that travels a
// centimetre over its whole length is already in place.
MIN_SPEED: 0.02,
});
/**
* Remove the constant-velocity horizontal ramp from a clip's root translation.
*
* Returns a NEW clip; the input is not modified. A clip with no root position
* track, too few frames, or no measurable ramp is returned unchanged, so this is
* always safe to call.
*
* @param {any} clip
* @returns {{ clip: any, speed: number, removed: number, residual: number }}
* speed is the fitted ramp in m/s, removed the total metres taken out, and
* residual the RMS of what was left behind (the real motion).
*/
export function flattenRootDrift(clip, opts = {}) {
const minSpeed = opts.minSpeed ?? ROOT_DRIFT.MIN_SPEED;
const tracks = clip?.tracks ?? [];
const index = tracks.findIndex((t) => String(t?.name || '') === 'Hips.position');
if (index === -1) return { clip, speed: 0, removed: 0, residual: 0 };
const track = tracks[index];
const times = Array.from(track.times ?? []);
const values = Array.from(track.values ?? []);
const n = times.length;
if (n < 2 || values.length !== n * 3) return { clip, speed: 0, removed: 0, residual: 0 };
const meanTime = times.reduce((s, t) => s + t, 0) / n;
let timeVariance = 0;
for (const t of times) timeVariance += (t - meanTime) ** 2;
if (timeVariance <= 0) return { clip, speed: 0, removed: 0, residual: 0 };
// Fit and subtract independently on X and Z: a clip can ramp on either axis.
const slopes = [0, 0];
const residuals = [0, 0];
for (const [slot, axis] of [[0, 0], [1, 2]]) {
let meanValue = 0;
for (let i = 0; i < n; i += 1) meanValue += values[i * 3 + axis];
meanValue /= n;
let covariance = 0;
for (let i = 0; i < n; i += 1) covariance += (times[i] - meanTime) * (values[i * 3 + axis] - meanValue);
const slope = covariance / timeVariance;
slopes[slot] = slope;
let sumSquares = 0;
const intercept = meanValue - slope * meanTime;
for (let i = 0; i < n; i += 1) sumSquares += (values[i * 3 + axis] - (slope * times[i] + intercept)) ** 2;
residuals[slot] = Math.sqrt(sumSquares / n);
}
const speed = Math.hypot(slopes[0], slopes[1]);
if (speed < minSpeed) {
return { clip, speed, removed: 0, residual: Math.hypot(residuals[0], residuals[1]) };
}
// Subtract the ramp relative to frame 0, so the clip still starts exactly
// where it started and only the travel is taken away.
const flattened = values.slice();
const t0 = times[0];
for (let i = 0; i < n; i += 1) {
const elapsed = times[i] - t0;
flattened[i * 3] -= slopes[0] * elapsed;
flattened[i * 3 + 2] -= slopes[1] * elapsed;
}
const out = { ...clip, tracks: tracks.slice() };
out.tracks[index] = { ...track, times, values: flattened };
return {
clip: out,
speed,
removed: speed * (times[n - 1] - t0),
residual: Math.hypot(residuals[0], residuals[1]),
};
}
// ── Foot flicks ─────────────────────────────────────────────────────────────
//
// The lane's foot rotation is under-determined. The worker recovers each bone's
// rotation from joint POSITIONS (a Kabsch fit in mdm_sampler.py), and a foot has
// a single child to fit against, so on some frames the fit lands on the other
// solution and the foot swings its toe through a different direction for one or
// two frames before snapping back. Measured on a live "speech" take on
// 2026-09-18: the ankle held within 0.4 cm for 40 frames while the toe jumped
// 8.6 cm and back on 12 of them. On screen that is a foot flicking, and in the
// gate it reads as a planted toe skating 3 m across the floor, which is why a
// clip of a person standing still talking was rejected for sliding.
//
// It is repaired in world space, where it is visible, and never in rotation
// space, where the twist flips described under "Judge positions" would be
// mistaken for it. A frame is a flick when the toe, measured relative to its
// own ankle, sits further than FOOT_FLICK.MIN_CM from the straight line between
// the good frames either side, and the excursion lasts at most MAX_FRAMES. The
// foot and toe rotations on those frames are replaced by a slerp between the
// neighbours. A real foot movement (a kick, a toe tap, a heel lift) is slower
// than MAX_FRAMES at 30 fps and is left alone.
export const FOOT_FLICK = Object.freeze({
MIN_CM: 3,
MAX_FRAMES: 3,
});
/**
* Repair single-frame foot flicks. Returns a NEW clip and the number of frames
* repaired per side; a clip without foot tracks is returned unchanged.
*
* @param {any} clip
* @returns {{ clip: any, repaired: number }}
*/
export function despikeFootFlicks(clip, opts = {}) {
const threshold = (opts.minCm ?? FOOT_FLICK.MIN_CM) / 100;
const maxFrames = opts.maxFrames ?? FOOT_FLICK.MAX_FRAMES;
const frames = frameCount(clip);
if (frames < 3) return { clip, repaired: 0 };
const worlds = [];
for (let i = 0; i < frames; i += 1) worlds.push(forwardKinematicsFrame(clip, i));
const tracks = (clip?.tracks ?? []).slice();
let repaired = 0;
for (const side of ['Left', 'Right']) {
const footIndex = tracks.findIndex((t) => t?.name === `${side}Foot.quaternion`);
if (footIndex === -1) continue;
const toeIndex = tracks.findIndex((t) => t?.name === `${side}ToeBase.quaternion`);
const toeRel = worlds.map((w) => {
const foot = w[`${side}Foot`];
const toe = w[`${side}ToeBase`];
return foot && toe ? [toe[0] - foot[0], toe[1] - foot[1], toe[2] - foot[2]] : null;
});
if (toeRel.some((v) => !v)) continue;
const flagged = new Array(frames).fill(false);
const deviation = (i, a, b) => {
const t = (i - a) / (b - a);
const expected = toeRel[a].map((v, k) => v + (toeRel[b][k] - v) * t);
return Math.hypot(...toeRel[i].map((v, k) => v - expected[k]));
};
// Try the shortest excursion first so a one-frame flick is never repaired
// as part of a longer span that swallows good frames.
for (let span = 1; span <= maxFrames; span += 1) {
for (let a = 0; a + span + 1 < frames; a += 1) {
const b = a + span + 1;
if (flagged[a] || flagged[b]) continue;
// The anchors must agree with each other, or this is real movement.
const anchorGap = Math.hypot(...toeRel[a].map((v, k) => v - toeRel[b][k]));
if (anchorGap > threshold) continue;
let all = true;
for (let i = a + 1; i < b; i += 1) {
if (flagged[i] || deviation(i, a, b) <= threshold) {
all = false;
break;
}
}
if (!all) continue;
for (let i = a + 1; i < b; i += 1) flagged[i] = true;
for (const index of [footIndex, toeIndex]) {
if (index === -1) continue;
const track = tracks[index];
const values = Array.from(track.values ?? []);
const qa = values.slice(a * 4, a * 4 + 4);
const qb = values.slice(b * 4, b * 4 + 4);
if (qa.length < 4 || qb.length < 4) continue;
for (let i = a + 1; i < b; i += 1) {
const q = slerp(qa, qb, (i - a) / (b - a));
for (let k = 0; k < 4; k += 1) values[i * 4 + k] = q[k];
}
tracks[index] = { ...track, values };
}
repaired += span;
}
}
}
return repaired ? { clip: { ...clip, tracks }, repaired } : { clip, repaired: 0 };
}
// ── Root travel from foot contact ───────────────────────────────────────────
//
// Flattening the drift is right for a clip that stands still and wrong for one
// that walks. The authored library does NOT ship in-place locomotion: measured
// on 2026-09-18, its walks carry their root motion (a catwalk travels 1.23 m, a
// careful walk 1.32 m, and their planted feet slide 0.09 m and 0.13 m). A
// generated walk with its root pinned is a treadmill: the legs stride and the
// planted foot is dragged backward under a body that goes nowhere, which the
// foot-slide rule rightly rejects. Every locomotion prompt in the first live
// batch failed exactly that way (slide 5 to 21 times its stride).
//
// The lane's own root channel cannot be kept instead, because it carries no
// prompt signal (see ROOT_DRIFT). So the travel is derived from the one place
// the motion does carry it: the feet. While a foot is planted it should stay
// put in the world, so the body must travel by exactly the opposite of that
// foot's hips-relative motion. Between plants (a run's flight phase, a foot
// switch) the velocity is interpolated across the gap. The result is smoothed
// over ROOT_LOCK.SMOOTH_SECONDS, which is what keeps the gate honest: the root
// follows the clip's average stride, not every sample of the foot, so a foot
// that genuinely skates relative to a steady gait still reads as a skate.
//
// This is standard mocap cleanup (root extraction from foot contacts), and it is
// harmless for a clip that stands still: an idle's planted feet barely move
// relative to its hips, so its derived travel is the same few centimetres of
// sway that flattening would have kept.
export const ROOT_LOCK = Object.freeze({
// Share of frame pairs that must have a planted foot on both ends before the
// feet are trusted to carry the root. Below it the clip is floor work, a jump
// or an aerial, and the flattened root is kept.
MIN_CONTACT_SHARE: 0.3,
// Centred smoothing window for the derived velocity. A third of a second is
// about one step at a walk: long enough to average across a foot switch,
// short enough to follow a real change of pace.
SMOOTH_SECONDS: 0.33,
// Net travel speed, in m/s, below which the derived root is discarded and the
// flattened one kept. A clip that stands still (a speech, a laugh) still has
// a centimetre of foot jitter per frame, and integrating that into a root path
// would hand it a fake "stride" that lets real skating hide behind the
// ratio test. A slow walk is about 0.5 m/s; 0.2 keeps a shuffle in place.
MIN_SPEED: 0.2,
});
function lowerGroundedFoot(world, floorY) {
const left = world.LeftToeBase ?? world.LeftFoot;
const right = world.RightToeBase ?? world.RightFoot;
const hips = world.Hips;
if (!left || !right || !hips) return null;
const entry = left[1] <= right[1] ? { side: 'Left', pos: left } : { side: 'Right', pos: right };
const grounded =
entry.pos[1] - floorY <= MOTION_GATE.PLANT_BAND && hips[1] - floorY >= MOTION_GATE.UPRIGHT_HIP_HEIGHT;
return grounded ? { side: entry.side, rel: [entry.pos[0] - hips[0], entry.pos[2] - hips[2]] } : null;
}
/**
* Replace a clip's horizontal root travel with the travel its planted feet imply.
*
* Returns a NEW clip; the input is not modified. A clip with no root position
* track, too few frames, or too little foot contact to trust is returned
* unchanged with `applied: false`, so this is always safe to call.
*
* @param {any} clip
* @param {{ minContactShare?: number, smoothSeconds?: number, minSpeed?: number }} [opts]
* @returns {{ clip: any, applied: boolean, contactShare: number, travel: number, speed: number }}
*/
export function lockRootToContacts(clip, opts = {}) {
const minShare = opts.minContactShare ?? ROOT_LOCK.MIN_CONTACT_SHARE;
const smoothSeconds = opts.smoothSeconds ?? ROOT_LOCK.SMOOTH_SECONDS;
const unchanged = (contactShare = 0) => ({ clip, applied: false, contactShare, travel: 0, speed: 0 });
// Why this runs after the foot-flick repair: a flick is a planted toe jumping
// 8 cm and back, which read as a burst of body travel would push the root.
const tracks = clip?.tracks ?? [];
const index = tracks.findIndex((t) => String(t?.name || '') === 'Hips.position');
if (index === -1) return unchanged();
const track = tracks[index];
const times = Array.from(track.times ?? []);
const values = Array.from(track.values ?? []);
const n = times.length;
if (n < 3 || values.length !== n * 3) return unchanged();
const worlds = new Array(n);
let floorY = Infinity;
for (let i = 0; i < n; i += 1) {
worlds[i] = forwardKinematicsFrame(clip, i);
for (const bone of ['LeftToeBase', 'LeftFoot', 'RightToeBase', 'RightFoot']) {
const y = worlds[i][bone]?.[1];
if (Number.isFinite(y)) floorY = Math.min(floorY, y);
}
}
if (!Number.isFinite(floorY)) return unchanged();
// A toe and its foot are both candidates for the floor above; the lower of
// the pair is what lowerGroundedFoot judges, so the band is measured from it.
const contacts = worlds.map((w) => lowerGroundedFoot(w, floorY));
// Per-step body velocity (metres per frame) wherever the same foot is planted
// on both ends of the step; null where it is not.
const velocity = new Array(n).fill(null);
let defined = 0;
for (let i = 1; i < n; i += 1) {
const a = contacts[i - 1];
const b = contacts[i];
if (!a || !b || a.side !== b.side) continue;
velocity[i] = [-(b.rel[0] - a.rel[0]), -(b.rel[1] - a.rel[1])];
defined += 1;
}
const contactShare = defined / (n - 1);
if (contactShare < minShare) return unchanged(contactShare);
// Fill the gaps by linear interpolation between the defined neighbours, and
// hold the nearest defined value at either end.
const filled = velocity.slice();
let last = -1;
for (let i = 1; i < n; i += 1) {
if (!velocity[i]) continue;
if (last === -1) {
for (let k = 1; k < i; k += 1) filled[k] = velocity[i];
} else if (i - last > 1) {
for (let k = last + 1; k < i; k += 1) {
const t = (k - last) / (i - last);
filled[k] = [
velocity[last][0] + (velocity[i][0] - velocity[last][0]) * t,
velocity[last][1] + (velocity[i][1] - velocity[last][1]) * t,
];
}
}
last = i;
}
for (let k = last + 1; k < n; k += 1) filled[k] = velocity[last];
filled[0] = [0, 0];
const duration = times[n - 1] - times[0];
const fps = duration > 0 ? (n - 1) / duration : 30;
const half = Math.max(1, Math.round((smoothSeconds * fps) / 2));
const smoothed = new Array(n);
smoothed[0] = [0, 0];
for (let i = 1; i < n; i += 1) {
let sx = 0;
let sz = 0;
let count = 0;
for (let k = Math.max(1, i - half); k <= Math.min(n - 1, i + half); k += 1) {
sx += filled[k][0];
sz += filled[k][1];
count += 1;
}
smoothed[i] = [sx / count, sz / count];
}
const out = values.slice();
let x = values[0];
let z = values[2];
let travel = 0;
for (let i = 1; i < n; i += 1) {
x += smoothed[i][0];
z += smoothed[i][1];
travel += Math.hypot(smoothed[i][0], smoothed[i][1]);
out[i * 3] = x;
out[i * 3 + 2] = z;
}
out[0] = values[0];
out[2] = values[2];
const net = Math.hypot(x - values[0], z - values[2]);
const speed = duration > 0 ? net / duration : 0;
if (speed < (opts.minSpeed ?? ROOT_LOCK.MIN_SPEED)) return { ...unchanged(contactShare), speed };
const result = { ...clip, tracks: tracks.slice() };
result.tracks[index] = { ...track, times, values: out };
return { clip: result, applied: true, contactShare, travel, speed };
}
export const LOOP_SEAM = Object.freeze({
// Never cut away more than this fraction of the clip hunting for a cycle: a
// clip trimmed to a third of its length is a different clip.
MAX_TRIM_FRACTION: 0.35,
// Frames blended back toward the start, tried shortest first. A short blend
// keeps the motion crisp; a long one spreads a big correction over enough
// frames that it does not read as a pop. A clip with a wide seam needs the
// longer end, and the alternative to accepting some smear is rejecting the
// clip outright.
BLEND_LADDER: Object.freeze([8, 16, 24, 36, 48]),
// A seam this small is already invisible; authored loops sit at 0.000.
TARGET: 0.02,
// A trim must beat the untrimmed seam by at least this much to be worth
// taking. Without it a clip whose seam is already nearly closed gets a third
// of its length cut off chasing a millimetre, and the blend that follows has
// to move a joint far enough to create the very pop this is meant to avoid.
TRIM_IMPROVEMENT: 0.7,
});
/**
* Close a generated clip's loop seam.
*
* Two steps, in order:
* 1. Trim to the cycle. Search the tail for the frame whose pose is closest to
* frame 0 and cut there. For a periodic motion (a walk, an idle) this alone
* usually finds a near-perfect seam, because the cycle really is in there.
* 2. Blend what is left. Over the final BLEND_FRAMES, slerp each rotation
* toward the value it holds at frame 0, ramping to a full match on the last
* frame, so the seam closes exactly. The root's height is matched the same
* way while its horizontal travel is preserved, so a travelling walk still
* travels.
*
* Returns a NEW clip; the input is not modified. A clip with too few frames to
* work with is returned unchanged, so this is always safe to call.
*/
export function closeLoopSeam(clip, opts = {}) {
const ladder = opts.blendFrames ? [opts.blendFrames] : LOOP_SEAM.BLEND_LADDER;
const maxTrim = opts.maxTrimFraction ?? LOOP_SEAM.MAX_TRIM_FRACTION;
const frames = frameCount(clip);
const shortest = ladder[0];
if (frames < shortest * 3) return { clip, trimmedFrames: 0, seamBefore: 0, seamAfter: 0 };
const seamBefore = seamDistanceBetween(clip, 0, frames - 1);
const original = worldMotionMetrics(clip);
// 1. Find the best cycle end in the tail.
const earliest = Math.max(shortest * 2, Math.floor(frames * (1 - maxTrim)));
let bestEnd = frames - 1;
let bestDistance = seamBefore;
for (let k = earliest; k < frames; k += 1) {
const d = seamDistanceBetween(clip, 0, k);
if (d < bestDistance) {
bestDistance = d;
bestEnd = k;
}
}
// Only pay for a trim that actually buys a better seam.
if (bestEnd !== frames - 1 && bestDistance > seamBefore * LOOP_SEAM.TRIM_IMPROVEMENT) {
bestEnd = frames - 1;
}
// 2. Blend the tail back onto the opening pose, shortest blend first, taking
// the first one that closes the seam without costing more continuity than
// the gate allows. Spreading a wide correction over more frames is what
// keeps it from reading as a pop.
const keep = bestEnd + 1;
const fps = frames > 1 ? (frames - 1) / Math.max(clip.duration, 1e-6) : 30;
let fallback = null;
for (const blendFrames of ladder) {
const closed = rebuildWithBlend(clip, keep, blendFrames, fps);
const after = worldMotionMetrics(closed);
const result = {
clip: closed,
trimmedFrames: frames - keep,
seamBefore,
seamAfter: loopSeamDistance(closed),
blendFrames,
};
if (after.continuity <= MOTION_GATE.MAX_WORLD_STEP_RATIO) return result;
// Keep the least-bad attempt in case every rung overshoots.
if (!fallback || after.continuity < fallback.continuity) {
fallback = { ...result, continuity: after.continuity };
}
}
// Every blend length cost more continuity than the gate allows. If the clip
// was fine before, leave it alone and say why; if it was not, the closed clip
// is still the better of two bad options.
if (original.continuity <= MOTION_GATE.MAX_WORLD_STEP_RATIO) {
return {
clip,
trimmedFrames: 0,
seamBefore,
seamAfter: seamBefore,
rejected: 'closing the seam would have cost more continuity than it bought',
};
}
const { continuity, ...rest } = fallback;
return rest;
}
/** Rebuild a clip trimmed to `keep` frames with its tail blended onto frame 0. */
function rebuildWithBlend(clip, keep, blendFrames, fps) {
const tracks = [];
for (const track of clip.tracks ?? []) {
const stride = track.type === 'quaternion' ? 4 : 3;
const available = Math.floor(track.values.length / stride);
const n = Math.min(keep, available);
const times = Array.from(track.times).slice(0, n);
const values = Array.from(track.values).slice(0, n * stride);
const first = values.slice(0, stride);
const blend = Math.min(blendFrames, n - 1);
for (let i = 0; i < blend; i += 1) {
const index = n - blend + i;
const t = (i + 1) / blend;
const at = index * stride;
if (track.type === 'quaternion') {
const blended = slerp(values.slice(at, at + 4), first, t);
for (let c = 0; c < 4; c += 1) values[at + c] = blended[c];
} else {
// Height is matched; horizontal travel is kept, so a travelling loop
// still covers ground.
values[at + 1] += (first[1] - values[at + 1]) * t;
}
}
tracks.push({ ...track, times, values });
}
return { ...clip, duration: (keep - 1) / fps, tracks };
}
// ── Library-ready conversion for a single clip ──────────────────────────────
/**
* Convert one clip exactly as the worker wrote it into a clip that plays
* correctly on the library's rig: the rest-shape rebase, the foot-flick repair,
* the drift removal and the root travel from foot contact, in the order the
* batch runner applies them (scripts/gcp/seed-motion.mjs deriveClip). This is
* what POST /api/forge-motion's poll hands a browser, so a clip generated on
* demand plays the same way a published one does. No gate: an on-demand clip
* is the user's to judge.
*
* @param {any} workerClip
* @returns {any} a NEW clip stamped with CLIP_BASIS
*/
export function libraryReadyClip(workerClip) {
const rebased = needsRebase(workerClip) ? rebaseToCanonicalRest(workerClip).clip : workerClip;
const flattened = flattenRootDrift(despikeFootFlicks(rebased).clip).clip;
const clip = lockRootToContacts(flattened).clip;
// This is the exact shape the client's AnimationClip.parse() reads (it's
// handed straight through as /api/forge-motion's `clip` field), and parse()
// passes userData to JSON.parse() unchanged, the same contract
// AnimationClip.toJSON() honors and every static library clip on disk already
// uses. An object here parses as the string "[object Object]" and throws.
return { ...clip, userData: JSON.stringify({ ...(clip.userData || {}), basis: CLIP_BASIS }) };
}