create-aura3d 1.1.2 → 1.3.0

package/templates/animation-studio/scripts/asset-motion-probe.ts

@@ -0,0 +1,450 @@
+/**
+ * asset-motion-probe.ts — the "do the embedded clips actually MOVE anything?" gate.
+ *
+ * Clip COUNT lies as badly as texture metadata: a catalog character can advertise five
+ * animations that are all a 2cm idle sway, a jaw-only lip-flap, or a root-bone slide with a
+ * frozen body. Those are useless for acting. This probe reads each embedded GLB animation's
+ * sampler data straight off the BIN chunk (no synthesis), measures the real motion AMPLITUDE
+ * per channel, works out WHICH humanoid bones each clip drives, scores the clip, and maps the
+ * useful ones onto the standard performance vocabulary (idle/talk/gesture/point/nod/walk/run/
+ * react). It then decides whether the character carries a "minimum viable acting pack" or must
+ * fall back to the shared retargeted clip library.
+ *
+ * Honest by construction: a clip that only animates root + mouth + a tiny idle is REJECTED, and
+ * a name-agnostic vocabulary mapping (no keyword in the clip name) is recorded as low confidence.
+ */
+
+import {
+  HUMANOID_BONES,
+  STANDARD_CLIP_IDS,
+  inferHumanoidRigDetailed,
+  type HumanoidBoneName,
+  type StandardClipId
+} from "@aura3d/animation";
+
+// ----------------------------------------------------------------------------------------------
+// GLB parsing — JSON chunk + BIN chunk, enough to read animation sampler accessors.
+// (Self-contained: this probe must run on a raw downloaded Buffer before the GLB is even saved.)
+// ----------------------------------------------------------------------------------------------
+
+interface GltfAccessor { bufferView?: number; byteOffset?: number; componentType: number; count: number; type: string }
+interface GltfBufferView { buffer: number; byteOffset?: number; byteLength: number; byteStride?: number }
+interface GltfChannel { sampler: number; target: { node?: number; path: string } }
+interface GltfSampler { input: number; output: number; interpolation?: "LINEAR" | "STEP" | "CUBICSPLINE" }
+interface GltfAnimation { name?: string; channels: GltfChannel[]; samplers: GltfSampler[] }
+interface GltfJson {
+  accessors?: GltfAccessor[];
+  bufferViews?: GltfBufferView[];
+  nodes?: { name?: string; mesh?: number }[];
+  skins?: { joints?: number[] }[];
+  meshes?: { primitives?: { targets?: unknown[] }[] }[];
+  animations?: GltfAnimation[];
+}
+interface ParsedGlb { readonly json: GltfJson; readonly bin: Buffer }
+
+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;
+  let json: GltfJson;
+  try { json = JSON.parse(buf.slice(jsonStart, jsonStart + jsonLen).toString("utf8")) as GltfJson; }
+  catch { return null; }
+  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 a FLOAT accessor as tuples (one per element). Non-float / truncated → honest empty. */
+function readAccessor(glb: ParsedGlb, index: number): number[][] {
+  const acc = glb.json.accessors?.[index];
+  if (!acc || acc.bufferView === undefined || acc.componentType !== 5126) return [];
+  const view = glb.json.bufferViews?.[acc.bufferView];
+  if (!view) return [];
+  const comps = TYPE_COMPONENTS[acc.type] ?? 1;
+  const elemBytes = comps * (COMPONENT_BYTES[acc.componentType] ?? 4);
+  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 * 4;
+      if (off + 4 > glb.bin.length) return out; // truncated — stop honestly
+      tuple.push(glb.bin.readFloatLE(off));
+    }
+    out.push(tuple);
+  }
+  return out;
+}
+
+// ----------------------------------------------------------------------------------------------
+// Amplitude measurement.
+// ----------------------------------------------------------------------------------------------
+
+/** Angle (radians) between two unit quaternions [x,y,z,w]. Clamped + finite-safe. */
+function quatAngle(a: number[], b: number[]): number {
+  const dot = Math.min(1, Math.abs(a[0]! * b[0]! + a[1]! * b[1]! + a[2]! * b[2]! + a[3]! * b[3]!));
+  if (!Number.isFinite(dot)) return 0;
+  return 2 * Math.acos(dot);
+}
+
+/** Max pairwise angular spread (radians) across a list of quaternion keyframes. */
+function rotationAmplitude(keys: number[][]): number {
+  if (keys.length < 2) return 0;
+  // Spread from the first key is a faithful, cheap proxy for the clip's rotational range.
+  let max = 0;
+  const ref = keys[0]!;
+  for (let i = 1; i < keys.length; i += 1) max = Math.max(max, quatAngle(ref, keys[i]!));
+  // Also check spread from the mid key (catches clips that swing symmetrically around rest).
+  const mid = keys[Math.floor(keys.length / 2)]!;
+  for (let i = 0; i < keys.length; i += 1) max = Math.max(max, quatAngle(mid, keys[i]!));
+  return max;
+}
+
+/** Max per-axis translation span across vector3 keyframes (world/local units). */
+function translationAmplitude(keys: number[][]): number {
+  if (keys.length < 2) return 0;
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (const k of keys) for (let a = 0; a < 3; a += 1) { min[a] = Math.min(min[a]!, k[a]!); max[a] = Math.max(max[a]!, k[a]!); }
+  return Math.max(max[0]! - min[0]!, max[1]! - min[1]!, max[2]! - min[2]!);
+}
+
+// ----------------------------------------------------------------------------------------------
+// Node classification: which humanoid bone (if any) does a node drive; is it root/mouth?
+// ----------------------------------------------------------------------------------------------
+
+const MOUTH_FACE_HINTS = ["mouth", "jaw", "teeth", "tongue", "lip", "face", "eye", "brow", "blink", "cheek"];
+const ROOT_HINTS = ["root", "armature", "scene", "rootnode", "rignode"];
+
+interface NodeRoles {
+  /** nodeIndex → humanoid bone it maps to (via inference), if any. */
+  readonly boneOf: Map<number, HumanoidBoneName>;
+  /** nodeIndex → true when the node name reads as a mouth/face/jaw bone. */
+  readonly mouthOf: Set<number>;
+  /** nodeIndex → true when the node name reads as a pure root/armature carrier. */
+  readonly rootOf: Set<number>;
+  /** Count of mapped REQUIRED humanoid bones present in the rig. */
+  readonly mappedRequired: number;
+  /** Total mapped humanoid bones present in the rig. */
+  readonly mappedTotal: number;
+}
+
+function classifyNodes(glb: ParsedGlb): NodeRoles {
+  const nodes = glb.json.nodes ?? [];
+  const jointIdx = glb.json.skins?.[0]?.joints ?? nodes.map((_, i) => i);
+  const named = 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(named.map((j) => j.name), { id: "probe-source", name: "Probe source rig" });
+  const nameToNode = new Map<string, number>();
+  for (const j of named) nameToNode.set(j.name, j.ni);
+
+  const boneOf = 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) boneOf.set(ni, bone);
+  }
+
+  const mouthOf = new Set<number>();
+  const rootOf = new Set<number>();
+  for (let ni = 0; ni < nodes.length; ni += 1) {
+    if (boneOf.has(ni)) continue; // a real body bone is never reclassified as mouth/root
+    const name = String(nodes[ni]?.name ?? "").toLowerCase();
+    if (!name) continue;
+    if (MOUTH_FACE_HINTS.some((h) => name.includes(h))) mouthOf.add(ni);
+    else if (ROOT_HINTS.some((h) => name.includes(h))) rootOf.add(ni);
+  }
+
+  return {
+    boneOf,
+    mouthOf,
+    rootOf,
+    mappedRequired: HUMANOID_BONES.length - inference.missingRequired.length,
+    mappedTotal: boneOf.size
+  };
+}
+
+// ----------------------------------------------------------------------------------------------
+// Per-clip scoring + vocabulary mapping.
+// ----------------------------------------------------------------------------------------------
+
+/** Bones that count as "body acting" (NOT root/hips-translation, NOT mouth/face). */
+const BODY_ACTING_BONES = new Set<HumanoidBoneName>(
+  HUMANOID_BONES.filter((b) => b !== "hips")
+);
+const ARM_BONES = new Set<HumanoidBoneName>([
+  "leftShoulder", "leftUpperArm", "leftLowerArm", "leftHand",
+  "rightShoulder", "rightUpperArm", "rightLowerArm", "rightHand"
+]);
+const LEG_BONES = new Set<HumanoidBoneName>([
+  "leftUpperLeg", "leftLowerLeg", "leftFoot",
+  "rightUpperLeg", "rightLowerLeg", "rightFoot"
+]);
+
+/** Minimum rotation (radians, ~5.7°) for a channel to count as "this bone actually moves". */
+const MIN_ROT_AMPLITUDE = 0.1;
+/** Minimum root translation (units) for locomotion to count as real travel, not jitter. */
+const MIN_ROOT_TRAVEL = 0.15;
+
+/** Token-boundary keyword match (so "nod" doesn't match "RootNodeAction"). Mirrors build-clip-library. */
+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)));
+}
+
+const VOCAB_KEYWORDS: Readonly<Record<StandardClipId, readonly string[]>> = {
+  idle: ["idle", "breathing", "stand", "breath"],
+  talk: ["talk", "speak", "speaking", "talking", "dialogue", "conversation"],
+  gesture: ["wave", "waving", "gesture", "greet", "hello", "clap"],
+  point: ["point", "pointing", "aim", "indicate"],
+  nod: ["nod", "nodding", "yes", "agree"],
+  walk: ["walk", "walking", "stride"],
+  run: ["run", "running", "sprint", "jog"],
+  react: ["react", "reaction", "surprised", "flinch", "recoil", "hit", "damage", "dodge"]
+};
+
+export interface ClipMotionScore {
+  /** Embedded clip name (or synthetic animation-N). */
+  readonly name: string;
+  /** Clip duration in seconds. */
+  readonly duration: number;
+  /** 0–100 usefulness: amplitude across real body bones, breadth of bones, locomotion. */
+  readonly score: number;
+  /** Largest body-bone rotation in the clip (radians). */
+  readonly maxBodyRotation: number;
+  /** Largest root/hips travel in the clip (units). */
+  readonly rootTravel: number;
+  /** Count of distinct body bones (excl. hips) the clip rotates beyond MIN_ROT_AMPLITUDE. */
+  readonly movingBodyBones: number;
+  /** Count of arm bones that actually move (gesture/talk signal). */
+  readonly movingArmBones: number;
+  /** Count of leg bones that actually move (locomotion signal). */
+  readonly movingLegBones: number;
+  /** True when the clip moves the mouth/jaw/face beyond MIN_ROT_AMPLITUDE. */
+  readonly movesMouth: boolean;
+  /** True when the clip drives meaningful body motion (passes the amplitude gate). */
+  readonly useful: boolean;
+  /** Reason the clip was rejected (when !useful). */
+  readonly rejectReason?: string;
+  /** Standard vocabulary slot this clip best fills, if any. */
+  readonly mappedIntent?: StandardClipId;
+  /** True when the name (token-matched) confirms the intent; false = inferred from motion only. */
+  readonly intentConfident: boolean;
+}
+
+interface ClipAnalysis {
+  readonly name: string;
+  duration: number;
+  maxBodyRotation: number;
+  rootTravel: number;
+  readonly movingBody: Set<HumanoidBoneName>;
+  movesMouth: boolean;
+  /** Total non-body channels (mouth/root/unmapped) that carry motion. */
+  noiseChannels: number;
+}
+
+/** Analyse one GLB animation: amplitude per channel, bucketed by node role. */
+function analyzeAnimation(glb: ParsedGlb, anim: GltfAnimation, roles: NodeRoles, idx: number): ClipAnalysis {
+  const out: ClipAnalysis = {
+    name: anim.name ?? `animation-${idx}`,
+    duration: 0,
+    maxBodyRotation: 0,
+    rootTravel: 0,
+    movingBody: new Set(),
+    movesMouth: false,
+    noiseChannels: 0
+  };
+  for (const ch of anim.channels) {
+    const node = ch.target.node;
+    if (node === undefined) continue;
+    const path = ch.target.path;
+    if (path !== "rotation" && path !== "translation" && path !== "weights") continue;
+    const sampler = anim.samplers[ch.sampler];
+    if (!sampler) continue;
+    const times = readAccessor(glb, sampler.input);
+    if (times.length) out.duration = Math.max(out.duration, times[times.length - 1]![0]!);
+    const raw = readAccessor(glb, sampler.output);
+    if (raw.length < 2) continue;
+    // CUBICSPLINE packs 3 values per key (in-tan, value, out-tan); sample the middle value.
+    const cubic = sampler.interpolation === "CUBICSPLINE";
+    const comps = path === "rotation" ? 4 : path === "translation" ? 3 : (raw[0]?.length ?? 1);
+    const flat = raw.flat();
+    const keys: number[][] = [];
+    const per = cubic ? comps * 3 : comps;
+    for (let k = 0; k * per + (cubic ? comps : 0) + comps <= flat.length; k += 1) {
+      keys.push(flat.slice(k * per + (cubic ? comps : 0), k * per + (cubic ? comps : 0) + comps));
+    }
+    if (keys.length < 2) continue;
+
+    const bone = roles.boneOf.get(node);
+    if (path === "rotation") {
+      const amp = rotationAmplitude(keys);
+      if (amp < MIN_ROT_AMPLITUDE) continue;
+      if (bone && bone !== "hips") { out.movingBody.add(bone); out.maxBodyRotation = Math.max(out.maxBodyRotation, amp); }
+      else if (roles.mouthOf.has(node)) out.movesMouth = true;
+      else out.noiseChannels += 1; // root/unmapped rotation = idle noise
+    } else if (path === "translation") {
+      const amp = translationAmplitude(keys);
+      // Translation only matters on the root/hips (locomotion); limb translation doesn't retarget.
+      if ((bone === "hips" || roles.rootOf.has(node)) && amp >= MIN_ROOT_TRAVEL) out.rootTravel = Math.max(out.rootTravel, amp);
+      else if (amp >= MIN_ROOT_TRAVEL) out.noiseChannels += 1;
+    } else {
+      // morph weights = mouth/blendshape; treat as mouth motion if it actually changes.
+      const amp = translationAmplitude(keys.map((k) => [k[0] ?? 0, 0, 0]));
+      if (amp > 0.05) out.movesMouth = true;
+    }
+  }
+  return out;
+}
+
+/** Score + classify one analysed clip into the standard vocabulary. */
+function scoreClip(a: ClipAnalysis): ClipMotionScore {
+  const movingBodyBones = a.movingBody.size;
+  const movingArmBones = [...a.movingBody].filter((b) => ARM_BONES.has(b)).length;
+  const movingLegBones = [...a.movingBody].filter((b) => LEG_BONES.has(b)).length;
+  const hasLocomotion = a.rootTravel >= MIN_ROOT_TRAVEL && movingLegBones >= 2;
+
+  // Usefulness gate: a clip that only animates root/mouth/tiny-idle is NOT acting motion.
+  let useful = true;
+  let rejectReason: string | undefined;
+  if (movingBodyBones === 0 && !hasLocomotion) {
+    useful = false;
+    rejectReason = a.movesMouth
+      ? "mouth/face only — no body bones move"
+      : a.noiseChannels > 0
+        ? "root/idle noise only — no body bones move beyond threshold"
+        : "no bone moves beyond amplitude threshold";
+  } else if (movingBodyBones === 1 && a.maxBodyRotation < 0.25 && !hasLocomotion) {
+    useful = false;
+    rejectReason = "tiny single-bone idle — below acting amplitude";
+  }
+
+  // Score (0–100): breadth of body bones + amplitude + locomotion bonus.
+  const score = useful
+    ? Math.min(100, Math.round(
+        movingBodyBones * 8 +
+        Math.min(a.maxBodyRotation, Math.PI) * 12 +
+        movingArmBones * 4 +
+        (hasLocomotion ? 25 : 0)
+      ))
+    : 0;
+
+  // Vocabulary mapping: name keyword wins (confident); else infer from the motion shape.
+  let mappedIntent: StandardClipId | undefined;
+  let intentConfident = false;
+  for (const id of STANDARD_CLIP_IDS) {
+    if (clipNameMatches(a.name, VOCAB_KEYWORDS[id])) { mappedIntent = id; intentConfident = true; break; }
+  }
+  if (!mappedIntent && useful) {
+    if (hasLocomotion) mappedIntent = a.rootTravel > 1.2 ? "run" : "walk";
+    else if (movingArmBones >= 2 && a.maxBodyRotation >= 0.6) mappedIntent = "gesture";
+    else if (movingArmBones >= 1) mappedIntent = "talk";
+    else if (a.movingBody.has("head") && movingBodyBones <= 2) mappedIntent = "nod";
+    else if (a.maxBodyRotation >= 1.0) mappedIntent = "react";
+    else mappedIntent = "idle";
+  }
+
+  return {
+    name: a.name,
+    duration: +a.duration.toFixed(2),
+    score,
+    maxBodyRotation: +a.maxBodyRotation.toFixed(3),
+    rootTravel: +a.rootTravel.toFixed(3),
+    movingBodyBones,
+    movingArmBones,
+    movingLegBones,
+    movesMouth: a.movesMouth,
+    useful,
+    rejectReason,
+    mappedIntent,
+    intentConfident
+  };
+}
+
+// ----------------------------------------------------------------------------------------------
+// Public API.
+// ----------------------------------------------------------------------------------------------
+
+/** The four roles a usable acting character must be able to perform from its OWN clips. */
+export const MINIMUM_ACTING_PACK: readonly StandardClipId[] = ["idle", "talk", "walk", "react"];
+
+export interface MotionProbeReport {
+  /** Per-clip scores, useful first. */
+  readonly clips: readonly ClipMotionScore[];
+  /** Useful clips count (passed the amplitude gate). */
+  readonly usefulClips: number;
+  /** Vocabulary slots the embedded clips cover (deduped). */
+  readonly coveredIntents: readonly StandardClipId[];
+  /** True when the embedded clips alone cover the minimum viable acting pack. */
+  readonly hasViableActingPack: boolean;
+  /** Acting-pack slots NOT covered by embedded clips (filled by the shared library). */
+  readonly missingActingSlots: readonly StandardClipId[];
+  /** True when motion must come from the shared retargeted library, not the GLB. */
+  readonly libraryFallback: boolean;
+  /** True when at least one useful clip drives real body motion (the motionPass gate). */
+  readonly motionPass: boolean;
+  /** Whether the rig animates a mouth/face at all (dialogue capability signal). */
+  readonly hasMouth: boolean;
+  /** Plain-language reason when motionPass is false. */
+  readonly reason: string;
+}
+
+/**
+ * Inspect a downloaded character GLB's embedded clips and produce a motion report.
+ * `requireMouth` (dialogue scenes) makes a missing mouth/face a hard reason in the summary text,
+ * though the caller decides the final accept/reject (it also weighs the rig grade + render probe).
+ */
+export function probeEmbeddedMotion(buf: Buffer): MotionProbeReport {
+  const glb = parseGlb(buf);
+  if (!glb || !glb.json.animations?.length) {
+    return {
+      clips: [], usefulClips: 0, coveredIntents: [], hasViableActingPack: false,
+      missingActingSlots: [...MINIMUM_ACTING_PACK], libraryFallback: true, motionPass: false,
+      hasMouth: false, reason: glb ? "no embedded animations" : "unparseable GLB"
+    };
+  }
+  const roles = classifyNodes(glb);
+  const analyses = glb.json.animations.map((anim, i) => analyzeAnimation(glb, anim, roles, i));
+  const clips = analyses.map(scoreClip).sort((x, y) => y.score - x.score);
+
+  const useful = clips.filter((c) => c.useful);
+  const hasMouth = analyses.some((a) => a.movesMouth);
+  const covered = new Set<StandardClipId>();
+  for (const c of useful) if (c.mappedIntent) covered.add(c.mappedIntent);
+  // talk and gesture are interchangeable for the "talk/gesture" acting-pack slot.
+  const coversTalkOrGesture = covered.has("talk") || covered.has("gesture");
+  const missingActingSlots = MINIMUM_ACTING_PACK.filter((slot) =>
+    slot === "talk" ? !coversTalkOrGesture : !covered.has(slot)
+  );
+  const hasViableActingPack = missingActingSlots.length === 0;
+  const motionPass = useful.length > 0;
+
+  return {
+    clips,
+    usefulClips: useful.length,
+    coveredIntents: [...covered],
+    hasViableActingPack,
+    missingActingSlots,
+    libraryFallback: !hasViableActingPack,
+    motionPass,
+    hasMouth,
+    reason: motionPass
+      ? hasViableActingPack
+        ? "embedded clips cover a viable acting pack"
+        : `embedded clips usable but incomplete (missing ${missingActingSlots.join("/")}) — shared library fallback`
+      : "no embedded clip drives real body motion (root/mouth/tiny-idle only) — shared library fallback"
+  };
+}

package/templates/animation-studio/scripts/asset-render-probe.ts

@@ -0,0 +1,152 @@
+/**
+ * asset-render-probe.ts — the REAL "does it actually render?" gate for cast resolution.
+ *
+ * Metadata lies: a GLB can declare embedded textures yet render as a flat white silhouette
+ * (malformed Sketchfab/FBX exports — alphaMode=BLEND, nested transforms, textures not wired
+ * to baseColor). The only reliable test is to RENDER it and look at the pixels. This probe
+ * loads ONE candidate against a NEUTRAL GREYSCALE background, captures a raw frame, and
+ * measures whether the character body actually carries colour or detail. A robot that comes
+ * out uniform white (low chroma AND low luma variance) is rejected before it can be cast.
+ */
+
+import { chromium } from "@playwright/test";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeFileSync } from "node:fs";
+import { startWarmVite, seekAndReadPixels, rawRgbaToPng } from "./render-core.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_ROOT = resolve(__dirname, "..");
+const MONOREPO_ROOT = resolve(TEMPLATE_ROOT, "../../../..");
+
+const PROBE_W = 384;
+const PROBE_H = 384;
+
+export interface ProbeVerdict {
+  readonly ok: boolean;
+  readonly meanChroma: number;
+  readonly lumaStd: number;
+  readonly bodyFraction: number;
+  readonly reason: string;
+  /**
+   * RENDERED detail grade (A/B/C) from the captured pixels — complements resolve-asset's
+   * metadata mesh grade (poly/texture/material). A character that renders with both real surface
+   * colour AND shading variance reads A; flat-but-coloured reads B; barely-textured reads C.
+   * This is the "material validity" lever measured at the pixel level, where metadata can lie.
+   */
+  readonly detailGrade: "A" | "B" | "C";
+}
+
+/** Grade the RENDERED body detail from measured chroma (surface colour) + luma variance (form). */
+function gradeRenderedDetail(meanChroma: number, lumaStd: number): "A" | "B" | "C" {
+  if (meanChroma > 0.08 && lumaStd > 0.18) return "A"; // rich colour + strong form shading
+  if (meanChroma > 0.03 || lumaStd > 0.22) return "B"; // some colour OR good form
+  return "C";                                          // flat / low-detail body
+}
+
+/** Minimal one-character document on a neutral greyscale stage, close-up on the body. */
+function probeDocument(url: string, clip: string, scale: number, heightUnits: number): unknown {
+  const grey3: [number, number, number] = [0.2, 0.2, 0.21];
+  const white: [number, number, number] = [1, 1, 1];
+  const h = Math.max(0.6, heightUnits * scale);
+  return {
+    id: "probe",
+    duration: 2,
+    assets: { characters: [{ id: "probe", url, scale, defaultClip: clip, mouthMorphIndex: -1 }], props: [] },
+    set: {
+      clearColor: [0.04, 0.04, 0.05, 1],
+      studioLightingScale: 0.5,
+      environment: {
+        color: grey3, intensity: 0.5,
+        proceduralMap: { skyColor: grey3, horizonColor: grey3, groundColor: grey3, specularColor: grey3, intensity: 0.5, specularIntensity: 0.4 }
+      },
+      pieces: [],
+      // NEUTRAL WHITE 3-point rig (mirrors moon-garden's intensities, which light the astronaut
+      // properly). White so the background stays greyscale and the body shows its TRUE colour —
+      // a real textured character lights up; the broken-white one stays flat.
+      lights: [
+        { id: "probe-key", kind: "point", color: white, position: [-2.6, 3.6, 2.6], intensity: 4.4, range: 18 },
+        { id: "probe-fill", kind: "point", color: white, position: [2.4, 2.0, 1.4], intensity: 2.2, range: 13 },
+        { id: "probe-rim", kind: "point", color: white, position: [0.4, 1.8, -2.0], intensity: 2.8, range: 13 }
+      ]
+    },
+    walkableBounds: { min: [-2, 0, -2], max: [2, 0, 2] },
+    shots: [{ shotId: "probe-shot", presetId: "two-shot", startTime: 0, endTime: 2, cameraSubject: [0, h * 0.45, 0] }],
+    blocking: [{ characterId: "probe", shots: [{ shotId: "probe-shot", clip, waypoints: [{ time: 0, position: [0, 0, 0], yaw: 0 }] }] }],
+    setDressing: [],
+    worldState: { glowSpanSeconds: 2 }
+  };
+}
+
+function measureBody(raw: Uint8Array): ProbeVerdict {
+  // Body pixels = clearly brighter than the dark neutral background.
+  let n = 0, chromaSum = 0, lumaSum = 0;
+  const lumas: number[] = [];
+  for (let i = 0; i < raw.length; i += 4) {
+    const r = raw[i]! / 255, g = raw[i + 1]! / 255, b = raw[i + 2]! / 255;
+    const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    if (luma < 0.12) continue;
+    const chroma = Math.max(r, g, b) - Math.min(r, g, b);
+    n += 1; chromaSum += chroma; lumaSum += luma; lumas.push(luma);
+  }
+  const total = raw.length / 4;
+  const bodyFraction = n / total;
+  if (n < total * 0.01) return { ok: false, meanChroma: 0, lumaStd: 0, bodyFraction, reason: "body-not-visible", detailGrade: "C" };
+  const meanChroma = chromaSum / n;
+  const meanLuma = lumaSum / n;
+  let varSum = 0;
+  for (const l of lumas) varSum += (l - meanLuma) * (l - meanLuma);
+  const lumaStd = Math.sqrt(varSum / n);
+  // The reliable signal is CHROMA (real surface colour). A flat untextured body reads ~0
+  // chroma no matter how it is lit; luma variance is fooled by the rig's shading gradients.
+  // A very high luma-variance fallback still admits a genuinely detailed grey/metallic body.
+  const ok = meanChroma > 0.025 || lumaStd > 0.30;
+  return { ok, meanChroma: +meanChroma.toFixed(3), lumaStd: +lumaStd.toFixed(3), bodyFraction: +bodyFraction.toFixed(3), reason: ok ? "renders-textured" : "flat-untextured-body", detailGrade: gradeRenderedDetail(meanChroma, lumaStd) };
+}
+
+/**
+ * A WARM probe harness: one Vite + Chromium, reused to render-test MANY candidates (the
+ * resolver may sift dozens). Start once, probe each, close once — instead of paying the
+ * ~10s browser/Vite startup per candidate.
+ */
+export class ProbeSession {
+  private constructor(private readonly vite: Awaited<ReturnType<typeof startWarmVite>>, private readonly browser: import("@playwright/test").Browser, private readonly routeUrl: string) {}
+
+  static async start(): Promise<ProbeSession> {
+    const vite = await startWarmVite(TEMPLATE_ROOT, MONOREPO_ROOT);
+    const address = vite.httpServer?.address();
+    if (!address || typeof address === "string") { await vite.close(); throw new Error("probe vite failed"); }
+    const browser = await chromium.launch({ args: ["--use-gl=angle", "--use-angle=swiftshader", "--enable-unsafe-swdecoder", "--ignore-gpu-blocklist"] });
+    return new ProbeSession(vite, browser, `http://127.0.0.1:${address.port}/live-route.html`);
+  }
+
+  async probe(url: string, clip: string, scale: number, heightUnits: number): Promise<ProbeVerdict> {
+    const page = await this.browser.newPage({ viewport: { width: PROBE_W + 40, height: PROBE_H + 40 } });
+    try {
+      await page.addInitScript(() => { (window as unknown as { __AURA_LIVE_ROUTE_HEADLESS__: boolean }).__AURA_LIVE_ROUTE_HEADLESS__ = true; });
+      await page.addInitScript((d) => { (window as unknown as { __AURA_EPISODE_DOCUMENT__: unknown }).__AURA_EPISODE_DOCUMENT__ = d; }, probeDocument(url, clip, scale, heightUnits));
+      await page.goto(this.routeUrl, { waitUntil: "load", timeout: 60_000 });
+      await page.waitForFunction(() => {
+        const w = window as unknown as { __AURA_LIVE_ROUTE_READY__?: unknown; __AURA_LIVE_ROUTE_ERROR__?: string };
+        if (w.__AURA_LIVE_ROUTE_ERROR__) throw new Error(`route error: ${w.__AURA_LIVE_ROUTE_ERROR__}`);
+        return Boolean(w.__AURA_LIVE_ROUTE_READY__);
+      }, { timeout: 60_000 });
+      const { raw } = await seekAndReadPixels(page, 0.5, PROBE_W, PROBE_H);
+      if (process.env.AURA_PROBE_DEBUG) writeFileSync(resolve(TEMPLATE_ROOT, `dist/probe-${process.env.AURA_PROBE_DEBUG}.png`), await rawRgbaToPng(raw, PROBE_W, PROBE_H));
+      return measureBody(raw);
+    } catch (err) {
+      return { ok: false, meanChroma: 0, lumaStd: 0, bodyFraction: 0, reason: `probe-error: ${err instanceof Error ? err.message : String(err)}`, detailGrade: "C" };
+    } finally {
+      await page.close();
+    }
+  }
+
+  async close(): Promise<void> { await this.browser.close(); await this.vite.close(); }
+}
+
+/** One-shot convenience wrapper (starts + closes its own session). */
+export async function probeCharacterRender(url: string, clip: string, scale: number, heightUnits: number): Promise<ProbeVerdict> {
+  const session = await ProbeSession.start();
+  try { return await session.probe(url, clip, scale, heightUnits); }
+  finally { await session.close(); }
+}

package/templates/animation-studio/scripts/author-office-scene.ts

@@ -0,0 +1,65 @@
+/**
+ * author-office-scene.ts — demonstrates the INTENDED architecture: the AI harness AUTHORS the
+ * dialogue (a coherent exchange), and the CLI/director stages + renders it. This replaces the
+ * template's generic `synthesizeDialogue` filler ("look at this part" pointing at nothing) with a
+ * real, readable argument. Run: `tsx scripts/author-office-scene.ts` then `episode:render-3d`.
+ */
+import { writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateSceneFromPrompt } from "../src/director/prompt-to-scene.js";
+import { directScene } from "../src/director/director-heuristics.js";
+import { estimateSpeechDuration } from "../src/episode-document.js";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// Base scene gives us the cast (worker-1/worker-2), the OFFICE set, camera shots, assets.
+const base = generateSceneFromPrompt("two office workers arguing about a deadline");
+const doc = base.document as any;
+const [a, b] = base.cast;
+
+// AUTHORED dialogue — a coherent argument about a release deadline. Each line makes sense as a
+// reply to the previous one (no hollow "look at this part"). This is what the AI harness writes.
+const authored: { s: string; t: string }[] = [
+  { s: a, t: "We are not shipping on Friday." },
+  { s: b, t: "Yes we are. The login feature is done." },
+  { s: a, t: "It is not done. The tests are still failing." },
+  { s: b, t: "Those tests are flaky. We can ignore them." },
+  { s: a, t: "We are not ignoring failing tests before a release." },
+  { s: b, t: "Fine. Give me one more day and I will fix them." }
+];
+
+let cursor = 0.4;
+const lines = authored.map((x, i) => {
+  const start = Number(cursor.toFixed(3));
+  const dur = estimateSpeechDuration(x.t);
+  let end = Number((start + dur).toFixed(3));
+  if (end > doc.duration) end = doc.duration;
+  cursor = end + 0.3; // a beat between lines
+  return { lineId: `l${i}`, speakerId: x.s, text: x.t, startTime: start, endTime: end };
+});
+doc.dialogue = { language: "en", lines };
+
+// Re-direct so the acting (who talks / reacts / gestures, and when) matches the AUTHORED dialogue.
+const directed = directScene(doc.id, {
+  duration: doc.duration,
+  characters: [
+    { id: a, entersFrom: "left" },
+    { id: b, entersFrom: "right" }
+  ],
+  shots: doc.shots,
+  dialogue: lines.map((l) => ({ lineId: l.lineId, speakerId: l.speakerId, startTime: l.startTime, endTime: l.endTime, text: l.text })),
+  walkableBounds: doc.walkableBounds,
+  props: [],
+  durationEstimator: estimateSpeechDuration
+}) as any;
+doc.blocking = directed.blocking;
+doc.shots = directed.shots;
+doc.setDressing = directed.setDressing;
+doc.worldState = directed.worldState;
+
+const out = JSON.stringify(doc, null, 2) + "\n";
+writeFileSync(resolve(ROOT, "dist/scene/working.document.json"), out);
+writeFileSync(resolve(ROOT, "dist/episodes/acceptance/office.document.json"), out);
+console.log(`authored office scene → ${lines.length} lines, cast ${base.cast.join(", ")}, set ${base.setTemplateId}`);
+for (const l of lines) console.log(`  [${l.startTime}-${l.endTime}] ${l.speakerId}: "${l.text}"`);