create-aura3d 1.1.2 → 1.3.0

package/templates/animation-studio/scripts/build-clip-library.ts

@@ -0,0 +1,972 @@
+/**
+ * build-clip-library.ts — Phase 3.2: the HONEST "fetch the library from the prompt CLI".
+ *
+ * For each motion in the STANDARD performance vocabulary (idle / talk / gesture / point / nod /
+ * walk / run / react) this:
+ *
+ *   1. searches the live ~850k Aura3D catalog (the same hosted worker + direct-GLB filter as
+ *      `resolve-asset.ts`) for a rigged, animated GLB carrying that motion
+ *      (`assets resolve "<motion> animation"` — the `--animated` intent),
+ *   2. downloads + inspects it, requiring a humanoid skin and >=1 embedded clip,
+ *   3. EXTRACTS the embedded clip's real keyframe tracks straight out of the GLB binary
+ *      (accessor float data — not synthesized), maps each animated node to a canonical humanoid
+ *      bone via `inferHumanoidRig` from `@aura3d/animation`, and RE-EXPRESSES every track on the
+ *      STANDARD humanoid rig (`STANDARD_LIBRARY_RIG`, canonical `HUMANOID_BONES`). The result is
+ *      rig-neutral: its track targets are `<humanoidBone>.rotation` / `.translation`, exactly the
+ *      shape the procedural `standardHumanoidClips` use, so it retargets onto any character rig
+ *      via an identity-or-inferred `createHumanoidRetargetingMap` downstream.
+ *   4. writes each extracted clip to `public/clip-library/<id>.json` + a `manifest.json` recording
+ *      per-clip provenance (source title, url, license, attribution, original clip name, hash).
+ *
+ * HONESTY: this depends on the live catalog actually returning a suitable rigged+animated GLB for
+ * a query. Most catalog hits for "<motion>" are static props or single-rig characters; many GLBs
+ * are external-texture or insane-scale. When a query yields nothing usable we DO NOT fabricate a
+ * clip — we fall back to the procedural standard clip (`createStandardHumanoidClipDefinitions`)
+ * and record `source: "procedural-fallback"` in the manifest, logging it loudly. The loader
+ * (`loadExtractedClipLibrary`) then augments/overrides the procedural registry only where a real
+ * extracted clip exists.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  AnimationClipRegistry,
+  AnimationTrack,
+  HUMANOID_BONES,
+  STANDARD_CLIP_IDS,
+  STANDARD_LIBRARY_RIG,
+  createStandardHumanoidClipDefinitions,
+  inferHumanoidRigDetailed,
+  type AnimationClipDefinition,
+  type HumanoidBoneName,
+  type StandardClipId
+} from "@aura3d/animation";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const OUT_DIR = resolve(__dirname, "..", "public", "clip-library");
+const WORKER = "https://aura3d-asset-index-cron.newsroom.workers.dev/search";
+
+/**
+ * Per-motion catalog config:
+ *  - `query`: catalog search string (`--animated` intent baked in).
+ *  - `clipKeywords`: tokens we look for in the EMBEDDED clip name to confirm the clip actually
+ *    depicts this motion. A candidate whose clip name matches is strongly preferred; only if no
+ *    candidate's clip name matches do we accept a name-agnostic best-animated clip (recorded as a
+ *    weaker `nameMatch:false` in provenance — honest about the looseness of catalog semantics).
+ */
+interface MotionConfig {
+  readonly query: string;
+  readonly clipKeywords: readonly string[];
+}
+
+// Keywords are matched as whole tokens (+ short inflections) by `clipNameMatches`, so use base
+// word stems that appear as standalone tokens in real clip names (Mixamo/Blender conventions).
+const MOTION_QUERIES: Readonly<Record<StandardClipId, MotionConfig>> = {
+  idle: { query: "idle breathing character animation", clipKeywords: ["idle", "breathing", "stand"] },
+  talk: { query: "talking gesture character animation", clipKeywords: ["talk", "speak", "speaking", "talking", "dialogue"] },
+  gesture: { query: "wave gesture character animation", clipKeywords: ["wave", "waving", "gesture", "greet", "hello"] },
+  point: { query: "pointing character animation", clipKeywords: ["point", "pointing", "aim", "indicate"] },
+  nod: { query: "nodding head character animation", clipKeywords: ["nod", "nodding", "yes"] },
+  walk: { query: "walk cycle character animation", clipKeywords: ["walk", "walking", "stride"] },
+  run: { query: "running character animation", clipKeywords: ["run", "running", "sprint", "jog"] },
+  react: { query: "surprised reaction character animation", clipKeywords: ["react", "reaction", "surprised", "flinch", "recoil"] }
+};
+
+// ----------------------------------------------------------------------------------------------
+// Catalog search (mirrors resolve-asset.ts: wide ranked list of direct .glb, commercial-OK)
+// ----------------------------------------------------------------------------------------------
+
+interface CatalogResult {
+  id: string;
+  title: string;
+  source: string;
+  url: string;
+  license?: string;
+  attribution?: string;
+}
+
+async function searchCatalog(query: string): Promise<CatalogResult[]> {
+  const url = `${WORKER}?q=${encodeURIComponent(query)}&limit=60&commercial=true&animated=true`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`catalog ${res.status}`);
+  const data = (await res.json()) as { results?: CatalogResult[] };
+  return (data.results ?? []).filter((r) => typeof r.url === "string" && /\.glb($|\?)/.test(r.url));
+}
+
+// ----------------------------------------------------------------------------------------------
+// GLB parsing — JSON chunk + BIN chunk, enough to read animation sampler accessors.
+// ----------------------------------------------------------------------------------------------
+
+interface ParsedGlb {
+  readonly json: GltfJson;
+  readonly bin: Buffer;
+}
+
+interface GltfJson {
+  accessors?: GltfAccessor[];
+  bufferViews?: GltfBufferView[];
+  buffers?: { byteLength: number; uri?: string }[];
+  nodes?: { name?: string }[];
+  skins?: { joints?: number[] }[];
+  meshes?: { primitives?: { attributes?: Record<string, number>; indices?: number }[] }[];
+  images?: { bufferView?: number }[];
+  animations?: GltfAnimation[];
+}
+
+interface GltfAccessor {
+  bufferView?: number;
+  byteOffset?: number;
+  componentType: number;
+  count: number;
+  type: "SCALAR" | "VEC2" | "VEC3" | "VEC4" | "MAT4" | string;
+}
+
+interface GltfBufferView {
+  buffer: number;
+  byteOffset?: number;
+  byteLength: number;
+  byteStride?: number;
+}
+
+interface GltfAnimation {
+  name?: string;
+  channels: { sampler: number; target: { node?: number; path: string } }[];
+  samplers: { input: number; output: number; interpolation?: "LINEAR" | "STEP" | "CUBICSPLINE" }[];
+}
+
+function parseGlb(buf: Buffer): ParsedGlb | null {
+  if (buf.length < 20 || buf.readUInt32LE(0) !== 0x46546c67) return null; // "glTF"
+  const jsonLen = buf.readUInt32LE(12);
+  const jsonStart = 20;
+  const json = JSON.parse(buf.slice(jsonStart, jsonStart + jsonLen).toString("utf8")) as GltfJson;
+  // BIN chunk follows the JSON chunk (8-byte chunk header: length + type 0x004E4942).
+  let bin = Buffer.alloc(0);
+  const binHeader = jsonStart + jsonLen;
+  if (binHeader + 8 <= buf.length && buf.readUInt32LE(binHeader + 4) === 0x004e4942) {
+    const binLen = buf.readUInt32LE(binHeader);
+    bin = buf.slice(binHeader + 8, binHeader + 8 + binLen);
+  }
+  return { json, bin };
+}
+
+const COMPONENT_BYTES: Record<number, number> = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 };
+const TYPE_COMPONENTS: Record<string, number> = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT4: 16 };
+
+/** Read an accessor as an array of number tuples (one tuple per element). Float accessors only. */
+function readAccessor(glb: ParsedGlb, index: number): number[][] {
+  const acc = glb.json.accessors?.[index];
+  if (!acc || acc.bufferView === undefined) return [];
+  const view = glb.json.bufferViews?.[acc.bufferView];
+  if (!view) return [];
+  const comps = TYPE_COMPONENTS[acc.type] ?? 1;
+  const compBytes = COMPONENT_BYTES[acc.componentType] ?? 4;
+  const elemBytes = comps * compBytes;
+  const stride = view.byteStride && view.byteStride > 0 ? view.byteStride : elemBytes;
+  const base = (view.byteOffset ?? 0) + (acc.byteOffset ?? 0);
+  const out: number[][] = [];
+  for (let i = 0; i < acc.count; i += 1) {
+    const elemStart = base + i * stride;
+    const tuple: number[] = [];
+    for (let c = 0; c < comps; c += 1) {
+      const off = elemStart + c * compBytes;
+      if (off + compBytes > glb.bin.length) return out; // truncated/malformed — stop honestly
+      // We only consume FLOAT (5126) sampler data; quantized inputs are rare for animation.
+      tuple.push(acc.componentType === 5126 ? glb.bin.readFloatLE(off) : glb.bin.readInt32LE(off));
+    }
+    out.push(tuple);
+  }
+  return out;
+}
+
+// ----------------------------------------------------------------------------------------------
+// Normalization (rest-pose reconciliation): make extracted tracks USABLE on the standard rig.
+//
+// Raw catalog clips lay the character DOWN / contort it for three independent reasons:
+//   (a) UNITS — many GLBs author hips translation in centimetres / raw exporter units, so a single
+//       stride reads as ~30 instead of ~0.3m. We detect the source scale from the magnitude of the
+//       hips translation (a clean stride is well under ~1.5m; anything an order of magnitude larger
+//       is cm/raw) and divide every translation component by it.
+//   (b) HIPS REST-POSE OFFSET — the clip's bind/first frame is not the standard rig's rest pose: the
+//       hips carry a constant world-position offset (e.g. y≈32) AND a constant rotation offset (a
+//       Z-up→Y-up axis swap or a lean). We re-anchor by subtracting the first frame: translations
+//       become RELATIVE to frame 0 (dropping absolute world position).
+//   (c) PER-BONE REST-POSE OFFSET (the M6 blocker) — EVERY bone (toes/legs/feet/head/shoulders) of an
+//       extracted clip carries a baked, CONSTANT axis-conversion rest rotation (toes/feet ~180°, head
+//       ~90°). Because the standard library rig has an IDENTITY rest, retargeting (Rt = Rt0·Rs0⁻¹·Ra,
+//       Rs0 = I) applies that constant offset straight onto the target → the character renders
+//       laid-down / contorted, and a range-based gate misses it (a constant offset never moves).
+//
+//   Reconciliation: estimate each rotation track's SOURCE REST rotation (the part that is CONSTANT
+//   across the clip — pure rest mismatch) and RE-ANCHOR every keyframe relative to it:
+//       R_motion(t) = R_rest⁻¹ · R(t).
+//   This removes the baked 90°/180° offset (R_motion(rest frame) = identity = standard rest = upright)
+//   while preserving the per-frame RELATIVE motion (leg swing, head turn). The rest estimate is the
+//   temporal-MEDIAN quaternion (robust to the swinging extremes of a walk/run), which for a static
+//   offset bone equals the offset and for a moving bone equals its mid-pose.
+//
+// Post-condition (matches the loader sanity gate in animation-performance.ts):
+//   hips:  max |translation component| ≲ 1.0  and  max (1 - |w|) ≲ 0.2;
+//   every rotation bone returns near rest at some frame: worstFloor = max over bones of
+//   min over keyframes of (1 - |w|)  < 0.15.
+// ----------------------------------------------------------------------------------------------
+
+const HIPS_TRANS_TARGET = /(^|[.\/])hips\.translation$/i;
+const ROT_TARGET = /\.rotation$/i;
+
+/** Quaternion conjugate (= inverse for unit quaternions). Layout is [x, y, z, w]. */
+function quatConjugate(q: readonly number[]): [number, number, number, number] {
+  return [-(q[0] ?? 0), -(q[1] ?? 0), -(q[2] ?? 0), q[3] ?? 1];
+}
+
+/** Hamilton product a*b for [x, y, z, w] quaternions. */
+function quatMultiply(a: readonly number[], b: readonly number[]): [number, number, number, number] {
+  const [ax, ay, az, aw] = [a[0] ?? 0, a[1] ?? 0, a[2] ?? 0, a[3] ?? 1];
+  const [bx, by, bz, bw] = [b[0] ?? 0, b[1] ?? 0, b[2] ?? 0, b[3] ?? 1];
+  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 quatNormalize(q: readonly number[]): [number, number, number, number] {
+  const len = Math.hypot(q[0] ?? 0, q[1] ?? 0, q[2] ?? 0, q[3] ?? 1) || 1;
+  return [(q[0] ?? 0) / len, (q[1] ?? 0) / len, (q[2] ?? 0) / len, (q[3] ?? 1) / len];
+}
+
+/**
+ * Estimate a rotation track's CONSTANT part (its source rest rotation) as the temporal-median
+ * quaternion. We first flip every keyframe into the same hemisphere as the first (quaternions double-
+ * cover SO(3): q and -q are the same rotation), then take the component-wise median and renormalize.
+ *
+ * Why median, not mean or first-frame: the median is robust to the swinging extremes of a cyclic clip
+ * (a walk's legs reach far in both directions; the median sits at the neutral mid-pose), and for a
+ * bone that carries ONLY a baked rest offset (toes/feet never move) the median IS that offset exactly.
+ * Re-anchoring by R_rest⁻¹ then sends the neutral pose to identity (= the standard rig's upright rest)
+ * and keeps the swing symmetric about it. Returns identity for an empty/short track.
+ */
+function quatRestEstimate(quats: readonly (readonly number[])[]): [number, number, number, number] {
+  if (quats.length === 0) return [0, 0, 0, 1];
+  const ref = quatNormalize(quats[0]!);
+  const aligned = quats.map((raw) => {
+    const q = quatNormalize(raw);
+    const dot = q[0] * ref[0] + q[1] * ref[1] + q[2] * ref[2] + q[3] * ref[3];
+    return dot < 0 ? ([-q[0], -q[1], -q[2], -q[3]] as [number, number, number, number]) : q;
+  });
+  const median = (i: number): number => {
+    const col = aligned.map((q) => q[i]!).sort((a, b) => a - b);
+    const n = col.length;
+    return n % 2 ? col[(n - 1) / 2]! : (col[n / 2 - 1]! + col[n / 2]!) / 2;
+  };
+  return quatNormalize([median(0), median(1), median(2), median(3)]);
+}
+
+export interface HipsStats {
+  readonly maxTranslation: number;
+  readonly maxRotationOffset: number;
+}
+
+/** Measure the worst hips translation magnitude + rotation offset (1 - |w|) across a track list. */
+export function measureHips(tracks: readonly { target: string; keyframes: readonly { value: readonly number[] }[] }[]): HipsStats {
+  let maxTranslation = 0;
+  let maxRotationOffset = 0;
+  const isHipsRot = (t: string): boolean => /(^|[.\/])hips\.rotation$/i.test(t);
+  for (const tr of tracks) {
+    const isT = HIPS_TRANS_TARGET.test(tr.target);
+    const isR = isHipsRot(tr.target);
+    if (!isT && !isR) continue;
+    for (const kf of tr.keyframes) {
+      const v = kf.value ?? [];
+      if (isT) for (const c of v) maxTranslation = Math.max(maxTranslation, Math.abs(c));
+      if (isR && v.length >= 4) maxRotationOffset = Math.max(maxRotationOffset, 1 - Math.abs(v[3]!));
+    }
+  }
+  return { maxTranslation, maxRotationOffset };
+}
+
+/**
+ * Worst per-bone REST FLOOR across a track list: for each rotation track take the MIN offset from
+ * identity over its keyframes (the closest that bone ever gets to rest), then take the MAX over bones.
+ * This mirrors the loader sanity gate (animation-performance.ts): a bone with a baked constant offset
+ * never returns near rest → a high floor; a reconciled clip has every bone return to ~identity at its
+ * rest frame → a low floor. The gate ACCEPTS a clip iff this value < 0.15.
+ */
+export function worstRestFloor(
+  tracks: readonly { target: string; keyframes: readonly { value: readonly number[] }[] }[]
+): { value: number; bone: string } {
+  let value = 0;
+  let bone = "";
+  for (const tr of tracks) {
+    if (!ROT_TARGET.test(tr.target)) continue;
+    let floor = Infinity;
+    for (const kf of tr.keyframes) {
+      const v = kf.value ?? [];
+      if (v.length < 4) continue;
+      floor = Math.min(floor, 1 - Math.abs(v[3]!));
+    }
+    if (floor !== Infinity && floor > value) {
+      value = floor;
+      bone = tr.target;
+    }
+  }
+  return { value, bone };
+}
+
+/**
+ * Detect the source-unit scale of the hips translation. We look at the peak absolute translation
+ * component: a clean clip on a metre rig keeps this under ~1.5m (a stride plus a little bob). When it
+ * is far larger the clip is in cm/raw units, so we divide by the smallest power-of-ten that brings the
+ * peak back under ~1.5 (e.g. peak 32 → /100 → 0.32m; peak 320 → /1000). Returns 1 when already metric.
+ */
+function detectHipsScale(maxAbsTranslation: number): number {
+  if (maxAbsTranslation <= 1.5) return 1;
+  let scale = 1;
+  while (maxAbsTranslation / scale > 1.5) scale *= 10;
+  return scale;
+}
+
+/**
+ * NORMALIZE a set of extracted tracks — returning a new array — with full rest-pose reconciliation.
+ *
+ *   • hips.translation  → scaled to metres + re-anchored to frame 0 (relative root motion).
+ *   • EVERY rotation track (hips and every limb) → re-anchored by its estimated source rest rotation:
+ *       R_motion(t) = R_rest⁻¹ · R(t),  R_rest = temporal-median quaternion of the track.
+ *     This strips the baked, constant 90°/180° axis-conversion offset each bone carries (so the
+ *     reconciled clip sits at the standard rig's UPRIGHT identity rest at its neutral pose) while
+ *     preserving the per-frame relative motion.
+ *
+ * Idempotent for the rotation part: re-normalizing an already-reconciled clip leaves the median at
+ * ~identity, so R_rest⁻¹·R(t) ≈ R(t). The hips-translation anchor is likewise a no-op once at origin.
+ */
+export function normalizeExtractedTracks<T extends AnimationTrack>(tracks: readonly T[]): AnimationTrack[] {
+  // 1) UNITS — detect the hips-translation scale from the raw peak magnitude.
+  let peakTrans = 0;
+  for (const tr of tracks) {
+    if (!HIPS_TRANS_TARGET.test(tr.target)) continue;
+    for (const kf of tr.keyframes) for (const c of kf.value as number[]) peakTrans = Math.max(peakTrans, Math.abs(c));
+  }
+  const scale = detectHipsScale(peakTrans);
+
+  return tracks.map((tr) => {
+    const isT = HIPS_TRANS_TARGET.test(tr.target);
+    const isR = ROT_TARGET.test(tr.target);
+
+    if (isT) {
+      // Scale to metres, then re-anchor: subtract the first frame so motion is RELATIVE to frame 0
+      // (drops the absolute hips world-position offset that pins the character above/below the floor).
+      const scaled = tr.keyframes.map((kf) => ({
+        time: kf.time,
+        interpolation: kf.interpolation,
+        value: (kf.value as number[]).map((c) => c / scale)
+      }));
+      const anchor = scaled[0]?.value ?? [0, 0, 0];
+      return new AnimationTrack({
+        target: tr.target,
+        valueType: tr.valueType,
+        keyframes: scaled.map((kf) => ({
+          time: kf.time,
+          interpolation: kf.interpolation,
+          value: kf.value.map((c, i) => +(c - (anchor[i] ?? 0)).toFixed(6)) as never
+        }))
+      });
+    }
+
+    if (!isR) return tr; // non-hips translation (none today) / other tracks pass through.
+
+    // REST-POSE RECONCILIATION (the M6 fix): re-anchor by the CONSTANT (rest) part of this bone's
+    // rotation, estimated as the temporal-median quaternion. q'_k = inverse(R_rest) * q_k. For a
+    // static offset bone this sends every frame to ~identity; for a moving bone it centres the
+    // motion on identity — either way the bone returns near the standard rig's upright rest.
+    const quats = tr.keyframes.map((kf) => kf.value as number[]).filter((v) => Array.isArray(v) && v.length >= 4);
+    if (quats.length === 0) return tr;
+    const invRest = quatConjugate(quatRestEstimate(quats));
+    return new AnimationTrack({
+      target: tr.target,
+      valueType: tr.valueType,
+      keyframes: tr.keyframes.map((kf) => {
+        const v = kf.value as number[];
+        if (!Array.isArray(v) || v.length < 4) return kf;
+        const q = quatNormalize(v);
+        let rel = quatMultiply(invRest, q);
+        // Keep w >= 0 so the offset metric (1 - |w|) is read off the canonical hemisphere.
+        if (rel[3] < 0) rel = [-rel[0], -rel[1], -rel[2], -rel[3]];
+        return {
+          time: kf.time,
+          interpolation: kf.interpolation,
+          value: rel.map((c) => +c.toFixed(6)) as never
+        };
+      })
+    });
+  });
+}
+
+// ----------------------------------------------------------------------------------------------
+// Extraction: GLB animation channels -> rig-neutral AnimationTrack[] on the standard humanoid.
+// ----------------------------------------------------------------------------------------------
+
+interface ExtractedClip {
+  readonly tracks: AnimationTrack[];
+  readonly duration: number;
+  readonly animatedHumanoidBones: number;
+  readonly sourceClipName: string;
+}
+
+/**
+ * Build node-index -> humanoid bone map by inferring the source rig from the skinned joint names
+ * (falling back to all node names). Returns a Map<nodeIndex, HumanoidBoneName>.
+ */
+function buildNodeBoneMap(glb: ParsedGlb): { map: Map<number, HumanoidBoneName>; mappedRequired: number } {
+  const nodes = glb.json.nodes ?? [];
+  // Prefer the first skin's joints (the actual deforming skeleton); else every named node.
+  const jointIdx = glb.json.skins?.[0]?.joints ?? nodes.map((_, i) => i);
+  const namedJoints = jointIdx
+    .map((ni) => ({ ni, name: nodes[ni]?.name }))
+    .filter((j): j is { ni: number; name: string } => typeof j.name === "string" && j.name.length > 0);
+
+  const inference = inferHumanoidRigDetailed(namedJoints.map((j) => j.name), {
+    id: "extracted-source",
+    name: "Extracted source rig"
+  });
+
+  // inference.rig.bones[bone].name is the resolved source NODE NAME. Invert back to node index.
+  const nameToNode = new Map<string, number>();
+  for (const j of namedJoints) nameToNode.set(j.name, j.ni);
+
+  const map = new Map<number, HumanoidBoneName>();
+  for (const bone of HUMANOID_BONES) {
+    const binding = inference.rig.bones[bone];
+    if (!binding) continue;
+    const ni = nameToNode.get(binding.name);
+    if (ni !== undefined) map.set(ni, bone);
+  }
+  const required = HUMANOID_BONES.length - inference.missingRequired.length;
+  return { map, mappedRequired: required };
+}
+
+/**
+ * Extract one GLB animation (by index) onto the standard humanoid rig. Only translation/rotation
+ * channels targeting a mapped humanoid bone are kept; scale channels are dropped (the standard
+ * library is rotation/translation-only). Times are rebased to start at 0.
+ */
+function extractAnimation(
+  glb: ParsedGlb,
+  animIndex: number,
+  nodeBone: Map<number, HumanoidBoneName>
+): ExtractedClip | null {
+  const anim = glb.json.animations?.[animIndex];
+  if (!anim) return null;
+  const tracks: AnimationTrack[] = [];
+  let minTime = Infinity;
+  let maxTime = 0;
+  let animatedHumanoidBones = 0;
+  const seen = new Set<string>();
+
+  for (const channel of anim.channels) {
+    const node = channel.target.node;
+    if (node === undefined) continue;
+    const bone = nodeBone.get(node);
+    if (!bone) continue; // not a humanoid bone -> not part of the rig-neutral library clip
+    const path = channel.target.path;
+    if (path !== "rotation" && path !== "translation") continue; // drop scale/weights
+    // The standard library is rotation-driven; only the hips (root) carry translation (bob/sway).
+    // Limb translations don't retarget meaningfully (no length scaling here) and bloat the clip.
+    if (path === "translation" && bone !== "hips") continue;
+
+    const sampler = anim.samplers[channel.sampler];
+    if (!sampler) continue;
+    const times = readAccessor(glb, sampler.input);
+    const values = readAccessor(glb, sampler.output);
+    if (times.length === 0 || values.length === 0) continue;
+
+    const valueType = path === "rotation" ? "quaternion" : "vector3";
+    const compsPerKey = path === "rotation" ? 4 : 3;
+    // CUBICSPLINE packs 3 values (in-tan, value, out-tan) per key; we take the middle value and
+    // emit linear keys (honest simplification — we don't re-derive tangents).
+    const cubic = sampler.interpolation === "CUBICSPLINE";
+    const valuesPerKey = cubic ? compsPerKey * 3 : compsPerKey;
+    const flat = values.flat();
+
+    const keyframes: { time: number; value: number[]; interpolation: "linear" }[] = [];
+    for (let k = 0; k < times.length; k += 1) {
+      const t = times[k]![0]!;
+      const start = k * valuesPerKey + (cubic ? compsPerKey : 0);
+      if (start + compsPerKey > flat.length) break;
+      const value = flat.slice(start, start + compsPerKey);
+      if (value.some((v) => !Number.isFinite(v))) continue;
+      keyframes.push({ time: t, value, interpolation: "linear" });
+    }
+    if (keyframes.length < 2) continue;
+
+    for (const kf of keyframes) {
+      if (kf.time < minTime) minTime = kf.time;
+      if (kf.time > maxTime) maxTime = kf.time;
+    }
+
+    const target = `${bone}.${path}`;
+    if (seen.has(target)) continue; // one track per bone/path (first sampler wins)
+    seen.add(target);
+    if (path === "rotation") animatedHumanoidBones += 1;
+
+    tracks.push(
+      new AnimationTrack({
+        target,
+        valueType,
+        keyframes: keyframes.map((kf) => ({
+          time: kf.time,
+          value: kf.value as never,
+          interpolation: kf.interpolation
+        }))
+      })
+    );
+  }
+
+  if (tracks.length === 0 || !Number.isFinite(minTime)) return null;
+
+  // Rebase times so the clip starts at t=0 (some exporters start mid-timeline).
+  const rebased = tracks.map(
+    (tr) =>
+      new AnimationTrack({
+        target: tr.target,
+        valueType: tr.valueType,
+        keyframes: tr.keyframes.map((kf) => ({ ...kf, time: +(kf.time - minTime).toFixed(6) }))
+      })
+  );
+  const duration = +(maxTime - minTime).toFixed(6);
+  // NORMALIZE the hips so the clip is usable on the standard rig (metres, rest-pose re-anchored to
+  // identity/origin) — otherwise raw-unit translation + bind offset displaces the character to the floor.
+  const normalized = normalizeExtractedTracks(rebased);
+  return {
+    tracks: normalized,
+    duration: duration > 0 ? duration : 1,
+    animatedHumanoidBones,
+    sourceClipName: anim.name ?? `animation-${animIndex}`
+  };
+}
+
+// ----------------------------------------------------------------------------------------------
+// Per-motion resolution: search -> download -> inspect -> extract.
+// ----------------------------------------------------------------------------------------------
+
+interface MotionProvenance {
+  readonly clipId: StandardClipId;
+  readonly source: "catalog-extracted" | "procedural-fallback";
+  readonly sourceTitle?: string;
+  readonly sourceUrl?: string;
+  readonly license?: string;
+  readonly attribution?: string;
+  readonly originalClipName?: string;
+  /**
+   * The UNIVERSAL vocabulary slot this source clip was mapped onto (idle/talk/gesture/…). Stored
+   * EXPLICITLY in provenance (separate from the source's own `originalClipName`) so a catalog name
+   * like "Moon Walk" is never confused for the product-facing id — the id is always `clipId`, and
+   * `mappedIntent === clipId` records the mapping decision as provenance metadata, not a concept.
+   */
+  readonly mappedIntent: StandardClipId;
+  /** ISO date the clip was resolved/extracted (provenance metadata). */
+  readonly date: string;
+  /**
+   * 0–100 confidence that this extracted clip is a faithful, retargetable source for `mappedIntent`:
+   * animated-humanoid-bone breadth + a confident clip-name match + a sane duration. A procedural
+   * fallback scores 0 (no real source motion).
+   */
+  readonly qualityScore: number;
+  readonly hash?: string;
+  readonly duration: number;
+  readonly trackCount: number;
+  readonly animatedHumanoidBones?: number;
+  /**
+   * True when the embedded clip NAME contained one of the motion's keywords (a confident semantic
+   * match). False means we accepted a name-agnostic best-animated clip because no candidate's clip
+   * name matched — the motion is real and rig-neutral, but its semantic fit is unverified.
+   */
+  readonly nameMatch?: boolean;
+  readonly note?: string;
+}
+
+/**
+ * Per-clip quality score (0–100) for an EXTRACTED source clip: breadth of animated humanoid bones
+ * (the body-acting signal), a confident clip-name match (semantic fit), and a sane duration. This
+ * is provenance metadata only — the universal `clipId` is always the product-facing id.
+ */
+function clipQualityScore(animatedHumanoidBones: number, nameMatch: boolean, duration: number): number {
+  const breadth = Math.min(animatedHumanoidBones, 24) * 3; // up to 72 for a full-body clip
+  const semantic = nameMatch ? 20 : 0;                     // confident keyword match
+  const durationOk = duration >= 0.5 && duration <= 30 ? 8 : 0;
+  return Math.max(0, Math.min(100, Math.round(breadth + semantic + durationOk)));
+}
+
+interface MotionResult {
+  readonly clip: AnimationClipDefinition<StandardClipId>;
+  readonly provenance: MotionProvenance;
+}
+
+/** A fully-extracted candidate, carried while we scan for the best (name-matching) one. */
+interface Candidate {
+  readonly extracted: ExtractedClip;
+  readonly catalog: CatalogResult;
+  readonly hash: string;
+  readonly nameMatch: boolean;
+}
+
+function proceduralFor(clipId: StandardClipId, note: string): MotionResult {
+  const proc = createStandardHumanoidClipDefinitions().find((c) => c.id === clipId)!;
+  return {
+    clip: proc,
+    provenance: {
+      clipId,
+      source: "procedural-fallback",
+      mappedIntent: clipId,
+      date: new Date().toISOString(),
+      qualityScore: 0, // no real source motion — the procedural baseline carries no provenance quality
+      duration: proc.duration,
+      trackCount: proc.tracks?.length ?? 0,
+      note
+    }
+  };
+}
+
+/**
+ * Match a motion keyword against a clip name on TOKEN boundaries, not raw substring — otherwise
+ * "nod" spuriously matches "RootNodeAction" ("root NODE action"). We split the name on common
+ * separators + camelCase humps, then require a token to EQUAL the keyword (or the keyword + a
+ * short inflection like "-s"/"-ing"/"-ed"). This keeps "nameMatch" an honest, conservative signal:
+ * "walk"/"walks"/"walking" match the walk motion, but "node" does not match "nod".
+ */
+function clipNameMatches(name: string, keywords: readonly string[]): boolean {
+  const tokens = name
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z]+/)
+    .filter(Boolean);
+  const inflections = ["", "s", "ing", "ed", "er"];
+  return keywords.some((k) => tokens.some((tok) => inflections.some((suf) => tok === k + suf)));
+}
+
+async function resolveMotion(clipId: StandardClipId, config: MotionConfig): Promise<MotionResult> {
+  let candidates: CatalogResult[];
+  try {
+    candidates = await searchCatalog(config.query);
+  } catch (err) {
+    console.error(`  [${clipId}] catalog search failed (${(err as Error).message}) -> procedural fallback`);
+    return proceduralFor(clipId, `catalog search failed: ${(err as Error).message}`);
+  }
+  console.error(`  [${clipId}] "${config.query}" -> ${candidates.length} GLB candidates`);
+
+  // Scan candidates. A clip-name match short-circuits (best possible). Otherwise keep the
+  // name-agnostic candidate with the most animated humanoid bones as a weaker fallback.
+  let fallback: Candidate | null = null;
+  // Cap downloads per motion so a flaky/huge candidate list can't run forever.
+  let downloads = 0;
+  for (const c of candidates) {
+    if (downloads >= 12) break;
+    let buf: Buffer;
+    try {
+      const r = await fetch(c.url);
+      if (!r.ok) continue;
+      buf = Buffer.from(await r.arrayBuffer());
+      downloads += 1;
+    } catch {
+      continue;
+    }
+    const glb = parseGlb(buf);
+    if (!glb) continue;
+    // We only need skeleton + animation data here. Require: a skin and at least one animation.
+    if (!(glb.json.skins?.length && glb.json.animations?.length)) continue;
+    if (buf.length > 60 * 1024 * 1024) continue; // keep extraction snappy
+
+    const { map, mappedRequired } = buildNodeBoneMap(glb);
+    if (mappedRequired < 10) continue; // require a usable humanoid
+
+    // Among this GLB's animations, prefer one whose NAME matches the motion; else most-animated.
+    let named: ExtractedClip | null = null;
+    let richest: ExtractedClip | null = null;
+    for (let ai = 0; ai < (glb.json.animations?.length ?? 0); ai += 1) {
+      const extracted = extractAnimation(glb, ai, map);
+      if (!extracted || extracted.animatedHumanoidBones < 3) continue;
+      if (!richest || extracted.animatedHumanoidBones > richest.animatedHumanoidBones) richest = extracted;
+      if (
+        clipNameMatches(extracted.sourceClipName, config.clipKeywords) &&
+        (!named || extracted.animatedHumanoidBones > named.animatedHumanoidBones)
+      ) {
+        named = extracted;
+      }
+    }
+
+    const hash = `sha256-${createHash("sha256").update(buf).digest("hex")}`;
+    if (named) {
+      return buildResult(clipId, { extracted: named, catalog: c, hash, nameMatch: true });
+    }
+    if (richest && (!fallback || richest.animatedHumanoidBones > fallback.extracted.animatedHumanoidBones)) {
+      fallback = { extracted: richest, catalog: c, hash, nameMatch: false };
+    }
+  }
+
+  if (fallback) {
+    console.error(`  [${clipId}] no name-matched clip; using best-animated catalog clip (nameMatch:false)`);
+    return buildResult(clipId, fallback);
+  }
+
+  console.error(`  [${clipId}] no usable rigged+animated GLB -> procedural fallback`);
+  return proceduralFor(clipId, "no catalog GLB yielded an extractable humanoid clip");
+}
+
+function buildResult(clipId: StandardClipId, cand: Candidate): MotionResult {
+  const { extracted: best, catalog: c, hash, nameMatch } = cand;
+  const clip: AnimationClipDefinition<StandardClipId> = {
+    id: clipId,
+    name: clipId,
+    duration: best.duration,
+    frameRate: 30,
+    loop: clipId === "idle" || clipId === "talk" || clipId === "walk" || clipId === "run",
+    tags: [clipId, "performance", "extracted"],
+    tracks: best.tracks,
+    source: "aura3d.catalog-extracted",
+    metadata: {
+      rig: STANDARD_LIBRARY_RIG.id,
+      extracted: true,
+      nameMatch,
+      sourceClipName: best.sourceClipName,
+      sourceTitle: c.title,
+      sourceUrl: c.url,
+      license: c.license ?? "CC-BY-4.0",
+      attribution: c.attribution ?? c.source
+    }
+  };
+  console.error(
+    `  [${clipId}] EXTRACTED "${best.sourceClipName}" from ${c.title} ` +
+      `(${best.tracks.length} tracks, ${best.animatedHumanoidBones} bones, ${best.duration.toFixed(2)}s, ` +
+      `nameMatch:${nameMatch}, ${c.source})`
+  );
+  return {
+    clip,
+    provenance: {
+      clipId,
+      source: "catalog-extracted",
+      sourceTitle: c.title,
+      sourceUrl: c.url,
+      license: c.license ?? "CC-BY-4.0",
+      attribution: c.attribution ?? c.source,
+      originalClipName: best.sourceClipName,
+      mappedIntent: clipId,
+      date: new Date().toISOString(),
+      qualityScore: clipQualityScore(best.animatedHumanoidBones, nameMatch, best.duration),
+      hash,
+      duration: best.duration,
+      trackCount: best.tracks.length,
+      animatedHumanoidBones: best.animatedHumanoidBones,
+      nameMatch
+    }
+  };
+}
+
+// ----------------------------------------------------------------------------------------------
+// Serialization (write extracted clips + manifest under public/clip-library/).
+// ----------------------------------------------------------------------------------------------
+
+interface SerializedClipFile {
+  readonly id: StandardClipId;
+  readonly name: string;
+  readonly duration: number;
+  readonly frameRate: number;
+  readonly loop: boolean;
+  readonly tags: readonly string[];
+  readonly source: string;
+  readonly rig: string;
+  readonly tracks: { target: string; valueType: string; keyframes: unknown[] }[];
+  readonly provenance: MotionProvenance;
+}
+
+function serializeClip(result: MotionResult): SerializedClipFile {
+  const { clip, provenance } = result;
+  return {
+    id: clip.id,
+    name: clip.name ?? clip.id,
+    duration: clip.duration,
+    frameRate: clip.frameRate ?? 30,
+    loop: clip.loop ?? true,
+    tags: clip.tags ?? [],
+    source: clip.source ?? "unknown",
+    rig: STANDARD_LIBRARY_RIG.id,
+    tracks: (clip.tracks ?? []).map((tr) => {
+      const t = tr as unknown as AnimationTrack;
+      return { target: t.target, valueType: t.valueType, keyframes: [...t.keyframes] };
+    }),
+    provenance
+  };
+}
+
+export interface ClipLibraryManifest {
+  readonly generatedAt: string;
+  readonly rig: string;
+  readonly vocabulary: readonly StandardClipId[];
+  readonly extractedCount: number;
+  readonly fallbackCount: number;
+  readonly clips: readonly MotionProvenance[];
+}
+
+async function build(): Promise<void> {
+  mkdirSync(OUT_DIR, { recursive: true });
+  const results: MotionResult[] = [];
+  for (const clipId of STANDARD_CLIP_IDS) {
+    results.push(await resolveMotion(clipId, MOTION_QUERIES[clipId]));
+  }
+  const named = results.filter((r) => r.provenance.nameMatch === true).length;
+  console.error(`  (${named}/${results.length} are confident clip-name matches)`);
+
+  for (const result of results) {
+    const file = serializeClip(result);
+    writeFileSync(resolve(OUT_DIR, `${result.clip.id}.json`), JSON.stringify(file, null, 2));
+  }
+
+  const extractedCount = results.filter((r) => r.provenance.source === "catalog-extracted").length;
+  const manifest: ClipLibraryManifest = {
+    generatedAt: new Date().toISOString(),
+    rig: STANDARD_LIBRARY_RIG.id,
+    vocabulary: [...STANDARD_CLIP_IDS],
+    extractedCount,
+    fallbackCount: results.length - extractedCount,
+    clips: results.map((r) => r.provenance)
+  };
+  writeFileSync(resolve(OUT_DIR, "manifest.json"), JSON.stringify(manifest, null, 2));
+
+  console.error("");
+  console.error(
+    `Done: ${extractedCount}/${results.length} clips extracted from the live catalog, ` +
+      `${manifest.fallbackCount} procedural fallbacks. -> ${OUT_DIR}`
+  );
+}
+
+// ----------------------------------------------------------------------------------------------
+// Loader: register extracted clips into an AnimationClipRegistry, augmenting the procedural set.
+// ----------------------------------------------------------------------------------------------
+
+/**
+ * Deserialize a written clip-library file back into an {@link AnimationClipDefinition} on the
+ * standard rig (track targets are already `<humanoidBone>.rotation|translation`).
+ */
+function deserializeClipFile(file: SerializedClipFile): AnimationClipDefinition<StandardClipId> {
+  return {
+    id: file.id,
+    name: file.name,
+    duration: file.duration,
+    frameRate: file.frameRate,
+    loop: file.loop,
+    tags: file.tags,
+    source: file.source,
+    tracks: file.tracks.map(
+      (tr) =>
+        new AnimationTrack({
+          target: tr.target,
+          valueType: tr.valueType as never,
+          keyframes: tr.keyframes as never
+        })
+    ),
+    metadata: { rig: file.rig, extracted: file.provenance.source === "catalog-extracted" }
+  };
+}
+
+/**
+ * Build the shared, rig-neutral clip registry the studio drives. Starts from the procedural
+ * `standardHumanoidClips` (Phase 2.4) and OVERRIDES each id with the real extracted clip written
+ * under `public/clip-library/` when one exists. If the library hasn't been built yet (no dir),
+ * returns the pure procedural registry. The result speaks exactly the 8 STANDARD_CLIP_IDS and is
+ * authored on STANDARD_LIBRARY_RIG, so it retargets onto any inferred character rig.
+ */
+export function loadExtractedClipLibrary(
+  dir: string = OUT_DIR
+): AnimationClipRegistry<StandardClipId> {
+  const registry = new AnimationClipRegistry<StandardClipId>(createStandardHumanoidClipDefinitions());
+  if (!existsSync(dir)) return registry;
+
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".json") || entry === "manifest.json") continue;
+    let file: SerializedClipFile;
+    try {
+      file = JSON.parse(readFileSync(resolve(dir, entry), "utf8")) as SerializedClipFile;
+    } catch {
+      continue;
+    }
+    // Only override with REAL extracted clips; procedural-fallback files leave the procedural
+    // registry entry in place (identical anyway), so we don't double-register noise.
+    if (file.provenance.source !== "catalog-extracted") continue;
+    if (!STANDARD_CLIP_IDS.includes(file.id)) continue;
+    registry.register(deserializeClipFile(file), { replace: true });
+  }
+  return registry;
+}
+
+/**
+ * Reconcile the already-extracted clips ON DISK (read each <id>.json, run full rest-pose
+ * reconciliation via {@link normalizeExtractedTracks} — hips units/anchor + per-bone median
+ * re-anchoring — rewrite), printing hips translation/rotation AND the per-bone worstFloor
+ * BEFORE→AFTER for each. This is the honest path when the live catalog is flaky/nondeterministic: it
+ * makes the existing extracted clips pass the loader sanity gate (worstFloor < 0.15) without
+ * re-downloading (which might return different assets). Only catalog-extracted files are touched;
+ * procedural-fallback files are already on the standard rig.
+ */
+export function normalizeClipLibraryInPlace(dir: string = OUT_DIR): void {
+  if (!existsSync(dir)) {
+    console.error(`no clip-library at ${dir} — nothing to normalize`);
+    return;
+  }
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".json") || entry === "manifest.json") continue;
+    let file: SerializedClipFile;
+    try {
+      file = JSON.parse(readFileSync(resolve(dir, entry), "utf8")) as SerializedClipFile;
+    } catch {
+      console.error(`  [${entry}] unreadable JSON — skipped`);
+      continue;
+    }
+    if (file.provenance?.source !== "catalog-extracted") {
+      console.error(`  [${entry}] ${file.provenance?.source ?? "unknown"} (not catalog-extracted) — skipped`);
+      continue;
+    }
+    const before = measureHips(file.tracks as never);
+    const beforeFloor = worstRestFloor(file.tracks as never);
+    const tracks = (file.tracks ?? []).map(
+      (tr) =>
+        new AnimationTrack({
+          target: tr.target,
+          valueType: tr.valueType as never,
+          keyframes: tr.keyframes as never
+        })
+    );
+    const normalized = normalizeExtractedTracks(tracks);
+    const serializedTracks = normalized.map((tr) => ({
+      target: tr.target,
+      valueType: tr.valueType,
+      keyframes: [...tr.keyframes]
+    }));
+    const after = measureHips(serializedTracks as never);
+    const afterFloor = worstRestFloor(serializedTracks as never);
+    const rewritten = { ...file, tracks: serializedTracks };
+    writeFileSync(resolve(dir, entry), JSON.stringify(rewritten, null, 2));
+    // The clip is ACCEPTED by the loader sanity gate iff hips are sane AND every bone returns near
+    // rest at some frame (worstFloor < 0.15) — the rest-pose-reconciliation post-condition.
+    const pass =
+      after.maxTranslation <= 1.0 && after.maxRotationOffset <= 0.2 && afterFloor.value < 0.15;
+    console.error(
+      `  [${entry}] hipsTrans ${before.maxTranslation.toFixed(2)} → ${after.maxTranslation.toFixed(2)}  |  ` +
+        `hipsRotOffset ${before.maxRotationOffset.toFixed(3)} → ${after.maxRotationOffset.toFixed(3)}  |  ` +
+        `worstFloor ${beforeFloor.value.toFixed(3)} (${beforeFloor.bone}) → ${afterFloor.value.toFixed(3)} (${afterFloor.bone})  ` +
+        `${pass ? "PASS (gate accepts)" : "STILL FAILING (gated)"}`
+    );
+  }
+}
+
+// CLI entry.
+if (process.argv[1] && process.argv[1].endsWith("build-clip-library.ts")) {
+  if (process.argv.includes("--normalize-in-place")) {
+    console.error("Normalizing existing extracted clips in place (no catalog download):");
+    normalizeClipLibraryInPlace();
+  } else {
+    void build().catch((err) => {
+      console.error(err);
+      process.exitCode = 1;
+    });
+  }
+}