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
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.jsnew file mode 100644index 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.jsindex 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');