Skip to content

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.

feat(motion): gate generated clips on quality and serve them from their own manifest

nirholas0a6ad1daedab
diff --git a/api/_lib/motion-quality.js b/api/_lib/motion-quality.js
new file mode 100644
index 000000000..15e19db33
--- /dev/null
+++ b/api/_lib/motion-quality.js
@@ -0,0 +1,574 @@
+// @ts-check
+// Automated quality gate for generated motion clips.
+//
+// The text-to-motion lane (workers/model-text2motion, reached through
+// POST /api/forge-motion) samples a motion diffusion model, so its output is a
+// distribution, not a guarantee: a prompt can come back frozen in bind pose,
+// torn by a single-frame discontinuity, or "walking" with both feet skating
+// across the floor. None of those may reach the public library, and none of
+// them is visible from the clip's metadata. This module decides, from the clip
+// JSON alone, whether a generated clip is good enough to publish beside the
+// curated Mixamo catalog.
+//
+// It is deliberately deterministic and dependency-free: no GPU, no renderer,
+// no model call. Every check is arithmetic over the keyframes, so the same
+// verdict is reachable from the seeding cron, from the batch runner on a
+// workstation, and from a unit test.
+//
+// The interesting check is FOOT SLIDE, and it is measured rather than guessed.
+// src/animation-canonical-rest.js carries the reference rig completely: every
+// canonical bone's world bind rotation, its world rest position, and its
+// parent. That is enough to run forward kinematics on each frame of the clip
+// and put the feet in world space, root translation included. A correct walk
+// plants a foot and lets the world carry it backwards; a skating walk drags
+// the planted foot. The gate measures the drift of each foot across the frames
+// it is actually in contact with the ground and rejects on the worst span.
+//
+// Thresholds are calibrated against the curated library rather than invented:
+// a generated clip is held to the standard the Mixamo clips already meet, so
+// the gate can never reject motion that the platform itself ships. See
+// scripts/gcp/calibrate-motion-gate.mjs, which replays this module over both
+// catalogs and prints the distributions the bounds below are drawn from.
+
+import {
+ CANONICAL_PARENT,
+ CANONICAL_REST_POSITION,
+ CANONICAL_REST_WORLD,
+} from '../../src/animation-canonical-rest.js';
+
+export const MOTION_GATE_VERSION = 1;
+
+/**
+ * Every bound the gate enforces, in one frozen object so a caller (or a report)
+ * can name the rule it tripped without reading the code.
+ */
+export const MOTION_BOUNDS = Object.freeze({
+ // Structure.
+ minDurationSeconds: 0.8,
+ maxDurationSeconds: 12,
+ minFrames: 12,
+ maxFrames: 1800,
+ minRotationTracks: 12,
+ // How far the delivered clip may miss the requested length. The sampler
+ // rounds to whole frames, so this is loose on purpose; it exists to catch a
+ // lane that silently returned somebody else's clip.
+ durationTolerance: 0.35,
+ // A quaternion track whose keys are not unit length will be renormalised by
+ // three.js and silently change the pose, so refuse it here instead.
+ quatNormTolerance: 0.05,
+
+ // Motion content.
+ // Averaged angular speed across every rotation track. A clip below this is
+ // standing in bind pose: technically valid, worthless in a library.
+ minMeanAngularSpeedDeg: 5,
+ // A single inter-frame step this large is a tear, not motion. 45 degrees at
+ // 30 fps is 1350 deg/s on one joint, well past anything a body does.
+ maxFrameAngularStepDeg: 45,
+ // Loop clips only: the pose distance between the first and last frame. A
+ // seam wider than this visibly pops every cycle.
+ maxLoopSeamDeg: 30,
+
+ // Space.
+ // Planted-foot horizontal drift over one contact span, as a fraction of the
+ // rig's hip height. Above this the character skates.
+ maxFootSlideRatio: 0.45,
+ // A foot below the ground plane by more than this (metres) is clipping
+ // through the floor.
+ maxGroundPenetration: 0.15,
+ // Hips translation speed. The diffusion model occasionally launches the root.
+ maxRootSpeedMetresPerSecond: 6,
+});
+
+/**
+ * Bones a humanoid clip must drive to be worth publishing. Fingers are not
+ * required: the text-to-motion lane emits a 22-joint SMPL body and the retarget
+ * engine leaves unlisted bones at rest, which is correct.
+ */
+export const REQUIRED_BONES = Object.freeze([
+ 'Hips',
+ 'Spine',
+ 'Head',
+ 'LeftArm',
+ 'LeftForeArm',
+ 'RightArm',
+ 'RightForeArm',
+ 'LeftUpLeg',
+ 'LeftLeg',
+ 'LeftFoot',
+ 'RightUpLeg',
+ 'RightLeg',
+ 'RightFoot',
+]);
+
+// ── Quaternion / vector helpers ──────────────────────────────────────────────
+// [x, y, z, w] throughout, matching three.js and the clip JSON.
+
+function qMul(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 qConjugate(q) {
+ return [-q[0], -q[1], -q[2], q[3]];
+}
+
+function qRotate(q, v) {
+ // v' = q * (v, 0) * q⁻¹, expanded to avoid two full quaternion products.
+ const [x, y, z, w] = q;
+ const [vx, vy, vz] = v;
+ const tx = 2 * (y * vz - z * vy);
+ const ty = 2 * (z * vx - x * vz);
+ const tz = 2 * (x * vy - y * vx);
+ return [
+ vx + w * tx + y * tz - z * ty,
+ vy + w * ty + z * tx - x * tz,
+ vz + w * tz + x * ty - y * tx,
+ ];
+}
+
+/** Shortest rotation angle between two unit quaternions, in degrees. */
+function qAngleDeg(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)) * 180) / Math.PI;
+}
+
+function qNorm(q) {
+ return Math.hypot(q[0], q[1], q[2], q[3]);
+}
+
+const IDENTITY_Q = [0, 0, 0, 1];
+
+// ── Reference skeleton ───────────────────────────────────────────────────────
+
+/**
+ * Local rest offset of each bone in its parent's bind frame, derived once from
+ * the reference rig. Forward kinematics needs the offset in the parent's local
+ * space, while the generated table stores world rest positions, so each is
+ * rotated back through the parent's world bind rotation.
+ */
+const LOCAL_REST_OFFSET = (() => {
+ /** @type {Record<string, number[]>} */
+ const out = {};
+ for (const [bone, parent] of Object.entries(CANONICAL_PARENT)) {
+ const here = CANONICAL_REST_POSITION[bone];
+ if (!here) continue;
+ if (!parent) {
+ out[bone] = [...here];
+ continue;
+ }
+ const up = CANONICAL_REST_POSITION[parent];
+ if (!up) continue;
+ const parentWorld = CANONICAL_REST_WORLD[parent] || IDENTITY_Q;
+ out[bone] = qRotate(qConjugate(parentWorld), [
+ here[0] - up[0],
+ here[1] - up[1],
+ here[2] - up[2],
+ ]);
+ }
+ return Object.freeze(out);
+})();
+
+/** Hip height of the reference rig, the scale every distance is reported in. */
+export const REFERENCE_HIP_HEIGHT = CANONICAL_REST_POSITION.Hips?.[1] || 1;
+
+/** Ground plane: the lowest rest point of the reference rig's feet. */
+const REST_FLOOR_Y = Math.min(
+ CANONICAL_REST_POSITION.LeftToeBase?.[1] ?? CANONICAL_REST_POSITION.LeftFoot?.[1] ?? 0,
+ CANONICAL_REST_POSITION.RightToeBase?.[1] ?? CANONICAL_REST_POSITION.RightFoot?.[1] ?? 0,
+);
+
+// Walk the parents first so a single pass can compose world transforms.
+const FK_ORDER = (() => {
+ const seen = new Set();
+ /** @type {string[]} */
+ const order = [];
+ const visit = (bone) => {
+ if (seen.has(bone) || !(bone in CANONICAL_PARENT)) return;
+ seen.add(bone);
+ const parent = CANONICAL_PARENT[bone];
+ if (parent) visit(parent);
+ order.push(bone);
+ };
+ for (const bone of Object.keys(CANONICAL_PARENT)) visit(bone);
+ return Object.freeze(order.filter((b) => LOCAL_REST_OFFSET[b]));
+})();
+
+// ── Clip parsing ─────────────────────────────────────────────────────────────
+
+/**
+ * A structural problem the gate could not look past: the clip is not a clip.
+ * Thrown only by readClip; every quality verdict comes back as data.
+ */
+export class MotionClipShapeError extends Error {}
+
+/**
+ * Normalise a three.js AnimationClip JSON into the sampled form the checks
+ * work on: one quaternion per bone per frame plus the root translation.
+ *
+ * The clip's tracks are keyframed independently, so the checks resample every
+ * track onto the union of its own key times. The text-to-motion lane emits all
+ * tracks on one uniform time base, and so does the Mixamo bake, so in practice
+ * this is a straight read; the nearest-key lookup only matters for a clip
+ * authored elsewhere.
+ *
+ * @param {unknown} raw
+ * @returns {{ name: string, duration: number, frames: number, times: number[],
+ * rotations: Record<string, number[][]>, rootPositions: number[][] | null,
+ * trackNames: string[], rotationTrackCount: number }}
+ */
+export function readClip(raw) {
+ if (!raw || typeof raw !== 'object') throw new MotionClipShapeError('clip is not an object');
+ const clip = /** @type {any} */ (raw);
+ const tracks = Array.isArray(clip.tracks) ? clip.tracks : null;
+ if (!tracks || tracks.length === 0) throw new MotionClipShapeError('clip carries no tracks');
+
+ /** @type {Record<string, number[][]>} */
+ const rotations = {};
+ /** @type {number[][] | null} */
+ let rootPositions = null;
+ /** @type {number[] | null} */
+ let times = null;
+ const trackNames = [];
+ let rotationTrackCount = 0;
+
+ for (const track of tracks) {
+ const name = typeof track?.name === 'string' ? track.name : '';
+ const keyTimes = Array.isArray(track?.times) ? track.times.map(Number) : null;
+ const values = Array.isArray(track?.values) ? track.values.map(Number) : null;
+ if (!name || !keyTimes || !values) {
+ throw new MotionClipShapeError(`track ${name || '(unnamed)'} is missing times or values`);
+ }
+ trackNames.push(name);
+
+ const [bone, property] = splitTrackName(name);
+ const stride = property === 'quaternion' ? 4 : 3;
+ if (values.length !== keyTimes.length * stride) {
+ throw new MotionClipShapeError(
+ `track ${name} has ${values.length} values for ${keyTimes.length} keys at stride ${stride}`,
+ );
+ }
+ const framesHere = [];
+ for (let i = 0; i < keyTimes.length; i++) {
+ framesHere.push(values.slice(i * stride, i * stride + stride));
+ }
+ if (property === 'quaternion') {
+ rotations[bone] = framesHere;
+ rotationTrackCount++;
+ if (!times || keyTimes.length > times.length) times = keyTimes;
+ } else if (property === 'position' && bone === 'Hips') {
+ rootPositions = framesHere;
+ if (!times) times = keyTimes;
+ }
+ }
+
+ if (!times || times.length === 0) throw new MotionClipShapeError('clip has no keyframe times');
+ if (rotationTrackCount === 0) throw new MotionClipShapeError('clip drives no rotations');
+
+ const duration = Number(clip.duration);
+ return {
+ name: typeof clip.name === 'string' ? clip.name : '',
+ duration: Number.isFinite(duration) ? duration : times[times.length - 1],
+ frames: times.length,
+ times,
+ rotations,
+ rootPositions,
+ trackNames,
+ rotationTrackCount,
+ };
+}
+
+function splitTrackName(name) {
+ const dot = name.lastIndexOf('.');
+ return dot < 0 ? [name, ''] : [name.slice(0, dot), name.slice(dot + 1)];
+}
+
+// ── Forward kinematics ───────────────────────────────────────────────────────
+
+/**
+ * Place every reference bone in world space for one frame of the clip.
+ * Bones the clip does not drive keep their bind rotation, exactly as the
+ * retarget engine leaves them.
+ *
+ * @param {ReturnType<typeof readClip>} clip
+ * @param {number} frame
+ * @returns {{ positions: Record<string, number[]>, rotations: Record<string, number[]> }}
+ */
+export function poseAtFrame(clip, frame) {
+ /** @type {Record<string, number[]>} */
+ const positions = {};
+ /** @type {Record<string, number[]>} */
+ const worldRotations = {};
+
+ const root = clip.rootPositions?.[Math.min(frame, clip.rootPositions.length - 1)] || null;
+
+ for (const bone of FK_ORDER) {
+ const parent = CANONICAL_PARENT[bone];
+ const track = clip.rotations[bone];
+ const local = track ? track[Math.min(frame, track.length - 1)] : null;
+ const localQ = local && local.length === 4 ? local : CANONICAL_REST_WORLD[bone] && !parent ? IDENTITY_Q : IDENTITY_Q;
+
+ if (!parent) {
+ worldRotations[bone] = localQ;
+ // Hips.position is the clip's root track when present; otherwise the
+ // character stands at its rest hip position.
+ positions[bone] = root ? [...root] : [...CANONICAL_REST_POSITION[bone]];
+ continue;
+ }
+ const parentQ = worldRotations[parent] || IDENTITY_Q;
+ const parentP = positions[parent] || [0, 0, 0];
+ const offset = qRotate(parentQ, LOCAL_REST_OFFSET[bone]);
+ positions[bone] = [parentP[0] + offset[0], parentP[1] + offset[1], parentP[2] + offset[2]];
+ worldRotations[bone] = qMul(parentQ, localQ);
+ }
+ return { positions, rotations: worldRotations };
+}
+
+/**
+ * Foot trajectories in world space, one entry per frame.
+ * @param {ReturnType<typeof readClip>} clip
+ */
+function footTrajectories(clip) {
+ const left = [];
+ const right = [];
+ for (let f = 0; f < clip.frames; f++) {
+ const { positions } = poseAtFrame(clip, f);
+ left.push(positions.LeftToeBase || positions.LeftFoot || [0, 0, 0]);
+ right.push(positions.RightToeBase || positions.RightFoot || [0, 0, 0]);
+ }
+ return { left, right };
+}
+
+/**
+ * Worst horizontal drift of a foot while it is planted, in metres.
+ *
+ * "Planted" is the frames where the foot sits in the lowest band of its own
+ * vertical range: a walk cycle's stance phase, an idle's whole timeline. Drift
+ * is measured per contiguous span, so a foot that lifts, travels and lands
+ * again is not charged for the step it legitimately took.
+ *
+ * @param {number[][]} trajectory
+ * @param {number} contactBand metres above the foot's own minimum that still counts as contact
+ */
+function worstPlantedDrift(trajectory, contactBand) {
+ if (trajectory.length < 2) return 0;
+ let minY = Infinity;
+ for (const p of trajectory) minY = Math.min(minY, p[1]);
+ const ceiling = minY + contactBand;
+
+ let worst = 0;
+ /** @type {number[] | null} */
+ let spanStart = null;
+ let spanDrift = 0;
+ /** @type {number[] | null} */
+ let previous = null;
+
+ for (const p of trajectory) {
+ if (p[1] <= ceiling) {
+ if (!spanStart) {
+ spanStart = p;
+ spanDrift = 0;
+ } else if (previous) {
+ spanDrift += Math.hypot(p[0] - previous[0], p[2] - previous[2]);
+ }
+ previous = p;
+ } else {
+ if (spanStart) worst = Math.max(worst, spanDrift);
+ spanStart = null;
+ previous = null;
+ spanDrift = 0;
+ }
+ }
+ if (spanStart) worst = Math.max(worst, spanDrift);
+ return worst;
+}
+
+// ── Measurement ──────────────────────────────────────────────────────────────
+
+/**
+ * Every number the gate decides on. Exported separately from the verdict so the
+ * calibration script can print distributions across a whole catalog without
+ * re-deriving them.
+ *
+ * @param {ReturnType<typeof readClip>} clip
+ */
+export function measureClip(clip) {
+ const fps = clip.frames > 1 ? (clip.frames - 1) / Math.max(clip.duration, 1e-6) : 0;
+
+ let nonFinite = 0;
+ let worstQuatNormError = 0;
+ let timeRegressions = 0;
+ for (let i = 1; i < clip.times.length; i++) {
+ if (!(clip.times[i] > clip.times[i - 1])) timeRegressions++;
+ }
+ for (const t of clip.times) if (!Number.isFinite(t)) nonFinite++;
+
+ let angularStepSum = 0;
+ let angularStepCount = 0;
+ let maxFrameStepDeg = 0;
+ for (const frames of Object.values(clip.rotations)) {
+ for (const q of frames) {
+ for (const c of q) if (!Number.isFinite(c)) nonFinite++;
+ worstQuatNormError = Math.max(worstQuatNormError, Math.abs(qNorm(q) - 1));
+ }
+ for (let i = 1; i < frames.length; i++) {
+ const step = qAngleDeg(frames[i - 1], frames[i]);
+ if (!Number.isFinite(step)) {
+ nonFinite++;
+ continue;
+ }
+ angularStepSum += step;
+ angularStepCount++;
+ maxFrameStepDeg = Math.max(maxFrameStepDeg, step);
+ }
+ }
+ const meanStepDeg = angularStepCount ? angularStepSum / angularStepCount : 0;
+ const meanAngularSpeedDeg = meanStepDeg * (fps || 0);
+
+ // Loop seam: how far the last frame's pose is from the first across all
+ // driven bones. Reported for every clip; only enforced on loops.
+ let seamDeg = 0;
+ for (const frames of Object.values(clip.rotations)) {
+ if (frames.length < 2) continue;
+ seamDeg = Math.max(seamDeg, qAngleDeg(frames[0], frames[frames.length - 1]));
+ }
+
+ let rootSpeed = 0;
+ let rootTravel = 0;
+ if (clip.rootPositions && clip.rootPositions.length > 1) {
+ for (let i = 1; i < clip.rootPositions.length; i++) {
+ const a = clip.rootPositions[i - 1];
+ const b = clip.rootPositions[i];
+ for (const c of b) if (!Number.isFinite(c)) nonFinite++;
+ const d = Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+ rootTravel += d;
+ rootSpeed = Math.max(rootSpeed, d * (fps || 0));
+ }
+ }
+
+ const { left, right } = footTrajectories(clip);
+ const contactBand = REFERENCE_HIP_HEIGHT * 0.06;
+ const footSlide = Math.max(
+ worstPlantedDrift(left, contactBand),
+ worstPlantedDrift(right, contactBand),
+ );
+ let lowestFootY = Infinity;
+ for (const p of left) lowestFootY = Math.min(lowestFootY, p[1]);
+ for (const p of right) lowestFootY = Math.min(lowestFootY, p[1]);
+
+ return {
+ frames: clip.frames,
+ duration: clip.duration,
+ fps,
+ rotationTracks: clip.rotationTrackCount,
+ hasRootTrack: !!clip.rootPositions,
+ nonFinite,
+ timeRegressions,
+ worstQuatNormError,
+ meanAngularSpeedDeg,
+ maxFrameStepDeg,
+ loopSeamDeg: seamDeg,
+ rootTravelMetres: rootTravel,
+ maxRootSpeedMetresPerSecond: rootSpeed,
+ footSlideMetres: footSlide,
+ footSlideRatio: footSlide / REFERENCE_HIP_HEIGHT,
+ groundPenetrationMetres: Math.max(0, REST_FLOOR_Y - lowestFootY),
+ missingBones: REQUIRED_BONES.filter((b) => !clip.rotations[b]),
+ };
+}
+
+// ── Verdict ──────────────────────────────────────────────────────────────────
+
+/**
+ * Turn measurements into an accept/reject decision. Pure and synchronous: the
+ * cron, the batch runner and the tests all reach the same verdict for a clip.
+ *
+ * @param {ReturnType<typeof measureClip>} m
+ * @param {{ loop?: boolean, requestedDuration?: number|null, bounds?: typeof MOTION_BOUNDS }} [opts]
+ * @returns {{ pass: boolean, reasons: string[] }}
+ */
+export function decideMotionVerdict(m, opts = {}) {
+ const b = opts.bounds || MOTION_BOUNDS;
+ const reasons = [];
+
+ if (m.nonFinite > 0) reasons.push('non_finite_keyframes');
+ if (m.timeRegressions > 0) reasons.push('times_not_increasing');
+ if (m.frames < b.minFrames) reasons.push('too_few_frames');
+ if (m.frames > b.maxFrames) reasons.push('too_many_frames');
+ if (!(m.duration >= b.minDurationSeconds)) reasons.push('duration_too_short');
+ if (m.duration > b.maxDurationSeconds) reasons.push('duration_too_long');
+ if (m.rotationTracks < b.minRotationTracks) reasons.push('too_few_rotation_tracks');
+ if (m.worstQuatNormError > b.quatNormTolerance) reasons.push('quaternions_not_normalized');
+ if (m.missingBones.length) reasons.push('missing_required_bones');
+ if (m.meanAngularSpeedDeg < b.minMeanAngularSpeedDeg) reasons.push('motion_too_still');
+ if (m.maxFrameStepDeg > b.maxFrameAngularStepDeg) reasons.push('frame_discontinuity');
+ if (m.maxRootSpeedMetresPerSecond > b.maxRootSpeedMetresPerSecond) reasons.push('root_velocity_implausible');
+ if (m.footSlideRatio > b.maxFootSlideRatio) reasons.push('foot_slide');
+ if (m.groundPenetrationMetres > b.maxGroundPenetration) reasons.push('ground_penetration');
+ if (opts.loop && m.loopSeamDeg > b.maxLoopSeamDeg) reasons.push('loop_seam_open');
+
+ const requested = Number(opts.requestedDuration);
+ if (Number.isFinite(requested) && requested > 0) {
+ const drift = Math.abs(m.duration - requested) / requested;
+ if (drift > b.durationTolerance) reasons.push('duration_off_request');
+ }
+
+ return { pass: reasons.length === 0, reasons };
+}
+
+/**
+ * The whole gate: parse, measure, decide. A clip whose shape cannot be read is
+ * a reject with the structural reason attached rather than a thrown error, so a
+ * batch never dies on one malformed response.
+ *
+ * @param {unknown} raw the clip JSON as served by the worker
+ * @param {{ loop?: boolean, requestedDuration?: number|null, bounds?: typeof MOTION_BOUNDS }} [opts]
+ */
+export function gateMotionClip(raw, opts = {}) {
+ let clip;
+ try {
+ clip = readClip(raw);
+ } catch (err) {
+ return {
+ pass: false,
+ reasons: ['unreadable_clip'],
+ detail: err instanceof Error ? err.message : String(err),
+ metrics: null,
+ gateVersion: MOTION_GATE_VERSION,
+ };
+ }
+ const metrics = measureClip(clip);
+ const { pass, reasons } = decideMotionVerdict(metrics, opts);
+ return { pass, reasons, detail: '', metrics, gateVersion: MOTION_GATE_VERSION };
+}
+
+/** One human sentence per reason, for the reject sidecar and the batch report. */
+export const MOTION_GATE_RULES = Object.freeze({
+ unreadable_clip: 'the response was not a readable three.js AnimationClip',
+ non_finite_keyframes: 'a keyframe carried NaN or Infinity',
+ times_not_increasing: 'keyframe times did not advance monotonically',
+ too_few_frames: 'too few keyframes to read as motion',
+ too_many_frames: 'more keyframes than any library clip should carry',
+ duration_too_short: 'shorter than the shortest useful library clip',
+ duration_too_long: 'longer than the library ceiling',
+ too_few_rotation_tracks: 'drives too few bones to animate a humanoid',
+ quaternions_not_normalized: 'rotation keys are not unit quaternions',
+ missing_required_bones: 'a required humanoid bone has no track',
+ motion_too_still: 'the character barely moves; effectively a bind pose',
+ frame_discontinuity: 'a single frame jumps further than a body can rotate',
+ root_velocity_implausible: 'the root translates faster than a body can travel',
+ foot_slide: 'a planted foot skates across the floor',
+ ground_penetration: 'a foot sinks through the ground plane',
+ loop_seam_open: 'the loop pops because the last frame does not meet the first',
+ duration_off_request: 'the delivered length does not match what was requested',
+});
+
+/** @param {string[]} reasons */
+export function explainMotionGate(reasons) {
+ return reasons.map((r) => MOTION_GATE_RULES[r] || r);
+}
diff --git a/api/animations/library.js b/api/animations/library.js
index dc1905c68..659ed3050 100644
--- a/api/animations/library.js
+++ b/api/animations/library.js
@@ -18,33 +18,75 @@
// (embed viewer, pose deep-link lookup, the older gallery build) are unchanged.
// Paged responses add `offset` + `next_offset` (null on the last page); `total`
// is always the full catalog size regardless of paging.
+//
+// TWO MANIFESTS, ONE CATALOG. The Mixamo bake and the generative text-to-motion
+// seeder each own their own manifest object and never write the other's:
+//
+// animations/library/manifest.json scripts/mixamo-all.mjs
+// animations/library/generated/manifest.json scripts/gcp/seed-motion.mjs
+//
+// They are kept apart because each publisher REBUILDS its manifest from the set
+// it staged. Sharing one object would mean whichever ran last silently deleted
+// the other's clips from the library, and the deletion would look exactly like a
+// successful publish. Reading both here costs one extra cached object fetch and
+// makes that class of accident impossible.
+//
+// Order is curated-then-generated and never interleaved, so every offset a
+// caller already holds keeps pointing at the same clip when the generated set
+// grows.
import { cors, json, method, wrap } from '../_lib/http.js';
import { getObjectBuffer } from '../_lib/r2.js';
const MANIFEST_KEY = 'animations/library/manifest.json';
+const GENERATED_MANIFEST_KEY = 'animations/library/generated/manifest.json';
const MAX_PAGE = 1000;
-export default wrap(async (req, res) => {
- if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
- if (!method(req, res, ['GET'])) return;
-
- let clips = [];
- let generatedAt = null;
+/**
+ * Read one manifest object. A missing object is the expected state for the
+ * generated catalog before its first publish (and for the whole library before
+ * launch), so it degrades to an empty list; anything else is logged and also
+ * degrades, because a partial library beats a 5xx on a browse page.
+ *
+ * @param {string} key
+ * @returns {Promise<{ clips: any[], generatedAt: string | null }>}
+ */
+async function readManifest(key) {
try {
- const buf = await getObjectBuffer(MANIFEST_KEY);
+ const buf = await getObjectBuffer(key);
const parsed = JSON.parse(buf.toString('utf8'));
- clips = Array.isArray(parsed) ? parsed : Array.isArray(parsed.clips) ? parsed.clips : [];
- generatedAt = parsed.generated_at || null;
+ const clips = Array.isArray(parsed)
+ ? parsed
+ : Array.isArray(parsed.clips)
+ ? parsed.clips
+ : [];
+ return { clips, generatedAt: parsed.generated_at || null };
} catch (err) {
- // Not uploaded yet (NoSuchKey/404) is the expected pre-launch state;
- // anything else is a real storage error worth logging. Both degrade to
- // an empty library so the UI simply hides the section.
const code = err?.$metadata?.httpStatusCode;
if (err?.name !== 'NoSuchKey' && code !== 404) {
- console.error('[animations/library]', err?.message || err);
+ console.error('[animations/library]', key, err?.message || err);
}
+ return { clips: [], generatedAt: null };
}
+}
+
+export default wrap(async (req, res) => {
+ if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
+ if (!method(req, res, ['GET'])) return;
+
+ const [curated, generated] = await Promise.all([
+ readManifest(MANIFEST_KEY),
+ readManifest(GENERATED_MANIFEST_KEY),
+ ]);
+ // A name collision would give the pose deep-link two clips to resolve, so
+ // the curated catalog wins and the duplicate is dropped rather than served
+ // twice. The seeder namespaces its clips `gen-`, so this never fires in
+ // practice; it exists so a hand-published clip cannot shadow a preset.
+ const curatedNames = new Set(curated.clips.map((c) => c?.name));
+ const clips = curated.clips.concat(
+ generated.clips.filter((c) => c?.name && !curatedNames.has(c.name)),
+ );
+ const generatedAt = curated.generatedAt;
const total = clips.length;
res.setHeader('Cache-Control', 'public, s-maxage=300, stale-while-revalidate=3600');