create-aura3d 1.1.2 → 1.3.0

package/templates/animation-studio/src/fidelity.ts

@@ -0,0 +1,129 @@
+/**
+ * fidelity.ts — PRD Phase M7: honest quality tiering.
+ *
+ * Surfaces a single, user-facing FIDELITY GRADE (A / B / C) per character and per
+ * scene, derived from the REAL signals the pipeline already records. The grade is
+ * how we keep the product honest: a C scene is "previz", never sold as finished.
+ *
+ * The grade is a deliberate DOWNGRADE-only combination of the inputs the PRD lists:
+ *
+ *   A — a curated/uploaded properly-rigged character (rig grade A) playing real
+ *       (mocap/extracted) motion, rendered with cel-or-PBR shading AND shadows.
+ *   B — a catalog rig that graded OK (rig grade A/B) but is missing one of the
+ *       A ingredients (procedural motion, or shadows off): a watchable catalog take.
+ *   C — a mascot / minimal rig (rig grade C/D) OR an authored placeholder: PREVIZ.
+ *       Never present a C as a finished shot.
+ *
+ * The function is PURE (no IO) so it can run identically in the render-time resolver
+ * report and in the browser UI. Both sides import the SAME grading rules.
+ */
+
+export type FidelityGrade = "A" | "B" | "C";
+
+/** Rig grade as produced by the resolver (`RigGrade`) / `gradeRig` (A best … D unusable). */
+export type FidelityRigGrade = "A" | "B" | "C" | "D";
+
+/** Where a character's geometry/rig came from — drives the mascot/previz floor. */
+export type FidelityProvenance = "curated" | "user-uploaded" | "catalog-resolved" | "authored-fallback";
+
+/** The motion actually played — real extracted/mocap clips vs the procedural baseline. */
+export type FidelityMotionSource = "mocap" | "extracted" | "embedded" | "procedural" | "idle" | "talk" | "fallback" | "unknown";
+
+export interface CharacterFidelityInput {
+  readonly id: string;
+  /** Rig grade from the resolver / `gradeRig`. Absent → treated as the previz floor. */
+  readonly rigGrade?: FidelityRigGrade;
+  readonly provenance: FidelityProvenance;
+  /** Dominant motion source the render actually played for this character. */
+  readonly motionSource?: FidelityMotionSource;
+  /** Shading mode the scene rendered with (cel/pbr both count; "none" does not). */
+  readonly shading?: "cel" | "pbr" | "none";
+  /** Whether real shadow maps were enabled (grounding + depth). */
+  readonly shadows?: boolean;
+}
+
+export interface CharacterFidelity {
+  readonly id: string;
+  readonly grade: FidelityGrade;
+  /** True for grade C — the UI must label this output "previz". */
+  readonly previz: boolean;
+  /** Short human reason the grade landed where it did (shown in the report + UI tooltip). */
+  readonly reason: string;
+}
+
+export interface SceneFidelity {
+  readonly grade: FidelityGrade;
+  readonly previz: boolean;
+  readonly characters: readonly CharacterFidelity[];
+  readonly reason: string;
+}
+
+const MASCOT_PROVENANCE = new Set<FidelityProvenance>(["authored-fallback"]);
+const REAL_MOTION = new Set<FidelityMotionSource>(["mocap", "extracted", "embedded"]);
+const CURATED_PROVENANCE = new Set<FidelityProvenance>(["curated", "user-uploaded"]);
+
+/** Grade ONE character. Pure; downgrade-only from the A ingredients. */
+export function gradeCharacterFidelity(input: CharacterFidelityInput): CharacterFidelity {
+  const rig = input.rigGrade ?? "D";
+  const provenance = input.provenance;
+  const motion = input.motionSource ?? "unknown";
+  const shading = input.shading ?? "none";
+  const shadows = input.shadows ?? false;
+
+  // PREVIZ FLOOR (C): a mascot/authored placeholder, or a rig too sparse to act (C/D),
+  // is previz regardless of the other ingredients — its body acting is unreliable.
+  if (MASCOT_PROVENANCE.has(provenance) || rig === "C" || rig === "D") {
+    const why =
+      MASCOT_PROVENANCE.has(provenance)
+        ? "authored placeholder / mascot rig"
+        : `sparse rig (grade ${rig}) — crude retarget only`;
+    return { id: input.id, grade: "C", previz: true, reason: `previz: ${why}` };
+  }
+
+  // A: curated/uploaded rig (grade A) + real motion + shading + shadows — the full stack.
+  const realMotion = REAL_MOTION.has(motion);
+  const shaded = shading === "cel" || shading === "pbr";
+  if (CURATED_PROVENANCE.has(provenance) && rig === "A" && realMotion && shaded && shadows) {
+    return {
+      id: input.id,
+      grade: "A",
+      previz: false,
+      reason: "curated/uploaded grade-A rig with real motion, shading and shadows"
+    };
+  }
+
+  // B: a catalog (or curated) rig that graded OK (A/B) but is missing one A ingredient
+  // (procedural motion, shadows off, or unshaded) — a watchable catalog take, not previz.
+  const missing: string[] = [];
+  if (!realMotion) missing.push("procedural motion");
+  if (!shaded) missing.push("no cel/PBR shading");
+  if (!shadows) missing.push("shadows off");
+  if (!CURATED_PROVENANCE.has(provenance)) missing.push("catalog rig");
+  return {
+    id: input.id,
+    grade: "B",
+    previz: false,
+    reason: missing.length ? `catalog-grade: ${missing.join(", ")}` : "graded-ok rig"
+  };
+}
+
+/** Grade a whole SCENE: the floor of its characters (worst grade wins; empty scene → C/previz). */
+export function gradeSceneFidelity(characters: readonly CharacterFidelityInput[]): SceneFidelity {
+  const graded = characters.map(gradeCharacterFidelity);
+  if (graded.length === 0) {
+    return { grade: "C", previz: true, characters: graded, reason: "previz: no characters in the scene" };
+  }
+  const order: Record<FidelityGrade, number> = { A: 3, B: 2, C: 1 };
+  let worst: FidelityGrade = "A";
+  for (const g of graded) if (order[g.grade] < order[worst]) worst = g.grade;
+  const previz = worst === "C";
+  const reason = previz
+    ? `previz: lowest character grade is C (${graded.filter((g) => g.grade === "C").map((g) => g.id).join(", ")})`
+    : `scene grade ${worst} (floor of ${graded.length} character grade(s))`;
+  return { grade: worst, previz, characters: graded, reason };
+}
+
+/** Human one-word tier label for a grade (used by report + UI badge). */
+export function fidelityLabel(grade: FidelityGrade): string {
+  return grade === "C" ? "Previz" : `Grade ${grade}`;
+}

package/templates/animation-studio/src/graph.ts

@@ -0,0 +1,14 @@
+// Runtime locomotion composition for the preview route. Uses the public @aura3d/animation
+// locomotion kit (BlendTree1D + locomotion state graph) built from the typed character.
+import { createLocomotionKit, type LocomotionKit } from "@aura3d/animation";
+import { heroCharacter, type AnimationStudioCharacter } from "./character.js";
+
+export function buildLocomotionKit(character: AnimationStudioCharacter = heroCharacter): LocomotionKit {
+  return createLocomotionKit({
+    idleClip: character.clipMap.idle,
+    walkClip: character.clipMap.walk,
+    runClip: character.clipMap.run,
+    walkSpeed: character.walkSpeed,
+    runSpeed: character.runSpeed
+  });
+}

package/templates/animation-studio/src/procedural-hdri.ts

@@ -0,0 +1,243 @@
+/**
+ * procedural-hdri.ts — bake a per-set equirectangular HDRI and wire it as real IBL (Phase M3).
+ *
+ * M3's remaining optional item was "load an HDRI *bitmap* per set" for image-based lighting in PBR
+ * mode. Rather than ship licensed .hdr files, we GENERATE an equirectangular environment IMAGE
+ * procedurally from each set's `EnvironmentHdriSpec` (a sky→horizon→ground vertical gradient plus an
+ * optional sun disc) and build a real `@aura3d/rendering` `Texture` + `TextureBinding` from it. The
+ * engine's forward pass already samples `environmentMapTexture` as a 2D equirect map for both diffuse
+ * irradiance and specular reflection (`u_environmentMapTexture*` uniforms in ForwardPass), so this is
+ * genuine IBL — not just a richer procedural ambient. The baked map composes ON TOP of the existing
+ * `proceduralMap` ambient: the procedural map remains the floor, the sampled HDRI adds image-based
+ * specular/diffuse detail and a directional sun highlight.
+ *
+ * The bitmap is generated in-memory (1024×512 RGBA8) so there is no asset to ship or fetch; it is
+ * deterministic from the spec. A PNG encoder is included so a set's HDRI can optionally be written to
+ * `public/hdri/<id>.png` for inspection/debug, but the render path uses the in-memory pixels directly.
+ */
+
+// I1 clean-room correctness: import the rendering primitives (Sampler/Texture/TextureBinding) from
+// the engine's OWN rendering subpath — the same copy the A3DRenderer validates against — NOT the
+// standalone `@aura3d/rendering` package. In a clean-room (tarball) install the standalone package is
+// a SECOND copy, so a `TextureBinding` built from it is a different class than the renderer's and is
+// rejected by `MaterialBinding.bind` (`value instanceof TextureBinding`). Going through the engine
+// keeps the baked HDRI's binding the same class as the renderer's, so IBL binds across the install.
+import { Sampler, Texture, TextureBinding } from "@aura3d/engine/rendering";
+import type { EnvironmentHdriSpec, Vec3 } from "./episode-document";
+
+export const HDRI_WIDTH = 1024;
+export const HDRI_HEIGHT = 512;
+
+function clamp01(x: number): number {
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+
+/** Linear interpolate between two RGB triples. */
+function mixRgb(a: Vec3, b: Vec3, t: number): Vec3 {
+  return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+}
+
+/** Convert a linear 0..1+ channel to an 8-bit sRGB-ish byte (gamma 2.2), clamped. */
+function toByte(linear: number): number {
+  const g = Math.pow(clamp01(linear), 1 / 2.2);
+  return Math.round(clamp01(g) * 255);
+}
+
+/**
+ * Bake the equirectangular RGBA8 pixel buffer for a set HDRI. Row 0 is the zenith (sky), the middle
+ * row is the horizon, the bottom row is the nadir (ground bounce). The sun disc, if present, is drawn
+ * into the sky hemisphere as a soft bright spot for a directional specular highlight.
+ */
+export function bakeEquirectHdriPixels(spec: EnvironmentHdriSpec): Uint8Array {
+  const data = new Uint8Array(HDRI_WIDTH * HDRI_HEIGHT * 4);
+  const sun = spec.sun;
+  // Precompute the sun's world direction (unit) so each texel can dot against it.
+  let sunDir: Vec3 | null = null;
+  if (sun) {
+    const ce = Math.cos(sun.elevation);
+    sunDir = [ce * Math.sin(sun.azimuth), Math.sin(sun.elevation), ce * Math.cos(sun.azimuth)];
+  }
+  const cosSunRadius = sun ? Math.cos(sun.angularRadius) : 1;
+
+  for (let y = 0; y < HDRI_HEIGHT; y++) {
+    // v: 0 at top (zenith) → 1 at bottom (nadir). Equirect latitude = (0.5 - v) * π.
+    const v = (y + 0.5) / HDRI_HEIGHT;
+    const lat = (0.5 - v) * Math.PI; // +π/2 zenith, 0 horizon, -π/2 nadir.
+    // Vertical gradient: sky→horizon over the top hemisphere, horizon→ground over the bottom.
+    let base: Vec3;
+    if (lat >= 0) {
+      base = mixRgb(spec.horizonColor, spec.skyColor, clamp01(lat / (Math.PI / 2)));
+    } else {
+      base = mixRgb(spec.horizonColor, spec.groundColor, clamp01(-lat / (Math.PI / 2)));
+    }
+    const sinLat = Math.sin(lat);
+    const cosLat = Math.cos(lat);
+    for (let x = 0; x < HDRI_WIDTH; x++) {
+      // u: 0..1 around the sphere; longitude = (u - 0.5) * 2π.
+      const u = (x + 0.5) / HDRI_WIDTH;
+      const lon = (u - 0.5) * 2 * Math.PI;
+      let r = base[0];
+      let g = base[1];
+      let b = base[2];
+      if (sunDir && lat > -0.05) {
+        // Texel direction on the unit sphere.
+        const dx = cosLat * Math.sin(lon);
+        const dy = sinLat;
+        const dz = cosLat * Math.cos(lon);
+        const dot = dx * sunDir[0] + dy * sunDir[1] + dz * sunDir[2];
+        if (dot > cosSunRadius) {
+          // Inside the disc: full sun. Add a soft glow falloff just outside via smoothstep.
+          const k = sun!.intensity;
+          r += sun!.color[0] * k;
+          g += sun!.color[1] * k;
+          b += sun!.color[2] * k;
+        } else if (dot > cosSunRadius - 0.04) {
+          const t = (dot - (cosSunRadius - 0.04)) / 0.04;
+          const halo = t * t * 0.5 * sun!.intensity;
+          r += sun!.color[0] * halo;
+          g += sun!.color[1] * halo;
+          b += sun!.color[2] * halo;
+        }
+      }
+      const i = (y * HDRI_WIDTH + x) * 4;
+      data[i] = toByte(r);
+      data[i + 1] = toByte(g);
+      data[i + 2] = toByte(b);
+      data[i + 3] = 255;
+    }
+  }
+  return data;
+}
+
+export interface BakedHdri {
+  readonly texture: Texture;
+  readonly binding: TextureBinding;
+  readonly intensity: number;
+  readonly specularIntensity: number;
+  readonly pixels: Uint8Array;
+}
+
+/**
+ * Bake a set's HDRI spec into a real engine IBL: an equirect `Texture` + a `TextureBinding`
+ * (`u_environmentMapTexture`, equirect → repeat U / clamp V like the engine's parity preset). The
+ * returned `intensity`/`specularIntensity` feed the engine's `environmentMapIntensity` /
+ * `environmentMapSpecularIntensity`.
+ */
+export function bakeSetHdri(id: string, spec: EnvironmentHdriSpec): BakedHdri {
+  const pixels = bakeEquirectHdriPixels(spec);
+  const texture = new Texture({
+    width: HDRI_WIDTH,
+    height: HDRI_HEIGHT,
+    colorSpace: "srgb",
+    label: `animation-studio-hdri-${id}`,
+    data: pixels
+  });
+  const binding = new TextureBinding({
+    name: "u_environmentMapTexture",
+    texture,
+    // Equirect: wrap horizontally (longitude is periodic), clamp vertically (poles).
+    sampler: new Sampler({ minFilter: "linear", magFilter: "linear", addressU: "repeat", addressV: "clamp-to-edge" }),
+    expectedColorSpace: "srgb",
+    expectedDimension: "2d",
+    required: true
+  });
+  return {
+    texture,
+    binding,
+    intensity: spec.intensity ?? 1,
+    specularIntensity: spec.specularIntensity ?? 0.4,
+    pixels
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Minimal PNG encoder (debug only) — lets `public/hdri/<id>.png` be written for inspection. The
+// render path does NOT depend on this; it samples the in-memory pixels directly.
+// ---------------------------------------------------------------------------
+
+function crc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) {
+    crc ^= bytes[i]!;
+    for (let k = 0; k < 8; k++) {
+      crc = crc & 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function adler32(bytes: Uint8Array): number {
+  let a = 1;
+  let b = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    a = (a + bytes[i]!) % 65521;
+    b = (b + a) % 65521;
+  }
+  return ((b << 16) | a) >>> 0;
+}
+
+function u32(n: number): Uint8Array {
+  return new Uint8Array([(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]);
+}
+
+function chunk(type: string, payload: Uint8Array): Uint8Array {
+  const typeBytes = new Uint8Array([type.charCodeAt(0), type.charCodeAt(1), type.charCodeAt(2), type.charCodeAt(3)]);
+  const body = new Uint8Array(typeBytes.length + payload.length);
+  body.set(typeBytes, 0);
+  body.set(payload, typeBytes.length);
+  const out = new Uint8Array(4 + body.length + 4);
+  out.set(u32(payload.length), 0);
+  out.set(body, 4);
+  out.set(u32(crc32(body)), 4 + body.length);
+  return out;
+}
+
+/** Encode an RGBA8 buffer to an (uncompressed-deflate) PNG. For debug export only. */
+export function encodePng(width: number, height: number, rgba: Uint8Array): Uint8Array {
+  // Raw scanlines with a 0 (none) filter byte per row.
+  const raw = new Uint8Array(height * (1 + width * 4));
+  for (let y = 0; y < height; y++) {
+    const dst = y * (1 + width * 4);
+    raw[dst] = 0;
+    raw.set(rgba.subarray(y * width * 4, (y + 1) * width * 4), dst + 1);
+  }
+  // zlib stream: 0x78 0x01 header, stored (uncompressed) deflate blocks, adler32 trailer.
+  const blocks: Uint8Array[] = [];
+  const MAX = 0xffff;
+  for (let off = 0; off < raw.length; off += MAX) {
+    const len = Math.min(MAX, raw.length - off);
+    const final = off + len >= raw.length ? 1 : 0;
+    const header = new Uint8Array([final, len & 0xff, (len >>> 8) & 0xff, ~len & 0xff, (~len >>> 8) & 0xff]);
+    blocks.push(header, raw.subarray(off, off + len));
+  }
+  let zlibLen = 2 + 4;
+  for (const blk of blocks) zlibLen += blk.length;
+  const zlib = new Uint8Array(zlibLen);
+  zlib[0] = 0x78;
+  zlib[1] = 0x01;
+  let p = 2;
+  for (const blk of blocks) {
+    zlib.set(blk, p);
+    p += blk.length;
+  }
+  zlib.set(u32(adler32(raw)), p);
+
+  const ihdr = new Uint8Array(13);
+  ihdr.set(u32(width), 0);
+  ihdr.set(u32(height), 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // colour type RGBA
+  // 10,11,12 = compression/filter/interlace = 0.
+
+  const sig = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  const idat = chunk("IDAT", zlib);
+  const ihdrChunk = chunk("IHDR", ihdr);
+  const iend = chunk("IEND", new Uint8Array(0));
+  const out = new Uint8Array(sig.length + ihdrChunk.length + idat.length + iend.length);
+  let q = 0;
+  for (const part of [sig, ihdrChunk, idat, iend]) {
+    out.set(part, q);
+    q += part.length;
+  }
+  return out;
+}

package/templates/animation-studio/src/profile.ts

@@ -0,0 +1,97 @@
+// Pure Animation Studio profile pipeline: builds the exportable animation-profile.json structure
+// and validates character readiness. No engine/browser import — runs in plain Node so
+// `anim:plan/profile/package/verify` work without a renderer.
+
+import {
+  requiredLocomotionActions,
+  type AnimationStudioCharacter,
+  type LocomotionAction
+} from "./character.js";
+
+export interface AnimationStudioReadiness {
+  readonly ok: boolean;
+  readonly characterId: string;
+  readonly requiredActions: readonly LocomotionAction[];
+  readonly missingActions: readonly LocomotionAction[];
+  readonly errors: readonly string[];
+}
+
+export interface AnimationStudioStateGraphDescriptor {
+  readonly states: readonly string[];
+  readonly parameters: readonly string[];
+  readonly transitions: ReadonlyArray<{ readonly from: string; readonly to: string; readonly when: string }>;
+}
+
+export interface AnimationStudioBlendTreeDescriptor {
+  readonly parameter: "speed";
+  readonly children: ReadonlyArray<{ readonly clip: string; readonly threshold: number }>;
+}
+
+export interface AnimationProfile {
+  readonly schema: "aura-animation-profile/v1";
+  readonly characterId: string;
+  readonly characterName: string;
+  readonly assetKey: string;
+  readonly clipMap: Readonly<Record<LocomotionAction, string>>;
+  readonly stateGraph: AnimationStudioStateGraphDescriptor;
+  readonly blendTree: AnimationStudioBlendTreeDescriptor;
+  readonly ikChains: AnimationStudioCharacter["ikChains"];
+  readonly rootMotion: { readonly suppressed: boolean; readonly note: string };
+}
+
+export function validateAnimationStudioCharacter(character: AnimationStudioCharacter): AnimationStudioReadiness {
+  const errors: string[] = [];
+  const missingActions: LocomotionAction[] = [];
+  for (const action of requiredLocomotionActions) {
+    const clip = character.clipMap[action];
+    if (!clip || clip.trim().length === 0) {
+      missingActions.push(action);
+      errors.push(`Required locomotion action "${action}" has no clip mapped.`);
+    }
+  }
+  if (!character.assetKey || character.assetKey.trim().length === 0) {
+    errors.push("Character must reference a typed assetKey, not a raw URL.");
+  }
+  if (!(character.runSpeed > character.walkSpeed)) {
+    errors.push(`runSpeed (${character.runSpeed}) must be greater than walkSpeed (${character.walkSpeed}).`);
+  }
+  return {
+    ok: errors.length === 0,
+    characterId: character.id,
+    requiredActions: requiredLocomotionActions,
+    missingActions,
+    errors
+  };
+}
+
+export function createAnimationProfile(character: AnimationStudioCharacter): AnimationProfile {
+  return {
+    schema: "aura-animation-profile/v1",
+    characterId: character.id,
+    characterName: character.name,
+    assetKey: character.assetKey,
+    clipMap: character.clipMap,
+    stateGraph: {
+      states: ["idle", "walk", "run"],
+      parameters: ["isMoving", "isRunning"],
+      transitions: [
+        { from: "idle", to: "walk", when: "isMoving" },
+        { from: "idle", to: "run", when: "isRunning" },
+        { from: "walk", to: "run", when: "isRunning" },
+        { from: "walk", to: "idle", when: "!isMoving" },
+        { from: "run", to: "walk", when: "!isRunning" },
+        { from: "run", to: "idle", when: "!isMoving" }
+      ]
+    },
+    blendTree: {
+      parameter: "speed",
+      children: [
+        { clip: character.clipMap.idle, threshold: 0 },
+        { clip: character.clipMap.walk, threshold: character.walkSpeed },
+        { clip: character.clipMap.run, threshold: character.runSpeed }
+      ]
+    },
+    ikChains: character.ikChains,
+    rootMotion: { suppressed: true, note: "Locomotion uses controller velocity; in-place clips with root motion suppressed." }
+  };
+}

package/templates/animation-studio/src/render-live-route.ts

@@ -0,0 +1,42 @@
+/**
+ * render-live-route.ts — the live 3D route ENTRY (the generic player).
+ *
+ * This file contains NO scene-specific content. It loads whatever EpisodeDocument is
+ * injected (a Director-GENERATED scene, the working document, or an explicitly chosen
+ * example) and hands it to the GENERIC `scene-player`, which can render ANY document.
+ *
+ * IMPORTANT: there is NO content fixture as the default. When nothing is injected the
+ * route plays a neutral EMPTY placeholder and prints a clear "no scene loaded" message.
+ * The Moon Garden scene is now an EXAMPLE (`src/examples/moon-garden.example.ts`) and is
+ * used ONLY when explicitly requested — never as the default render path.
+ *
+ * This is the bridge for both project goals:
+ * generalization = a Director GENERATES documents; studio = an agent EDITS documents.
+ */
+
+import { mountScenePlayer } from "./scene-player";
+import { emptyDocument, EMPTY_DOCUMENT_NOTICE } from "./empty-document";
+import type { EpisodeDocument } from "./episode-document";
+
+// The capture script / studio injects the scene to render (any document) via this global.
+// If nothing is injected we fall back to the generic EMPTY placeholder — never a fixture.
+const injected = (window as Window & { __AURA_EPISODE_DOCUMENT__?: EpisodeDocument }).__AURA_EPISODE_DOCUMENT__;
+const documentToPlay = injected ?? emptyDocument;
+if (!injected) {
+  // eslint-disable-next-line no-console
+  console.warn(EMPTY_DOCUMENT_NOTICE);
+}
+
+void mountScenePlayer(documentToPlay).catch((error: unknown) => {
+  const diagnostics = (error as { diagnostics?: readonly string[] })?.diagnostics;
+  const baseMessage = error instanceof Error ? error.message : String(error);
+  const message = diagnostics && diagnostics.length > 0 ? `${baseMessage} :: ${diagnostics.join(" | ")}` : baseMessage;
+  const liveWindow = window as Window & { __AURA_LIVE_ROUTE_ERROR__?: string };
+  liveWindow.__AURA_LIVE_ROUTE_ERROR__ = message;
+  const root = document.querySelector<HTMLDivElement>("#app");
+  if (root) {
+    root.innerHTML = `<pre style="color:#f88;background:#0b0f1a;padding:24px;white-space:pre-wrap;">scene-player failed: ${message}</pre>`;
+  }
+  // eslint-disable-next-line no-console
+  console.error("scene-player failed", error);
+});

package/templates/animation-studio/src/render-modes.ts

@@ -0,0 +1,137 @@
+/**
+ * render-modes.ts — PRD Phase I2 (rendering honesty). The SINGLE source of truth for:
+ *
+ *  1. WHICH cel is which. There are TWO distinct "cel" mechanisms and conflating them is the
+ *     dishonesty this module exists to prevent:
+ *       • IN-SHADER CEL  (GPU): the engine's real `AnimationToonMaterial` (banded N·L + Fresnel
+ *         rim), assigned to non-glow SET PIECES at scene-build time in `scene-player.ts`. This is
+ *         a true material shader — it shades geometry on the GPU before any pixels are read back.
+ *       • CPU TOON POST-PASS: `applyToonTreatment` in `scripts/render-core.ts`, run on the
+ *         CAPTURED RGBA pixels after read-back (quantize luma + Sobel ink + grade). This is a
+ *         2D image filter — it never touches geometry or lighting.
+ *     `renderModeNotes()` returns this contract verbatim so the studio/report can show it and the
+ *     two are never described as the same thing.
+ *
+ *  2. The RENDER MODE (toon / wireframe / storyboard) and its verification. These are the three
+ *     user-facing stage views; this module resolves the requested mode from a flag/env and
+ *     verifies a request is one of the supported modes (no silent fallback to a dead mode).
+ *
+ *  3. The GLOBAL BLEND/alpha GHOST FIX. Many catalog GLBs set `alphaMode=BLEND` on an OPAQUE
+ *     (opacity 1) material, so a textured mesh renders as a translucent white "ghost". The fix —
+ *     force such materials opaque (blend off, depth write/test on) — must apply to EVERY render
+ *     item (characters, props, set dressing), not just characters. `forceOpaqueIfGhost` is the one
+ *     policy both `scene-player.ts` and any prop/set path call, so the fix is provably global.
+ */
+
+/** The three user-facing stage render modes (mirrors the UI `ViewMode`). */
+export type RenderMode = "toon" | "wireframe" | "storyboard";
+
+/** Shading style WITHIN the rendered (toon) mode: cel look vs realistic PBR. */
+export type RenderStyle = "toon" | "pbr";
+
+export const RENDER_MODES: readonly RenderMode[] = ["toon", "wireframe", "storyboard"];
+export const RENDER_STYLES: readonly RenderStyle[] = ["toon", "pbr"];
+
+/** True when `mode` is a real, supported render mode (not a dead/legacy flag). */
+export function isRenderMode(mode: string): mode is RenderMode {
+  return (RENDER_MODES as readonly string[]).includes(mode);
+}
+
+/** True when `style` is a real, supported render style. */
+export function isRenderStyle(style: string): style is RenderStyle {
+  return (RENDER_STYLES as readonly string[]).includes(style);
+}
+
+export interface ResolvedRenderMode {
+  readonly mode: RenderMode;
+  readonly style: RenderStyle;
+  /** True when the cel image post-pass + in-shader cel apply (only in `toon` mode + `toon` style). */
+  readonly celApplies: boolean;
+}
+
+/**
+ * Resolve the effective render mode + style from explicit values, else env, else the defaults
+ * (`toon` mode, `toon`/cel style). VERIFIES the request: an unknown mode/style THROWS rather than
+ * silently falling back, so a typo can never quietly render the wrong view (PRD: "render-mode
+ * verification; no dead flags").
+ */
+export function resolveRenderMode(opts: {
+  readonly mode?: string;
+  readonly style?: string;
+  readonly env?: Record<string, string | undefined>;
+} = {}): ResolvedRenderMode {
+  const env = opts.env ?? (typeof process !== "undefined" ? process.env : {});
+  const rawMode = (opts.mode ?? env.AURA_RENDER_MODE ?? "toon").trim().toLowerCase();
+  const rawStyle = (opts.style ?? env.AURA_RENDER_STYLE ?? "toon").trim().toLowerCase();
+  if (!isRenderMode(rawMode)) {
+    throw new Error(
+      `Unknown AURA_RENDER_MODE "${rawMode}". Supported: ${RENDER_MODES.join(", ")} (no dead/legacy modes).`
+    );
+  }
+  if (!isRenderStyle(rawStyle)) {
+    throw new Error(
+      `Unknown AURA_RENDER_STYLE "${rawStyle}". Supported: ${RENDER_STYLES.join(", ")}.`
+    );
+  }
+  // Cel (both the in-shader material and the CPU post-pass) only applies in the rendered TOON mode
+  // with the TOON style. Wireframe/storyboard are line/flat views; PBR style is realistic.
+  const celApplies = rawMode === "toon" && rawStyle === "toon";
+  return { mode: rawMode, style: rawStyle, celApplies };
+}
+
+/** The honest cel-vs-post-pass contract, returned verbatim for the resolver report / UI. */
+export function renderModeNotes(): {
+  readonly inShaderCel: string;
+  readonly cpuToonPostPass: string;
+  readonly modes: readonly RenderMode[];
+  readonly styles: readonly RenderStyle[];
+} {
+  return {
+    inShaderCel:
+      "GPU material (AnimationToonMaterial): banded N·L + Fresnel rim, assigned to non-glow set pieces in scene-player.ts. Shades geometry before read-back.",
+    cpuToonPostPass:
+      "CPU 2D filter (render-core.ts applyToonTreatment): luma quantize + Sobel ink + grade on captured pixels. Never touches geometry/lighting.",
+    modes: RENDER_MODES,
+    styles: RENDER_STYLES
+  };
+}
+
+/** A material's render state subset relevant to the ghost fix (the engine's `renderState`). */
+export interface GhostFixableRenderState {
+  blend?: boolean;
+  depthWrite?: boolean;
+  depthTest?: boolean;
+}
+export interface GhostFixableMaterial {
+  readonly renderState?: GhostFixableRenderState;
+  /** Opacity, when the material exposes it — opacity 1 + blend on is the ghost signature. */
+  readonly opacity?: number;
+}
+
+/**
+ * GLOBAL ghost fix. If a material is BLENDed yet effectively opaque (opacity ≥ 1 or unspecified),
+ * force it opaque (blend off, depth write + test on) so its real textures render solid instead of
+ * washing into the background. Returns true when it changed something (for proof/logging). Safe to
+ * call on ANY render item — characters, props, set dressing — which is how the fix stays global.
+ */
+export function forceOpaqueIfGhost(material: GhostFixableMaterial | undefined | null): boolean {
+  const rs = material?.renderState;
+  if (!rs || !rs.blend) return false;
+  // A genuinely translucent material (opacity < 1) is left alone; only opaque-but-BLENDed ghosts
+  // are corrected.
+  const opacity = typeof material?.opacity === "number" ? material.opacity : 1;
+  if (opacity < 1) return false;
+  rs.blend = false;
+  rs.depthWrite = true;
+  rs.depthTest = true;
+  return true;
+}
+
+/** Apply the global ghost fix across a list of render items; returns the count of fixed materials. */
+export function forceOpaqueAcrossRenderItems(
+  items: readonly { readonly material?: GhostFixableMaterial }[]
+): number {
+  let fixed = 0;
+  for (const item of items) if (forceOpaqueIfGhost(item.material)) fixed += 1;
+  return fixed;
+}