create-aura3d 1.1.2 → 1.3.0

package/templates/animation-studio/scripts/texture-bake.ts

@@ -0,0 +1,297 @@
+/**
+ * texture-bake.ts — dependency-free procedural BITMAP TEXTURE baker for the authored
+ * animation-studio cast (companion to build-characters.ts, Phase M1 character fidelity).
+ *
+ * It paints a single 1024×1024 RGBA base-colour ATLAS per character and encodes it as a
+ * real PNG (node `zlib.deflateSync` — no `sharp`, no native module, so the script stays
+ * runnable standalone exactly like its sibling). The atlas is split into per-material
+ * REGIONS (body / skin / dark / glow / accent); each region carries genuine shading
+ * detail instead of one flat colour:
+ *
+ *   - skin: a vertical tone gradient (lighter forehead → warmer jaw) + soft cheek blush +
+ *     subtle ambient-occlusion vignette at the region edges (crease shading),
+ *   - body (clothing): a woven fabric pattern (fine warp/weft modulation) over the body
+ *     colour with a top-lit vertical shade ramp + edge AO,
+ *   - accent (belt/collar/hair): brushed directional streaks + edge AO,
+ *   - dark (boots/pupils/mouth): near-flat dark with a faint specular sheen band,
+ *   - glow (eyes): a radial hot-centre → rim falloff so eyes read as lit, not flat discs.
+ *
+ * build-characters.ts assigns each material's vertices PLANAR UVs into that material's
+ * region (see assignAtlasUVs there), sets baseColorFactor to white, and references the
+ * PNG as an embedded glTF image + texture + baseColorTexture. The result is a genuine
+ * UV-mapped albedo map — honestly procedural (not scanned/artist-painted), but textured
+ * rather than flat vertex colour.
+ */
+
+import { deflateSync } from "node:zlib";
+
+export type RGBA = [number, number, number, number];
+
+export const ATLAS_SIZE = 1024;
+
+/** A material's rectangular slot in the shared atlas, in normalised [0,1] UV space. */
+export interface AtlasRegion {
+  readonly u0: number;
+  readonly v0: number;
+  readonly u1: number;
+  readonly v1: number;
+}
+
+/**
+ * Atlas layout: five regions on a 1024² sheet. A 4px gutter is left around each cell so
+ * bilinear sampling at the edges never bleeds a neighbouring material in.
+ */
+export const ATLAS_REGIONS = {
+  body: { u0: 0.0, v0: 0.0, u1: 0.5, v1: 0.5 },
+  skin: { u0: 0.5, v0: 0.0, u1: 1.0, v1: 0.5 },
+  accent: { u0: 0.0, v0: 0.5, u1: 0.5, v1: 1.0 },
+  dark: { u0: 0.5, v0: 0.5, u1: 0.75, v1: 1.0 },
+  glow: { u0: 0.75, v0: 0.5, u1: 1.0, v1: 1.0 }
+} as const satisfies Record<string, AtlasRegion>;
+
+export type RegionName = keyof typeof ATLAS_REGIONS;
+
+/** Inputs the painter needs from a CharacterDesign (colours in linear 0..1). */
+export interface BakeColors {
+  readonly bodyColor: RGBA;
+  readonly accentColor: RGBA;
+  readonly skinColor: RGBA;
+  readonly trimColor: RGBA;
+  /** Dark material (boots/pupils/mouth) — fixed, matches the build's dark material. */
+  readonly darkColor: RGBA;
+}
+
+// ---------------------------------------------------------------------------
+// Tiny value-noise (deterministic) for fabric weave + brushed streaks.
+// ---------------------------------------------------------------------------
+function hash2(x: number, y: number): number {
+  const s = Math.sin(x * 127.1 + y * 311.7) * 43758.5453;
+  return s - Math.floor(s);
+}
+
+function clamp01(v: number): number {
+  return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+/**
+ * Edge ambient-occlusion factor inside a region: 1.0 in the middle, darkening toward the
+ * cell borders so creases/seams read. `fx`,`fy` are 0..1 within the region.
+ */
+function edgeAO(fx: number, fy: number): number {
+  const dx = Math.min(fx, 1 - fx);
+  const dy = Math.min(fy, 1 - fy);
+  const d = Math.min(dx, dy);
+  // Full strength shadow within ~6% of the edge, easing to none by ~18%.
+  return clamp01(0.62 + 0.38 * clamp01((d - 0.04) / 0.14));
+}
+
+// ---------------------------------------------------------------------------
+// Per-region painters. Each fills its region of the RGBA buffer (row-major,
+// origin top-left, 4 bytes/pixel). `put` writes one pixel.
+// ---------------------------------------------------------------------------
+type Painter = (fx: number, fy: number, base: RGBA) => RGBA;
+
+/** Clothing fabric: body colour + woven warp/weft + top-lit shade ramp + edge AO. */
+const paintBody: Painter = (fx, fy, base) => {
+  const ao = edgeAO(fx, fy);
+  // Top-lit vertical ramp (brighter near the top of the region → simulates key light).
+  const shade = lerp(1.12, 0.82, fy);
+  // Woven pattern: fine alternating warp (x) and weft (y) threads.
+  const warp = 0.5 + 0.5 * Math.sin(fx * Math.PI * 220);
+  const weft = 0.5 + 0.5 * Math.sin(fy * Math.PI * 220);
+  const weave = 1 + (warp * 0.06 - 0.03) + (weft * 0.06 - 0.03);
+  // A touch of broad cloth folds via low-frequency noise.
+  const fold = 1 + (hash2(Math.floor(fx * 12), Math.floor(fy * 16)) - 0.5) * 0.07;
+  const k = ao * shade * weave * fold;
+  return [clamp01(base[0] * k), clamp01(base[1] * k), clamp01(base[2] * k), 1];
+};
+
+/** Skin: forehead→jaw tone gradient + cheek blush + edge AO (face/limb shading). */
+const paintSkin: Painter = (fx, fy, base) => {
+  const ao = edgeAO(fx, fy);
+  // Vertical tone: a little lighter at the top (forehead), warmer/darker toward the jaw.
+  const tone = lerp(1.08, 0.9, fy);
+  // Cheek blush: two soft warm lobes left/right of centre, mid-height.
+  const blushL = Math.exp(-(((fx - 0.34) ** 2 + (fy - 0.55) ** 2) / 0.01));
+  const blushR = Math.exp(-(((fx - 0.66) ** 2 + (fy - 0.55) ** 2) / 0.01));
+  const blush = (blushL + blushR) * 0.12;
+  const r = base[0] * tone * ao + blush * 0.22;
+  const g = base[1] * tone * ao + blush * 0.05;
+  const b = base[2] * tone * ao + blush * 0.04;
+  return [clamp01(r), clamp01(g), clamp01(b), 1];
+};
+
+/** Accent (belt/collar/hair): brushed directional streaks + edge AO. */
+const paintAccent: Painter = (fx, fy, base) => {
+  const ao = edgeAO(fx, fy);
+  const shade = lerp(1.1, 0.85, fy);
+  // Horizontal brushed streaks: high-frequency noise stretched along x.
+  const streak = 1 + (hash2(Math.floor(fy * 160), Math.floor(fx * 6)) - 0.5) * 0.16;
+  const k = ao * shade * streak;
+  return [clamp01(base[0] * k), clamp01(base[1] * k), clamp01(base[2] * k), 1];
+};
+
+/** Dark (boots/pupils/mouth): near-flat dark with a faint top sheen band. */
+const paintDark: Painter = (fx, fy, base) => {
+  const ao = edgeAO(fx, fy);
+  // Specular sheen near the top quarter (boot/pupil highlight).
+  const sheen = Math.exp(-(((fy - 0.22) ** 2) / 0.006)) * 0.25;
+  const k = ao;
+  return [clamp01(base[0] * k + sheen), clamp01(base[1] * k + sheen), clamp01(base[2] * k + sheen), 1];
+};
+
+/** Glow (eyes): radial hot-centre → rim falloff so the iris reads as lit. */
+const paintGlow: Painter = (fx, fy, base) => {
+  const d = Math.hypot(fx - 0.5, fy - 0.5) / 0.7071;
+  const hot = clamp01(1.0 - d * d); // bright core, soft rim
+  const k = lerp(0.7, 1.25, hot);
+  return [clamp01(base[0] * k), clamp01(base[1] * k), clamp01(base[2] * k), 1];
+};
+
+const PAINTERS: Record<RegionName, Painter> = {
+  body: paintBody,
+  skin: paintSkin,
+  accent: paintAccent,
+  dark: paintDark,
+  glow: paintGlow
+};
+
+function regionBase(name: RegionName, colors: BakeColors): RGBA {
+  switch (name) {
+    case "body":
+      return colors.bodyColor;
+    case "skin":
+      return colors.skinColor;
+    case "accent":
+      return colors.trimColor;
+    case "dark":
+      return colors.darkColor;
+    case "glow":
+      return colors.accentColor;
+  }
+}
+
+/**
+ * Bake the full RGBA atlas (ATLAS_SIZE²) for one character. Returns the raw pixel buffer.
+ * Background (gutters between regions) is a neutral mid grey so any sampling outside a
+ * mapped region is innocuous.
+ */
+export function bakeAtlasPixels(colors: BakeColors): Uint8Array {
+  const N = ATLAS_SIZE;
+  const px = new Uint8Array(N * N * 4);
+  // Neutral background.
+  for (let i = 0; i < px.length; i += 4) {
+    px[i] = 60;
+    px[i + 1] = 60;
+    px[i + 2] = 66;
+    px[i + 3] = 255;
+  }
+  for (const [name, region] of Object.entries(ATLAS_REGIONS) as [RegionName, AtlasRegion][]) {
+    const painter = PAINTERS[name];
+    const base = regionBase(name, colors);
+    const x0 = Math.round(region.u0 * N);
+    const y0 = Math.round(region.v0 * N);
+    const x1 = Math.round(region.u1 * N);
+    const y1 = Math.round(region.v1 * N);
+    const w = x1 - x0;
+    const h = y1 - y0;
+    for (let y = y0; y < y1; y += 1) {
+      const fy = (y - y0) / (h - 1);
+      for (let x = x0; x < x1; x += 1) {
+        const fx = (x - x0) / (w - 1);
+        const c = painter(fx, fy, base);
+        const o = (y * N + x) * 4;
+        px[o] = Math.round(linearToSrgb(c[0]) * 255);
+        px[o + 1] = Math.round(linearToSrgb(c[1]) * 255);
+        px[o + 2] = Math.round(linearToSrgb(c[2]) * 255);
+        px[o + 3] = 255;
+      }
+    }
+  }
+  return px;
+}
+
+// glTF base-colour textures are sampled in sRGB; the design colours are authored as the
+// same factors used for baseColorFactor (which the engine treats as sRGB-ish display
+// colour), so encode straight through (identity) to keep parity with the prior flat look.
+function linearToSrgb(v: number): number {
+  return clamp01(v);
+}
+
+// ---------------------------------------------------------------------------
+// Minimal PNG encoder (RGBA8, no external deps). Produces a standard PNG whose
+// IHDR width/height the resolver's sniffImageDim reads to report textureMaxDim.
+// ---------------------------------------------------------------------------
+const PNG_SIGNATURE = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+function crc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < bytes.length; i += 1) {
+    crc ^= bytes[i]!;
+    for (let b = 0; b < 8; b += 1) {
+      crc = crc & 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type: string, data: Uint8Array): Uint8Array {
+  const typeBytes = new TextEncoder().encode(type);
+  const out = new Uint8Array(12 + data.length);
+  const dv = new DataView(out.buffer);
+  dv.setUint32(0, data.length, false);
+  out.set(typeBytes, 4);
+  out.set(data, 8);
+  const crcInput = new Uint8Array(typeBytes.length + data.length);
+  crcInput.set(typeBytes, 0);
+  crcInput.set(data, typeBytes.length);
+  dv.setUint32(8 + data.length, crc32(crcInput), false);
+  return out;
+}
+
+/** Encode an RGBA8 pixel buffer (row-major, top-left origin) as PNG bytes. */
+export function encodePNG(pixels: Uint8Array, width: number, height: number): Uint8Array {
+  // IHDR.
+  const ihdr = new Uint8Array(13);
+  const dv = new DataView(ihdr.buffer);
+  dv.setUint32(0, width, false);
+  dv.setUint32(4, height, false);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // colour type 6 = RGBA
+  ihdr[10] = 0; // compression
+  ihdr[11] = 0; // filter
+  ihdr[12] = 0; // interlace
+
+  // Raw scanlines with a per-row filter byte (0 = none).
+  const stride = width * 4;
+  const raw = new Uint8Array((stride + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    raw[y * (stride + 1)] = 0;
+    raw.set(pixels.subarray(y * stride, y * stride + stride), y * (stride + 1) + 1);
+  }
+  const idatData = deflateSync(raw, { level: 9 });
+
+  const sig = PNG_SIGNATURE;
+  const ihdrChunk = chunk("IHDR", ihdr);
+  const idatChunk = chunk("IDAT", new Uint8Array(idatData.buffer, idatData.byteOffset, idatData.byteLength));
+  const iendChunk = chunk("IEND", new Uint8Array(0));
+
+  const total = sig.length + ihdrChunk.length + idatChunk.length + iendChunk.length;
+  const png = new Uint8Array(total);
+  let o = 0;
+  png.set(sig, o); o += sig.length;
+  png.set(ihdrChunk, o); o += ihdrChunk.length;
+  png.set(idatChunk, o); o += idatChunk.length;
+  png.set(iendChunk, o);
+  return png;
+}
+
+/** Bake + PNG-encode in one call. */
+export function bakeAtlasPNG(colors: BakeColors): { png: Uint8Array; size: number } {
+  const px = bakeAtlasPixels(colors);
+  return { png: encodePNG(px, ATLAS_SIZE, ATLAS_SIZE), size: ATLAS_SIZE };
+}

package/templates/animation-studio/scripts/verify-extracted-overlay-cli.ts

@@ -0,0 +1,264 @@
+/**
+ * verify-extracted-overlay-cli.ts — HONEST visual proof that the reconciled EXTRACTED clips render
+ * UPRIGHT (M6 / B3).
+ *
+ * Unlike `skeleton-overlay-cli.ts` / `motion-evidence-cli.ts` (which visualize the PROCEDURAL
+ * standard library), this CLI loads the on-disk `public/clip-library/*.json` EXTRACTED clips via
+ * `loadExtractedClipLibrary`, drives the canonical rest skeleton with them through the SAME FK
+ * projection `buildSkeletonStrip` uses (which is equivalent to retargeting onto an identity-rest
+ * standard rig — `Rt = Rt0·Rs0⁻¹·Ra` collapses to applying the clip rotation directly), and:
+ *
+ *   1. writes a first/mid/final skeleton-overlay PNG strip per extracted clip, and
+ *   2. measures UPRIGHTNESS from the projected world bone positions — head above hips above feet,
+ *      head near the top of the figure, feet near the ground — plus per-frame motion.
+ *
+ * It reports, per clip: worstFloor (gate metric), upright?, head/hip/foot heights, motion present.
+ * This is the proof the PRD's M6 acceptance demands: extracted mocap is only usable if it renders
+ * UPRIGHT, not merely if it passes the numeric gate.
+ *
+ * Usage: tsx scripts/verify-extracted-overlay-cli.ts [--out dist/extracted-overlays]
+ */
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+// 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 type { AnimationClipRegistry } from "@aura3d/animation";
+import { buildSkeletonStrip } from "./skeleton-overlay.js";
+import { loadExtractedClipLibrary, worstRestFloor } from "./build-clip-library.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLIP_DIR = resolve(__dirname, "..", "public", "clip-library");
+const INTENTS = ["idle", "talk", "gesture", "point", "nod", "walk", "run", "react"] as const;
+
+// --- sharp loader (same standalone resolution as the sibling CLIs) -------------------------------
+interface SharpModule {
+  (input: Buffer | Uint8Array, options?: { raw: { width: number; height: number; channels: number } }): {
+    png(): { toBuffer(): Promise<Buffer> };
+  };
+}
+function loadSharp(): SharpModule | null {
+  try {
+    return createRequire(import.meta.url)("sharp") as SharpModule;
+  } catch {
+    const roots = [process.cwd(), __dirname];
+    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;
+      }
+    }
+    return null; // PNG is optional evidence; numeric uprightness is the load-bearing proof.
+  }
+}
+async function rawRgbaToPng(pixels: Uint8Array, width: number, height: number): Promise<Uint8Array | null> {
+  const sharp = loadSharp();
+  if (!sharp) return null;
+  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;
+}
+
+// --- FK uprightness measurement (mirrors skeleton-overlay's REST_SKELETON + FK) -------------------
+type Vec3 = readonly [number, number, number];
+type Quat = readonly [number, number, number, number];
+const REST: Readonly<Record<string, { parent: string | null; offset: Vec3 }>> = {
+  hips: { parent: null, offset: [0, 0.95, 0] },
+  spine: { parent: "hips", offset: [0, 0.12, 0] },
+  chest: { parent: "spine", offset: [0, 0.14, 0] },
+  upperChest: { parent: "chest", offset: [0, 0.1, 0] },
+  neck: { parent: "upperChest", offset: [0, 0.08, 0] },
+  head: { parent: "neck", offset: [0, 0.12, 0] },
+  leftShoulder: { parent: "upperChest", offset: [0.06, 0.05, 0] },
+  leftUpperArm: { parent: "leftShoulder", offset: [0.14, 0, 0] },
+  leftLowerArm: { parent: "leftUpperArm", offset: [0.26, 0, 0] },
+  leftHand: { parent: "leftLowerArm", offset: [0.24, 0, 0] },
+  rightShoulder: { parent: "upperChest", offset: [-0.06, 0.05, 0] },
+  rightUpperArm: { parent: "rightShoulder", offset: [-0.14, 0, 0] },
+  rightLowerArm: { parent: "rightUpperArm", offset: [-0.26, 0, 0] },
+  rightHand: { parent: "rightLowerArm", offset: [-0.24, 0, 0] },
+  leftUpperLeg: { parent: "hips", offset: [0.09, -0.04, 0] },
+  leftLowerLeg: { parent: "leftUpperLeg", offset: [0, -0.42, 0] },
+  leftFoot: { parent: "leftLowerLeg", offset: [0, -0.42, 0.04] },
+  rightUpperLeg: { parent: "hips", offset: [-0.09, -0.04, 0] },
+  rightLowerLeg: { parent: "rightUpperLeg", offset: [0, -0.42, 0] },
+  rightFoot: { parent: "rightLowerLeg", offset: [0, -0.42, 0.04] }
+};
+const I: Quat = [0, 0, 0, 1];
+function qMulV(q: Quat, v: Vec3): Vec3 {
+  const [x, y, z, w] = q;
+  const tx = 2 * (y * v[2] - z * v[1]);
+  const ty = 2 * (z * v[0] - x * v[2]);
+  const tz = 2 * (x * v[1] - y * v[0]);
+  return [v[0] + w * tx + (y * tz - z * ty), v[1] + w * ty + (z * tx - x * tz), v[2] + w * tz + (x * ty - y * tx)];
+}
+function qMul(a: Quat, b: Quat): Quat {
+  return [
+    a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+    a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+    a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+    a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2]
+  ];
+}
+interface SampledClip {
+  duration: number;
+  loop: boolean;
+  tracks: readonly { target: string; sample(t: number): readonly number[] }[];
+}
+function solveWorld(clip: SampledClip, t: number): Record<string, Vec3> {
+  const dur = clip.duration > 0 ? clip.duration : 1;
+  const local = clip.loop ? t % dur : Math.min(t, dur);
+  const rot: Record<string, Quat> = {};
+  let hips: Vec3 = [0, 0, 0];
+  for (const tr of clip.tracks) {
+    const d = tr.target.lastIndexOf(".");
+    if (d < 0) continue;
+    const bone = tr.target.slice(0, d);
+    const path = tr.target.slice(d + 1);
+    const v = tr.sample(local);
+    if (path === "rotation" && v.length >= 4) rot[bone] = [v[0]!, v[1]!, v[2]!, v[3]!];
+    else if (path === "translation" && bone === "hips" && v.length >= 3) hips = [v[0]!, v[1]!, v[2]!];
+  }
+  const wp: Record<string, Vec3> = {};
+  const wr: Record<string, Quat> = {};
+  for (const [bone, r] of Object.entries(REST)) {
+    const lr = rot[bone] ?? I;
+    if (r.parent === null) {
+      wr[bone] = lr;
+      wp[bone] = [r.offset[0] + hips[0], r.offset[1] + hips[1], r.offset[2] + hips[2]];
+    } else {
+      const pr = wr[r.parent] ?? I;
+      const pp = wp[r.parent] ?? [0, 0, 0];
+      const ro = qMulV(pr, r.offset);
+      wp[bone] = [pp[0] + ro[0], pp[1] + ro[1], pp[2] + ro[2]];
+      wr[bone] = qMul(pr, lr);
+    }
+  }
+  return wp;
+}
+
+interface UprightReport {
+  upright: boolean;
+  minHeadY: number;
+  maxFootY: number;
+  headAboveHipsPct: number;
+  hipsAboveFeetPct: number;
+  headTravel: number;
+}
+function measureUpright(clip: SampledClip): UprightReport {
+  const dur = clip.duration > 0 ? clip.duration : 1;
+  const N = 24;
+  let minHeadY = Infinity;
+  let maxFootY = -Infinity;
+  let headAbove = 0;
+  let hipsAbove = 0;
+  let samples = 0;
+  let headTravel = 0;
+  const head0 = solveWorld(clip, 0).head!;
+  for (let i = 0; i <= N; i += 1) {
+    const w = solveWorld(clip, (dur * i) / N);
+    const head = w.head!;
+    const hips = w.hips!;
+    const footY = Math.min(w.leftFoot?.[1] ?? 99, w.rightFoot?.[1] ?? 99);
+    minHeadY = Math.min(minHeadY, head[1]);
+    maxFootY = Math.max(maxFootY, footY);
+    headTravel = Math.max(headTravel, Math.hypot(head[0] - head0[0], head[1] - head0[1], head[2] - head0[2]));
+    if (head[1] > hips[1]) headAbove += 1;
+    if (hips[1] > footY) hipsAbove += 1;
+    samples += 1;
+  }
+  const headAboveHipsPct = headAbove / samples;
+  const hipsAboveFeetPct = hipsAbove / samples;
+  return {
+    upright: headAboveHipsPct > 0.9 && hipsAboveFeetPct > 0.9 && minHeadY > 1.0,
+    minHeadY,
+    maxFootY,
+    headAboveHipsPct,
+    hipsAboveFeetPct,
+    headTravel
+  };
+}
+
+function round(n: number): number {
+  return Math.round(n * 1000) / 1000;
+}
+
+async function main(): Promise<void> {
+  const outRoot = resolve(arg("out", "dist/extracted-overlays"));
+  mkdirSync(outRoot, { recursive: true });
+  const registry = loadExtractedClipLibrary(CLIP_DIR) as unknown as AnimationClipRegistry;
+
+  const rows: Record<string, unknown> = {};
+  let allUpright = true;
+  let allAccepted = true;
+  for (const intent of INTENTS) {
+    const clip = (registry.get?.(intent) ?? registry.require?.(intent)) as SampledClip | undefined;
+    const extracted = Boolean((clip as { metadata?: { extracted?: boolean } } | undefined)?.metadata?.extracted);
+    if (!clip) continue;
+    const upright = measureUpright(clip);
+    const floor = worstRestFloor(
+      clip.tracks.map((tr) => ({
+        target: tr.target,
+        keyframes: (tr as unknown as { keyframes: { value: number[] }[] }).keyframes
+      }))
+    );
+    const accepted = floor.value < 0.15;
+    allUpright &&= upright.upright;
+    if (extracted) allAccepted &&= accepted;
+
+    const strip = buildSkeletonStrip({ intent, registry });
+    const png = await rawRgbaToPng(strip.rgba, strip.width, strip.height);
+    let pngPath: string | null = null;
+    if (png) {
+      pngPath = join(outRoot, `${intent}.png`);
+      writeFileSync(pngPath, png);
+    }
+    rows[intent] = {
+      extracted,
+      worstFloor: round(floor.value),
+      worstFloorBone: floor.bone,
+      gate: accepted ? "ACCEPT" : "REJECT",
+      upright: upright.upright,
+      minHeadY: round(upright.minHeadY),
+      maxFootY: round(upright.maxFootY),
+      headAboveHipsPct: round(upright.headAboveHipsPct),
+      hipsAboveFeetPct: round(upright.hipsAboveFeetPct),
+      headTravel: round(upright.headTravel),
+      firstFinalDiff: strip.firstFinalMaxDiff,
+      png: pngPath
+    };
+    // eslint-disable-next-line no-console
+    console.error(
+      `  [${intent.padEnd(8)}] ${extracted ? "EXTRACTED" : "procedural"}  worstFloor=${round(floor.value)
+        .toString()
+        .padEnd(5)} ${accepted ? "ACCEPT" : "REJECT"}  ${upright.upright ? "UPRIGHT" : "CONTORTED"}  ` +
+        `head>=${round(upright.minHeadY)}m foot<=${round(upright.maxFootY)}m travel=${round(upright.headTravel)}m`
+    );
+  }
+
+  writeFileSync(
+    join(outRoot, "summary.json"),
+    JSON.stringify({ generated: "M6 reconciled-extracted-clip uprightness proof", allUpright, allAccepted, clips: rows }, null, 2)
+  );
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify({ ok: true, outRoot, allUpright, allAccepted, clips: rows }));
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(JSON.stringify({ ok: false, error: (err as Error).message, stack: (err as Error).stack }));
+  process.exitCode = 1;
+});

package/templates/animation-studio/src/animation-episode-validator.ts

@@ -0,0 +1,97 @@
+/**
+ * animation-episode-validator.ts — the scene-coherence gate.
+ *
+ * Proves a generated/edited EpisodeDocument is VALID + COHERENT before it is rendered or
+ * shipped: characters + props stay on the walkable set, cameras frame near the action,
+ * every scheduled clip exists on the asset, every shot is covered, plus the structural
+ * checks from `validateEpisodeDocumentShape`.
+ *
+ * HONEST CAVEAT (design doc): this proves a scene is *valid/coherent*, NOT that it is
+ * *well-directed or watchable*. "Good" needs the human-review rubric — automation can
+ * only keep a scene from being broken, not make it good.
+ */
+
+import { validateEpisodeDocumentShape, type EpisodeDocument, type Vec3 } from "./episode-document";
+
+export interface EpisodeDocumentValidation {
+  readonly ok: boolean;
+  readonly errors: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+export interface ValidateOptions {
+  /** GLB clip lists per character, so scheduled clips can be checked to exist. */
+  readonly availableClipsByCharacter?: Record<string, readonly string[]>;
+}
+
+export function validateEpisodeDocument(doc: EpisodeDocument, opts: ValidateOptions = {}): EpisodeDocumentValidation {
+  const shape = validateEpisodeDocumentShape(doc);
+  const errors: string[] = [...shape.errors];
+  const warnings: string[] = [];
+
+  // 0. An empty cast is a valid skeleton (fresh prompt-built scene) — warn so the agent knows
+  //    to resolve real characters with `animation-scene cast add`, but don't break the scene.
+  if (doc.assets.characters.length === 0) {
+    warnings.push("no characters yet — add real cast with `animation-scene cast add --id <id> --query \"<look>\"`");
+  }
+
+  const bounds = doc.walkableBounds;
+  const margin = 0.6;
+  const inBounds = (p: Vec3): boolean =>
+    !bounds ||
+    (p[0] >= bounds.min[0] - margin &&
+      p[0] <= bounds.max[0] + margin &&
+      p[2] >= bounds.min[2] - margin &&
+      p[2] <= bounds.max[2] + margin);
+
+  // 1. Blocking stays on the walkable set (hard error — a character off the set is broken).
+  for (const b of doc.blocking) {
+    for (const s of b.shots) {
+      for (const w of s.waypoints) {
+        if (!inBounds(w.position)) {
+          errors.push(`${b.characterId} blocking in ${s.shotId} leaves the walkable set at [${w.position.map((n) => n.toFixed(2)).join(",")}]`);
+        }
+      }
+    }
+  }
+
+  // 2. Props on the walkable set (warning — off-set props are ugly, not fatal).
+  for (const d of doc.setDressing) {
+    if (!inBounds(d.position)) warnings.push(`prop ${d.propId} placed off the walkable set`);
+  }
+
+  // 3. Camera frames near the action.
+  for (const shot of doc.shots) {
+    if (!inBounds([shot.cameraSubject[0], 0, shot.cameraSubject[2]])) {
+      warnings.push(`shot ${shot.shotId} camera subject is far from the walkable set`);
+    }
+  }
+
+  // 4. Every scheduled clip exists on the asset (fuzzy match; warn + note fallback).
+  if (opts.availableClipsByCharacter) {
+    for (const b of doc.blocking) {
+      const clips = opts.availableClipsByCharacter[b.characterId];
+      if (!clips || clips.length === 0) continue;
+      for (const s of b.shots) {
+        const want = s.clip.toLowerCase();
+        const has = clips.some((c) => {
+          const lc = c.toLowerCase();
+          return lc === want || lc.includes(want) || want.includes(lc);
+        });
+        if (!has) warnings.push(`${b.characterId} clip "${s.clip}" in ${s.shotId} not found; falls back to "${clips[0]}"`);
+      }
+    }
+  }
+
+  // 5. Every character has blocking for every shot.
+  for (const c of doc.assets.characters) {
+    const cb = doc.blocking.find((b) => b.characterId === c.id);
+    for (const shot of doc.shots) {
+      if (!cb?.shots.find((s) => s.shotId === shot.shotId)) {
+        warnings.push(`${c.id} has no blocking for ${shot.shotId} (will hold a fallback mark)`);
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}