create-aura3d 1.1.2 → 1.3.1

package/templates/animation-studio/scripts/motion-evidence-cli.ts

@@ -0,0 +1,150 @@
+/**
+ * motion-evidence-cli.ts — write the Phase B4/B5 motion-evidence artifacts to disk.
+ *
+ * Produces:
+ *   B4  tests/reports/standard-clips/<intent>.png   (8 strips, one per standard intent)
+ *       tests/reports/standard-clips/summary.json    (per-intent bones/maxRot/firstFinalDiff)
+ *   B5  tests/reports/rig-overlays/<rigName>.png      (5 retargeting-overlay strips)
+ *       tests/reports/rig-overlays/summary.json       (per-rig grade + coverage + refusal flag)
+ *
+ * Standalone (no Playwright/GPU): reuses `buildSkeletonStrip`'s FK projection and `sharp` for PNG
+ * encoding only. Deterministic. Emits a final machine-readable JSON line the test parses.
+ *
+ * Usage:
+ *   tsx scripts/motion-evidence-cli.ts --out tests/reports [--clip gesture]
+ */
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import {
+  buildAllIntentEvidence,
+  buildAllRigEvidence,
+  type IntentEvidence,
+  type RigEvidence
+} from "./motion-evidence.js";
+
+interface SharpModule {
+  (input: Buffer | Uint8Array, options?: { raw: { width: number; height: number; channels: number } }): {
+    png(): { toBuffer(): Promise<Buffer> };
+  };
+}
+function loadSharp(): SharpModule {
+  try {
+    return createRequire(import.meta.url)("sharp") as SharpModule;
+  } catch {
+    const roots = [process.cwd(), dirname(fileURLToPath(import.meta.url))];
+    for (const start of roots) {
+      let dir = start;
+      for (let up = 0; up < 8; up += 1) {
+        const storePkg = resolve(dir, "node_modules/.pnpm/sharp@0.33.5/node_modules/sharp/package.json");
+        if (existsSync(storePkg)) return createRequire(storePkg)("sharp") as SharpModule;
+        const parent = dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+    }
+    throw new Error("Could not load `sharp`. Install it: pnpm add -D sharp");
+  }
+}
+async function rawRgbaToPng(pixels: Uint8Array, width: number, height: number): Promise<Uint8Array> {
+  const sharp = loadSharp();
+  const buffer = await sharp(Buffer.from(pixels.buffer, pixels.byteOffset, pixels.byteLength), {
+    raw: { width, height, channels: 4 }
+  })
+    .png()
+    .toBuffer();
+  return new Uint8Array(buffer);
+}
+
+function arg(name: string, fallback: string): string {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1]! : fallback;
+}
+
+function round(n: number): number {
+  return Math.round(n * 1000) / 1000;
+}
+
+async function main(): Promise<void> {
+  const outRoot = resolve(arg("out", "tests/reports"));
+  const clipIntent = arg("clip", "gesture");
+
+  // --- B4: per-intent strips + summary ----------------------------------------------------------
+  const intentDir = join(outRoot, "standard-clips");
+  mkdirSync(intentDir, { recursive: true });
+  const intents: IntentEvidence[] = buildAllIntentEvidence();
+  const intentSummary: Record<string, unknown> = {};
+  for (const ev of intents) {
+    const png = await rawRgbaToPng(ev.strip.rgba, ev.strip.width, ev.strip.height);
+    const file = join(intentDir, `${ev.intent}.png`);
+    writeFileSync(file, png);
+    intentSummary[ev.intent] = {
+      png: file,
+      bonesTouched: ev.bonesTouched,
+      bonesTouchedCount: ev.bonesTouched.length,
+      maxRotAmplitudeRad: round(ev.maxRotAmplitudeRad),
+      firstFinalDiff: ev.firstFinalDiff,
+      panelJointCounts: ev.panelJointCounts,
+      pngBytes: png.byteLength
+    };
+  }
+  writeFileSync(
+    join(intentDir, "summary.json"),
+    JSON.stringify({ generated: "B4 standard-clip visual regression", intents: intentSummary }, null, 2)
+  );
+
+  // --- B5: per-rig retargeting overlays + summary -----------------------------------------------
+  const rigDir = join(outRoot, "rig-overlays");
+  mkdirSync(rigDir, { recursive: true });
+  const rigs: RigEvidence[] = buildAllRigEvidence(clipIntent);
+  const rigSummary: Record<string, unknown> = {};
+  for (const ev of rigs) {
+    const png = await rawRgbaToPng(ev.strip.rgba, ev.strip.width, ev.strip.height);
+    const file = join(rigDir, `${ev.name}.png`);
+    writeFileSync(file, png);
+    rigSummary[ev.name] = {
+      png: file,
+      convention: ev.convention,
+      grade: ev.grade,
+      mappedBoneCount: ev.mappedBoneCount,
+      retargetCoverage: round(ev.retargetCoverage),
+      retargetedBoneCount: ev.retargetedBones.length,
+      refusesBodyActing: ev.refusesBodyActing,
+      clip: ev.clip,
+      firstFinalDiff: ev.firstFinalDiff,
+      gradeReasons: ev.gradeReasons,
+      pngBytes: png.byteLength
+    };
+  }
+  writeFileSync(
+    join(rigDir, "summary.json"),
+    JSON.stringify({ generated: "B5 5-rig retargeting overlays", clip: clipIntent, rigs: rigSummary }, null, 2)
+  );
+
+  console.log(
+    JSON.stringify({
+      ok: true,
+      outRoot,
+      clip: clipIntent,
+      intents: intents.map((ev) => ({
+        intent: ev.intent,
+        bonesTouched: ev.bonesTouched.length,
+        maxRotAmplitudeRad: round(ev.maxRotAmplitudeRad),
+        firstFinalDiff: ev.firstFinalDiff
+      })),
+      rigs: rigs.map((ev) => ({
+        name: ev.name,
+        grade: ev.grade,
+        mappedBoneCount: ev.mappedBoneCount,
+        refusesBodyActing: ev.refusesBodyActing,
+        firstFinalDiff: ev.firstFinalDiff
+      }))
+    })
+  );
+}
+
+main().catch((err) => {
+  console.error(JSON.stringify({ ok: false, error: (err as Error).message, stack: (err as Error).stack }));
+  process.exitCode = 1;
+});

package/templates/animation-studio/scripts/motion-evidence.ts

@@ -0,0 +1,362 @@
+/**
+ * motion-evidence.ts — Phase B4/B5 motion-evidence artifact generator (GPU-free, deterministic).
+ *
+ * This is the visual-regression + retargeting-overlay producer the PRD's B4/B5 acceptance asks for.
+ * It is intentionally browser-FREE and GPU-FREE: it reuses the FK bone-projection in
+ * `skeleton-overlay.ts` (which drives the canonical rest skeleton with the SHARED standard-library
+ * clip and rasterizes a first/mid/final PNG strip) and adds:
+ *
+ *   B4 — one skeleton-overlay strip PER standard intent (idle/talk/gesture/point/nod/walk/run/react)
+ *        onto the STANDARD reference rig, plus a per-intent motion summary (bones touched, max
+ *        rotation amplitude in rad, first-vs-final pixel diff).
+ *
+ *   B5 — five materially-different synthetic rigs (Mixamo / Blender / UE / sparse 8-bone mascot /
+ *        rich humanoid) inferred from node-name lists, GRADED with `gradeRig`, with the SAME clip
+ *        retargeted onto each. A per-rig skeleton-overlay strip is produced that draws ONLY the bones
+ *        the rig actually maps (so a sparse rig visibly acts with fewer bones), and each rig's grade
+ *        is recorded. A D-grade rig is reported as refusing body-acting.
+ *
+ * Everything here is pure data + raw RGBA; PNG encoding is delegated to the caller (the CLI uses
+ * `sharp`). Deterministic — same inputs, same bytes — so a vitest test can assert the artifacts exist
+ * and that every strip shows real motion.
+ */
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore — resolved at runtime to the freshly-built monorepo dist (has co-located .d.ts).
+import {
+  createStandardHumanoidClipRegistry,
+  STANDARD_LIBRARY_RIG,
+  inferHumanoidRig,
+  gradeRig,
+  createHumanoidRetargetingMap,
+  type AnimationClipRegistry,
+  type HumanoidRigDefinition,
+  type RigGrade
+} from "@aura3d/animation";
+import { buildSkeletonStrip, type SkeletonStripResult } from "./skeleton-overlay.js";
+
+/** The 8 shared standard intents (mirrors STANDARD_CLIP_IDS in packages/animation). */
+export const STANDARD_INTENTS = [
+  "idle",
+  "talk",
+  "gesture",
+  "point",
+  "nod",
+  "walk",
+  "run",
+  "react"
+] as const;
+export type StandardIntent = (typeof STANDARD_INTENTS)[number];
+
+type Quat = readonly [number, number, number, number];
+
+interface SampledTrack {
+  readonly target: string;
+  readonly valueType: string;
+  sample(t: number): readonly number[];
+}
+interface SampledClip {
+  readonly duration: number;
+  readonly loop: boolean;
+  readonly tracks: readonly SampledTrack[];
+}
+
+/** Angular distance (rad) between two unit quaternions. */
+function quatAngle(a: Quat, b: Quat): number {
+  let dot = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+  dot = Math.min(1, Math.max(-1, Math.abs(dot)));
+  return 2 * Math.acos(dot);
+}
+
+/**
+ * Measure a clip's motion semantics directly off its tracks (independent of the projection):
+ *  - bonesTouched: distinct bone names with a rotation OR translation track.
+ *  - maxRotAmplitudeRad: the largest angular deviation any rotation track travels from its t=0 pose,
+ *    sampled densely across the clip duration. A static (offset-only) clip reports ~0 here.
+ */
+export function measureClipMotion(clip: SampledClip): {
+  bonesTouched: string[];
+  maxRotAmplitudeRad: number;
+  rotationTracks: number;
+} {
+  const duration = clip.duration > 0 ? clip.duration : 1;
+  const SAMPLES = 48;
+  const bones = new Set<string>();
+  let maxRot = 0;
+  let rotationTracks = 0;
+  for (const track of clip.tracks) {
+    const dot = track.target.lastIndexOf(".");
+    if (dot < 0) continue;
+    const bone = track.target.slice(0, dot);
+    const path = track.target.slice(dot + 1);
+    bones.add(bone);
+    if (path !== "rotation") continue;
+    rotationTracks += 1;
+    const first = track.sample(0);
+    if (first.length < 4) continue;
+    const q0: Quat = [first[0]!, first[1]!, first[2]!, first[3]!];
+    for (let i = 1; i <= SAMPLES; i += 1) {
+      const t = (duration * i) / SAMPLES;
+      const v = track.sample(clip.loop ? t % duration : Math.min(t, duration));
+      if (v.length < 4) continue;
+      const q: Quat = [v[0]!, v[1]!, v[2]!, v[3]!];
+      const angle = quatAngle(q0, q);
+      if (angle > maxRot) maxRot = angle;
+    }
+  }
+  return { bonesTouched: [...bones].sort(), maxRotAmplitudeRad: maxRot, rotationTracks };
+}
+
+export interface IntentEvidence {
+  readonly intent: StandardIntent;
+  readonly bonesTouched: string[];
+  readonly maxRotAmplitudeRad: number;
+  /** first-vs-final pixel diff from the rendered strip (>0 ⇒ the figure visibly moved). */
+  readonly firstFinalDiff: number;
+  readonly panelJointCounts: readonly number[];
+  readonly strip: SkeletonStripResult;
+}
+
+/** B4 — build the per-intent strip + measured motion for one standard intent. */
+export function buildIntentEvidence(
+  intent: StandardIntent,
+  registry: AnimationClipRegistry
+): IntentEvidence {
+  const clip = (registry.get?.(intent) ?? registry.require?.(intent)) as SampledClip | undefined;
+  if (!clip) throw new Error(`motion-evidence: no standard clip for intent "${intent}".`);
+  const motion = measureClipMotion(clip);
+  const strip = buildSkeletonStrip({ intent, registry });
+  return {
+    intent,
+    bonesTouched: motion.bonesTouched,
+    maxRotAmplitudeRad: motion.maxRotAmplitudeRad,
+    firstFinalDiff: strip.firstFinalMaxDiff,
+    panelJointCounts: strip.panelJointCounts,
+    strip
+  };
+}
+
+/** Build evidence for every standard intent (B4). Shares one registry for determinism + speed. */
+export function buildAllIntentEvidence(): IntentEvidence[] {
+  const registry = createStandardHumanoidClipRegistry();
+  return STANDARD_INTENTS.map((intent) => buildIntentEvidence(intent, registry));
+}
+
+// --------------------------------------------------------------------------------------------------
+// B5 — five materially-different synthetic rigs.
+// --------------------------------------------------------------------------------------------------
+
+export interface SyntheticRigSpec {
+  readonly name: string;
+  /** Convention label for the report. */
+  readonly convention: string;
+  /** Node names a GLB of this convention would expose (drives `inferHumanoidRig`). */
+  readonly nodeNames: readonly string[];
+}
+
+/** Mixamo joints (`mixamorig:` namespace, full humanoid → expect grade A). */
+const MIXAMO_NODES: readonly string[] = [
+  "mixamorig:Hips",
+  "mixamorig:Spine",
+  "mixamorig:Spine1",
+  "mixamorig:Spine2",
+  "mixamorig:Neck",
+  "mixamorig:Head",
+  "mixamorig:LeftShoulder",
+  "mixamorig:LeftArm",
+  "mixamorig:LeftForeArm",
+  "mixamorig:LeftHand",
+  "mixamorig:RightShoulder",
+  "mixamorig:RightArm",
+  "mixamorig:RightForeArm",
+  "mixamorig:RightHand",
+  "mixamorig:LeftUpLeg",
+  "mixamorig:LeftLeg",
+  "mixamorig:LeftFoot",
+  "mixamorig:LeftToeBase",
+  "mixamorig:RightUpLeg",
+  "mixamorig:RightLeg",
+  "mixamorig:RightFoot",
+  "mixamorig:RightToeBase"
+];
+
+/** Blender / Rigify-ish names (full humanoid → expect grade A). */
+const BLENDER_NODES: readonly string[] = [
+  "pelvis",
+  "spine",
+  "chest",
+  "upper_chest",
+  "neck",
+  "head",
+  "shoulder.L",
+  "upper_arm.L",
+  "forearm.L",
+  "hand.L",
+  "shoulder.R",
+  "upper_arm.R",
+  "forearm.R",
+  "hand.R",
+  "thigh.L",
+  "shin.L",
+  "foot.L",
+  "toe.L",
+  "thigh.R",
+  "shin.R",
+  "foot.R",
+  "toe.R"
+];
+
+/** Unreal Engine mannequin names (full humanoid → expect grade A). */
+const UE_NODES: readonly string[] = [
+  "pelvis",
+  "spine_01",
+  "spine_02",
+  "spine_03",
+  "neck_01",
+  "head",
+  "clavicle_l",
+  "upperarm_l",
+  "lowerarm_l",
+  "hand_l",
+  "clavicle_r",
+  "upperarm_r",
+  "lowerarm_r",
+  "hand_r",
+  "thigh_l",
+  "calf_l",
+  "foot_l",
+  "ball_l",
+  "thigh_r",
+  "calf_r",
+  "foot_r",
+  "ball_r"
+];
+
+/** Sparse 8-node mascot: torso + head + stub arms, NO forearms/hands, NO legs → expect grade C. */
+const MASCOT_NODES: readonly string[] = [
+  "root",
+  "spine",
+  "neck",
+  "head",
+  "arm_L",
+  "arm_R",
+  "eye_L",
+  "eye_R"
+];
+
+/** Rich humanoid (descriptive anatomical names, full chains → expect grade A). */
+const RICH_NODES: readonly string[] = [
+  "Hips",
+  "LowerSpine",
+  "Ribcage",
+  "UpperChest",
+  "Neck",
+  "Head",
+  "Left Clavicle",
+  "Left Humerus",
+  "Left Ulna",
+  "Left Wrist",
+  "Right Clavicle",
+  "Right Humerus",
+  "Right Ulna",
+  "Right Wrist",
+  "Left Femur",
+  "Left Shin",
+  "Left Ankle",
+  "Left Ball",
+  "Right Femur",
+  "Right Shin",
+  "Right Ankle",
+  "Right Ball"
+];
+
+/**
+ * Props-only / no usable skeleton (root + decorative nodes, no spine/head/limbs) → expect grade D.
+ * This is the honest "this asset cannot body-act" case; it is reported as refusing body acting.
+ */
+const PROPS_ONLY_NODES: readonly string[] = [
+  "root",
+  "Armature",
+  "Camera",
+  "Light",
+  "GroundPlane",
+  "Cube.001"
+];
+
+export const SYNTHETIC_RIGS: readonly SyntheticRigSpec[] = [
+  { name: "mixamo", convention: "Mixamo (mixamorig:)", nodeNames: MIXAMO_NODES },
+  { name: "blender", convention: "Blender / Rigify (.L/.R)", nodeNames: BLENDER_NODES },
+  { name: "ue", convention: "Unreal Engine mannequin (_l/_r)", nodeNames: UE_NODES },
+  { name: "mascot8", convention: "Sparse 8-node mascot", nodeNames: MASCOT_NODES },
+  { name: "rich", convention: "Rich anatomical humanoid", nodeNames: RICH_NODES },
+  { name: "props-only", convention: "Props-only / no usable skeleton", nodeNames: PROPS_ONLY_NODES }
+];
+
+export interface RigEvidence {
+  readonly name: string;
+  readonly convention: string;
+  readonly grade: RigGrade;
+  readonly gradeReasons: readonly string[];
+  readonly mappedBoneCount: number;
+  /** Canonical bones the standard clip's pose actually retargeted onto this rig. */
+  readonly retargetedBones: string[];
+  readonly retargetCoverage: number;
+  /** Honest: true ⇒ the rig is too sparse to drive body acting (grade D). */
+  readonly refusesBodyActing: boolean;
+  readonly clip: string;
+  readonly firstFinalDiff: number;
+  readonly strip: SkeletonStripResult;
+}
+
+/**
+ * Retarget one standard clip onto a synthetic rig and produce a skeleton-overlay strip restricted to
+ * the bones that rig actually maps. The strip therefore visualizes *this rig's* coverage of the clip:
+ * a full humanoid draws the whole figure, a sparse mascot draws only its torso/head.
+ */
+export function buildRigEvidence(spec: SyntheticRigSpec, clipIntent: string): RigEvidence {
+  const rig: HumanoidRigDefinition = inferHumanoidRig(spec.nodeNames, {
+    id: `synthetic-${spec.name}`,
+    name: spec.convention
+  });
+  const report = gradeRig(rig);
+
+  // Which canonical bones map on this rig — used to mask the projection (and to retarget).
+  const mappedBones = Object.keys(rig.bones).filter((b) => {
+    const binding = (rig.bones as Record<string, { name?: string } | undefined>)[b];
+    return Boolean(binding && typeof binding.name === "string" && binding.name.length > 0);
+  });
+
+  // Build the retargeting map standard-library-rig → this rig and retarget the clip's first pose so
+  // we can report the bones that actually carried motion (coverage), even for D rigs.
+  const map = createHumanoidRetargetingMap(STANDARD_LIBRARY_RIG, rig, { minRequiredCoverage: 0 });
+  const retargetedBones = Object.keys(map.bindings).sort();
+
+  const refusesBodyActing = report.grade === "D";
+
+  // Mask the strip to the rig's mapped bones (a sparse rig draws a sparser figure). For D rigs we
+  // still render whatever (near-empty) skeleton it has — the strip + the refusal message together
+  // are the honest evidence.
+  const strip = buildSkeletonStrip({
+    intent: clipIntent,
+    bonesAllow: mappedBones
+  });
+
+  return {
+    name: spec.name,
+    convention: spec.convention,
+    grade: report.grade,
+    gradeReasons: report.reasons,
+    mappedBoneCount: report.mappedBoneCount,
+    retargetedBones,
+    retargetCoverage: map.requiredCoverage,
+    refusesBodyActing,
+    clip: clipIntent,
+    firstFinalDiff: strip.firstFinalMaxDiff,
+    strip
+  };
+}
+
+/** Build evidence for all five synthetic rigs (B5) against one shared clip. */
+export function buildAllRigEvidence(clipIntent = "gesture"): RigEvidence[] {
+  return SYNTHETIC_RIGS.map((spec) => buildRigEvidence(spec, clipIntent));
+}

package/templates/animation-studio/scripts/preview-server.ts

@@ -0,0 +1,52 @@
+/**
+ * preview-server.ts — a watch-and-preview server for the studio loop: it watches a
+ * document JSON and renders a short PREVIEW RANGE to PNGs on every edit, so the agent/creator
+ * sees changes quickly instead of re-rendering the whole 60s.
+ *
+ * HONEST: this renders the range per change (windowed, fast-ish via the `#1` readback). The
+ * further optimization — keeping the browser/page WARM across edits (no per-render startup) +
+ * parallel pages — is the productionization noted in the design doc.
+ *
+ * Run: AURA_DOCUMENT=<doc.json> AURA_PREVIEW_RANGE=0-6 \
+ *   pnpm exec tsx --tsconfig tsconfig.base.json packages/create-aura3d/templates/animation-studio/scripts/preview-server.ts
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, watch } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(__dirname, "..", "..", "..", "..", "..");
+const DOC = process.env.AURA_DOCUMENT
+  ? resolve(process.env.AURA_DOCUMENT)
+  : resolve(__dirname, "..", "dist", "generated", "studio-edited.document.json");
+const RANGE = process.env.AURA_PREVIEW_RANGE ?? "0-6";
+const OUT = process.env.AURA_OUTPUT_DIR ?? "dist/episodes/studio-preview";
+
+function renderPreview(): void {
+  const t = Date.now();
+  const r = spawnSync(
+    "pnpm",
+    ["exec", "tsx", "--tsconfig", "tsconfig.base.json", "packages/create-aura3d/templates/animation-studio/scripts/render-live.ts"],
+    { cwd: REPO, stdio: "ignore", env: { ...process.env, AURA_DOCUMENT: DOC, AURA_OUTPUT_DIR: OUT, AURA_PREVIEW_RANGE: RANGE } }
+  );
+  console.log(`preview ${r.status === 0 ? "ok" : "FAILED"} (range ${RANGE}) in ${((Date.now() - t) / 1000).toFixed(1)}s → ${OUT}`);
+}
+
+function main(): void {
+  if (!existsSync(DOC)) {
+    console.error(`document not found: ${DOC}\nGenerate one first (studio.ts / generate-scene.ts).`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`preview-server watching ${DOC} (range ${RANGE}) ...`);
+  renderPreview();
+  let pending: NodeJS.Timeout | null = null;
+  watch(DOC, () => {
+    if (pending) clearTimeout(pending);
+    pending = setTimeout(renderPreview, 250); // debounce rapid writes
+  });
+}
+
+main();