create-aura3d 3.0.1 → 4.0.0

package/templates/animation-channel/tests/look-floor.ts

@@ -0,0 +1,270 @@
+/**
+ * PRD-13 T3.12/T3.13 — the shared template look floor.
+ *
+ * Every create-aura3d template's `tests/screenshot.spec.ts` calls
+ * `assertTemplateLookFloor(page, ...)` after readiness: the same five checks
+ * everywhere (PRD §6.5/T3.12):
+ *
+ *   1. non-blank — sampled WebGL pixels are lit and varied (not a uniform
+ *      clear/void frame);
+ *   2. `diagnostics().look.lint` carries no `severity === "error"` finding
+ *      (empty when A3D_QR_LOOKS is off — the check never silently skips);
+ *   3. `appliedLook.environment.specularIntensity > 0` — an environment map
+ *      actually reached the frame;
+ *   4. `appliedLook.shadows.strength >= 0.8` when the look declares a shadow
+ *      caster (a null ShadowReport means the renderer produced no shadow
+ *      evidence — recorded, not failed);
+ *   5. `appliedLook.pixelRatio >= min(devicePixelRatio, tierCap)` — the
+ *      renderer used the display density up to the tier cap (2).
+ *
+ * …plus the optional §T3.12 subject check: the lit-pixel bounding box of the
+ * canvas' central region must sit within `tolerance` of the expected subject
+ * bounds (default ±10% of frame).
+ *
+ * Templates that mount through `createAuraApp` surface `appliedLook`/`look`
+ * via the global `__AURA3D_LIVE_APPS__` registry — no per-template wiring.
+ * `skipAppDiagnostics` covers the bespoke-renderer template (animation-studio),
+ * which reports its stage environment through its own readiness evidence.
+ */
+
+import { expect, type Page } from "@playwright/test";
+
+/** Normalized canvas-space bounds the lit subject mass is expected to occupy. */
+export interface LookFloorSubjectBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface LookFloorOptions {
+  /** Expected subject bounds in normalized canvas units. Omit to skip. */
+  readonly subject?: LookFloorSubjectBounds;
+  /** Fractional tolerance on each bound axis. Default 0.1 (±10%). */
+  readonly tolerance?: number;
+  /** Template has no `__AURA3D_LIVE_APPS__` app (bespoke renderer). */
+  readonly skipAppDiagnostics?: boolean;
+}
+
+export interface LookFloorReport {
+  readonly sampledPixels: number;
+  readonly brightPixels: number;
+  readonly uniqueBuckets: number;
+  readonly subjectBounds: LookFloorSubjectBounds | null;
+  readonly appliedLook: {
+    readonly specularIntensity: number;
+    readonly shadowStrength: number | null;
+    readonly pixelRatio: number;
+    readonly renderPath: string;
+    readonly background: string | null;
+  } | null;
+  readonly lookLintErrors: readonly string[];
+  readonly devicePixelRatio: number;
+}
+
+const MIN_BRIGHT_FRACTION = 0.02;
+const MIN_UNIQUE_BUCKETS = 8;
+
+export async function assertTemplateLookFloor(page: Page, options: LookFloorOptions = {}): Promise<LookFloorReport> {
+  const canvas = page.locator("canvas").first();
+  await expect(canvas).toBeVisible();
+
+  /*
+   * Deterministic frame before profiling: pause every live app, rewind its
+   * runtime clock and step a fixed 45 frames at 1/60 — through `stepAsync`,
+   * not the synchronous registry `settle()`. The production renderer mounts
+   * asynchronously, so a sync step loop renders nothing while the mount is in
+   * flight and never yields for it to finish (the failure mode on software-GL
+   * runners: blank frames, `environment.intensity` still NaN in diagnostics).
+   * Awaiting each step also lets pending environment/IBL/asset promises resolve
+   * between frames, and one final dt=0 step re-renders the same simulated
+   * instant once that work has applied.
+   */
+  const report = await page.evaluate(async (): Promise<LookFloorReport> => {
+    interface LiveApp {
+      pause?: () => void;
+      resetRuntimeClock?: () => void;
+      step?: (dt?: number) => void;
+      stepAsync?: (dt?: number) => Promise<unknown>;
+      diagnostics?: () => Record<string, unknown>;
+    }
+    const empty = (code: string): LookFloorReport => ({
+      sampledPixels: 0,
+      brightPixels: 0,
+      uniqueBuckets: 0,
+      subjectBounds: null,
+      appliedLook: null,
+      lookLintErrors: [code],
+      devicePixelRatio: globalThis.devicePixelRatio ?? 1
+    });
+    const registry = (globalThis as { __AURA3D_LIVE_APPS__?: { all?: () => readonly LiveApp[] } }).__AURA3D_LIVE_APPS__;
+    const apps = [...(registry?.all?.() ?? [])];
+    const stepApp = async (app: LiveApp, dt: number): Promise<void> => {
+      if (app.stepAsync) {
+        try {
+          await Promise.race([
+            app.stepAsync(dt),
+            new Promise((resolvePromise) => setTimeout(resolvePromise, 30_000))
+          ]);
+          return;
+        } catch {
+          // synchronous step fallback below
+        }
+      }
+      app.step?.(dt);
+    };
+    /*
+     * Wall-clock bound on the settle loop: on software-GL CI runners a single
+     * stepped render of a heavy scene costs several seconds, so an unbounded
+     * 45-step loop outlives the test budget and fails with a bare timeout and
+     * no report. Cap the stepping and always take the dt=0 settle frame — a
+     * partially settled scene still yields a readable floor report.
+     */
+    const STEP_WALLCLOCK_BUDGET_MS = 420_000;
+    const settleStartedAt = Date.now();
+    for (const app of apps) {
+      app.pause?.();
+      app.resetRuntimeClock?.();
+      for (let index = 0; index < 45; index += 1) {
+        if (Date.now() - settleStartedAt > STEP_WALLCLOCK_BUDGET_MS) break;
+        await stepApp(app, 1 / 60);
+      }
+      await stepApp(app, 0);
+    }
+    /*
+     * Renderers outside the liveApps registry (bespoke renderers, e.g.
+     * animation-studio's A3DRenderer) cannot be stepped. Two animation
+     * frames guarantee at least one full app render finished inside this
+     * evaluate task, so the readPixels below sees a real presented frame
+     * instead of a compositor-cleared buffer.
+     */
+    if (apps.length === 0) {
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+      });
+    }
+
+    const diagnostics = apps[0]?.diagnostics?.() as
+      | { appliedLook?: { environment?: { specularIntensity?: number; background?: string }; shadows?: { strength?: number | null } | null; pixelRatio?: number; renderPath?: string }; look?: { lint?: readonly { severity?: string; code?: string }[] } }
+      | undefined;
+    const appliedLook = diagnostics?.appliedLook
+      ? {
+          specularIntensity: diagnostics.appliedLook.environment?.specularIntensity ?? 0,
+          shadowStrength: diagnostics.appliedLook.shadows?.strength ?? null,
+          pixelRatio: diagnostics.appliedLook.pixelRatio ?? 0,
+          renderPath: diagnostics.appliedLook.renderPath ?? "unknown",
+          background: diagnostics.appliedLook.environment?.background ?? null
+        }
+      : null;
+    const lookLintErrors = (diagnostics?.look?.lint ?? [])
+      .filter((finding) => finding.severity === "error")
+      .map((finding) => finding.code ?? "unknown");
+    const devicePixelRatio = globalThis.devicePixelRatio ?? 1;
+
+    /*
+     * The app's WebGL context is not preserveDrawingBuffer, so readPixels must
+     * run in the same task as the stepped render, before compositing clears the
+     * drawing buffer. That also removes the composited element screenshot that
+     * software-GL runners could not produce inside a test timeout.
+     */
+    const target = [...document.querySelectorAll("canvas")]
+      .map((element) => ({
+        element,
+        gl: (element.getContext("webgl2") ?? element.getContext("webgl")) as WebGL2RenderingContext | WebGLRenderingContext | null
+      }))
+      .find((entry) => entry.gl !== null);
+    if (!target?.gl) return { ...empty("no-webgl-context"), appliedLook, lookLintErrors };
+    const gl = target.gl;
+    const width = gl.drawingBufferWidth;
+    const height = gl.drawingBufferHeight;
+    if (width === 0 || height === 0) return { ...empty("empty-drawing-buffer"), appliedLook, lookLintErrors };
+    // readPixels reads the currently bound framebuffer: renderers that end a
+    // frame with an offscreen target bound (shadow/post FBOs — e.g.
+    // animation-studio's bespoke renderer) would return that target's pixels
+    // instead of the canvas backbuffer. Rebind the default framebuffer first;
+    // every renderer rebinds its own targets at the start of its next frame.
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    const pixels = new Uint8Array(width * height * 4);
+    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+
+    const BRIGHT_LUMA = 48;
+    const stride = 4; // pixels — 16×16 sample grid
+    let sampled = 0;
+    let bright = 0;
+    const buckets = new Set<number>();
+    // Central-region lit-pixel bbox: edges carry floor/backdrop, the subject
+    // mass is what every §6.4 template frames mid-frame.
+    const x0 = Math.floor(width * 0.1);
+    const x1 = Math.floor(width * 0.9);
+    const y0 = Math.floor(height * 0.1);
+    const y1 = Math.floor(height * 0.9);
+    let minX = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (let y = 0; y < height; y += stride) {
+      for (let x = 0; x < width; x += stride) {
+        const offset = (y * width + x) * 4;
+        const r = pixels[offset] ?? 0;
+        const g = pixels[offset + 1] ?? 0;
+        const b = pixels[offset + 2] ?? 0;
+        sampled += 1;
+        buckets.add(((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4));
+        const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+        if (luma > BRIGHT_LUMA) {
+          bright += 1;
+          if (x >= x0 && x <= x1 && y >= y0 && y <= y1) {
+            minX = Math.min(minX, x);
+            maxX = Math.max(maxX, x);
+            minY = Math.min(minY, y);
+            maxY = Math.max(maxY, y);
+          }
+        }
+      }
+    }
+    // readPixels rows run bottom-up; report `y` in the same top-down
+    // convention the composited-screenshot path produced so stored
+    // expectations stay comparable across the switch.
+    const subjectBounds = Number.isFinite(minX)
+      ? { x: minX / width, y: 1 - maxY / height, width: (maxX - minX) / width, height: (maxY - minY) / height }
+      : null;
+
+    return {
+      sampledPixels: sampled,
+      brightPixels: bright,
+      uniqueBuckets: buckets.size,
+      subjectBounds,
+      appliedLook,
+      lookLintErrors,
+      devicePixelRatio
+    };
+  });
+
+  // 1. Non-blank.
+  expect(report.brightPixels / Math.max(1, report.sampledPixels)).toBeGreaterThan(MIN_BRIGHT_FRACTION);
+  expect(report.uniqueBuckets).toBeGreaterThan(MIN_UNIQUE_BUCKETS);
+
+  if (!options.skipAppDiagnostics) {
+    // 2–5. Renderer/look evidence via __AURA3D_LIVE_APPS__.
+    expect(report.appliedLook, "appliedLook diagnostics missing — is the app mounted via createAuraApp?").not.toBeNull();
+    expect(report.lookLintErrors).toEqual([]);
+      expect(report.appliedLook!.specularIntensity).toBeGreaterThan(0);
+    if (report.appliedLook!.shadowStrength !== null) {
+      expect(report.appliedLook!.shadowStrength!).toBeGreaterThanOrEqual(0.8);
+    }
+    expect(report.appliedLook!.pixelRatio).toBeGreaterThanOrEqual(Math.min(report.devicePixelRatio, 2));
+  }
+
+  // 6. Subject bounds ±10%.
+  if (options.subject) {
+    const tolerance = options.tolerance ?? 0.1;
+    const measured = `measured ${JSON.stringify(report.subjectBounds)}`;
+    expect(report.subjectBounds, "no lit subject mass in the central frame").not.toBeNull();
+    expect(Math.abs(report.subjectBounds!.x - options.subject.x), measured).toBeLessThanOrEqual(tolerance);
+    expect(Math.abs(report.subjectBounds!.y - options.subject.y), measured).toBeLessThanOrEqual(tolerance);
+    expect(Math.abs(report.subjectBounds!.width - options.subject.width), measured).toBeLessThanOrEqual(tolerance);
+    expect(Math.abs(report.subjectBounds!.height - options.subject.height), measured).toBeLessThanOrEqual(tolerance);
+  }
+
+  return report;
+}

package/templates/animation-channel/tests/route-health.spec.ts

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { expect, test } from "@playwright/test";
 
 test("animation channel route loads", async ({ page }) => {
-  test.setTimeout(90_000);
+  test.setTimeout(240_000);
   await page.goto("/");
   await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 60_000 }).toBe("true");
   await expect(page.locator("#app")).toBeVisible();

package/templates/animation-channel/tests/screenshot.spec.ts

@@ -1,16 +1,21 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { expect, test } from "@playwright/test";
+import { assertTemplateLookFloor } from "./look-floor";
 
-test.setTimeout(60_000);
+test.setTimeout(600_000);
 
-test("Aura3D animation channel screenshot shows content", async ({ page }) => {
+// PRD-13 T3.12 — look floor: non-blank, look.lint error-free, appliedLook
+// environment specular > 0, shadow strength >= 0.8, pixelRatio at tier cap,
+// subject bounds within ±10% — plus this template's bespoke assertions.
+test("Aura3D animation channel screenshot clears the look floor", async ({ page }) => {
   await page.goto("/");
-  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
-  const canvas = page.locator("canvas");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 150_000 }).toBe("true");
+
+  const floor = await assertTemplateLookFloor(page, { subject: { x: 0.15, y: 0.3, width: 0.7, height: 0.55 } });
   const screenshot = await page.screenshot({ fullPage: false });
   mkdirSync(resolve("tests/reports"), { recursive: true });
   writeFileSync(resolve("tests/reports/screenshot.png"), screenshot);
-  writeFileSync(resolve("tests/reports/screenshot.json"), `${JSON.stringify({ bytes: screenshot.byteLength }, null, 2)}\n`);
+  writeFileSync(resolve("tests/reports/screenshot.json"), `${JSON.stringify({ bytes: screenshot.byteLength, floor }, null, 2)}\n`);
   expect(screenshot.byteLength).toBeGreaterThan(1000);
 });

package/templates/animation-channel/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vite";
+import { auraDecodersPlugin } from "@aura3d/assets/vite";
+
+// F-05-04 (05-PKG): ship + serve the decoder vendor tree at /aura-decoders/
+// so compressed (KTX2/draco/meshopt) GLBs decode same-origin with correct
+// MIME in both `vite dev` and `vite preview`/deployed builds.
+export default defineConfig({ plugins: [auraDecodersPlugin()] });

package/templates/animation-studio/.claude/CLAUDE.md

@@ -0,0 +1,3 @@
+# Aura3D agent instructions
+
+Read ./llms.txt first. Read the `aura3d-art-direction` skill. Every scene gets a look. Run the look-dev loop (`aura3d look capture` → judge → iterate) before calling a scene done.

package/templates/animation-studio/.github/workflows/aura3d-lookdev.yml

@@ -0,0 +1,67 @@
+name: Aura3D look-dev
+
+# Captures this scene's screenshot tests on an Apple-silicon GPU runner
+# (ANGLE Metal) and uploads the report as the `lookdev` artifact.
+# `aura3d look capture --runner gh-actions` dispatches this workflow and
+# downloads the artifacts; it can also be run manually from the Actions tab.
+# No secrets are used; workflow_dispatch only — never runs forked code.
+
+on:
+  workflow_dispatch:
+    inputs:
+      shots:
+        description: "Shot names to capture (comma-separated; the template's defaults when empty)"
+        required: false
+        default: ""
+      viewports:
+        description: "Viewport names (comma-separated; the template's defaults when empty)"
+        required: false
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  capture:
+    name: Look-dev captures (macos-14, ANGLE Metal)
+    runs-on: macos-14
+    timeout-minutes: 45
+    env:
+      QRC_GPU_ARGS: "--use-angle=metal --enable-gpu --ignore-gpu-blocklist"
+      A3D_LOOKDEV_SHOTS: ${{ inputs.shots }}
+      A3D_LOOKDEV_VIEWPORTS: ${{ inputs.viewports }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          lfs: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build the app
+        run: npm run build
+
+      - name: Install Playwright Chromium
+        run: npx playwright install chromium
+
+      - name: Capture screenshots
+        run: npx playwright test tests/screenshot.spec.ts --reporter=line
+        env:
+          CHROMIUM_FLAGS: ${{ env.QRC_GPU_ARGS }}
+
+      - name: Upload look-dev artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: lookdev
+          path: |
+            tests/reports/**
+          if-no-files-found: warn
+          retention-days: 30

package/templates/animation-studio/AGENTS.md

@@ -1,71 +1,3 @@
-# Animation Studio — you are the director
+# Aura3D agent instructions
 
-**You** (Claude Code, Codex, Cursor, the API, whatever coding agent the user is already
-running) are the director. There is **no separate AI model and no API key** wired into this
-studio. The user gives a prompt; **you** turn it into a finished scene by driving the
-Scene-Tool CLI. You generate everything — the cast, the script/subtitles, the staging, the
-performance. The CLI is your hands; the renderer is deterministic.
-
-Every command edits one working document (`dist/scene/working.document.json`), is **validated**
-before it commits, and is **rejected** if it would break the scene (off-set, missing clip,
-bad framing). You cannot produce a broken document.
-
-## The loop (run these as shell commands)
-
-```bash
-S="pnpm exec tsx --tsconfig tsconfig.base.json packages/create-aura3d/templates/animation-studio/scripts/animation-scene.ts"
-# or, from an installed project:  aura3d animation scene <args...>
-```
-
-1. **Start a skeleton from the prompt** (picks a SET template + shots + timeline; NO dialogue —
-   you write that):
-   ```bash
-   $S new --prompt "two robots argue on a space station"
-   ```
-
-2. **Cast real characters** — resolve them from the live asset catalog by description. Use
-   DISTINCT queries so they look and move differently (each GLB brings its own clips):
-   ```bash
-   $S cast add --id rusty --query "rusty industrial robot"
-   $S cast add --id sleek --query "sleek white android robot"
-   ```
-   Provenance/license/scale are recorded automatically. `--scale N` overrides auto-fit.
-
-3. **Write the script** — this is the story AND the subtitles AND the AuraVoice lip-sync
-   contract, all one timed track. Author every line yourself; make it an actual arc:
-   ```bash
-   $S dialogue --line l1 --speaker rusty --text "You rerouted the coolant without telling me." --start 1 --end 6
-   $S dialogue --line l2 --speaker sleek --text "Because you'd have said no. The core was overheating." --start 7 --end 13
-   $S dialogue --line l3 --speaker rusty --text "That was MY system to balance." --start 21 --end 27
-   # …carry the argument to a turn and a resolution across the shots.
-   ```
-
-4. **Direct distinct performance per beat** — make the two characters DO different things so
-   it reads as an argument, not two idle loops. Move one in, push one back, face them off,
-   assign gestures. Motion is bounded by each GLB's clips — pick the clip that fits the beat:
-   ```bash
-   $S block --character rusty --shot shot-1 --to -1.2,0 --yaw 1.2 --clip walk
-   $S block --character sleek --shot shot-1 --to 1.2,0 --yaw -1.2
-   $S gesture --character rusty --shot shot-3 --clip <a-clip-the-GLB-has>
-   $S shot retime --id shot-2 --duration 24      # give the escalation room
-   ```
-   Use `$S show` to see the cast's real clip names before assigning them.
-
-5. **Render** and review:
-   ```bash
-   $S render
-   ```
-
-## Honest boundaries (do not oversell to the user)
-
-- **You write the story.** The skeleton has no dialogue on purpose. If you skip step 3 there
-  are no captions — that is correct, not a bug.
-- **Performance is limited by the asset's clips.** You can stage position, facing, camera, who
-  moves, and which existing clip plays — but you cannot synthesize motion a GLB doesn't contain.
-  If both characters look the same, you cast look-alike GLBs or left them on one clip; fix it by
-  casting distinct characters (step 2) and assigning per-beat clips/blocking (step 4).
-- **Subtitles ≠ voice.** Aura3D never does TTS. The dialogue track you write is the timed
-  contract AuraVoice consumes later to generate the voice locked to this timeline.
-
-The user's measure is "is this a watchable animation with a real story." That is **your** job as
-director — the tools guarantee a *valid* document, not a *good* one. Make it good.
+Read ./llms.txt first. Read the `aura3d-art-direction` skill. Every scene gets a look. Run the look-dev loop (`aura3d look capture` → judge → iterate) before calling a scene done.

package/templates/animation-studio/package.json

@@ -16,9 +16,10 @@
     "preview": "vite preview --host 0.0.0.0"
   },
   "dependencies": {
-    "@aura3d/animation": "3.0.1",
-    "@aura3d/engine": "3.0.1",
-    "@aura3d/navigation-recast": "3.0.1",
+    "@aura3d/animation": "4.0.0",
+    "@aura3d/assets": "4.0.0",
+    "@aura3d/engine": "4.0.0",
+    "@aura3d/navigation-recast": "4.0.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "sharp": "^0.33.5"

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

@@ -31,6 +31,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseGlbDocument } from "@aura3d/assets";
 import {
   AnimationClipRegistry,
   AnimationTrack,
@@ -137,13 +138,13 @@ interface GltfAnimation {
 }
 
 function parseGlb(buf: Buffer): ParsedGlb | null {
-  if (buf.length < 20 || buf.readUInt32LE(0) !== 0x46546c67) return null; // "glTF"
-  const jsonLen = buf.readUInt32LE(12);
-  const jsonStart = 20;
-  const json = JSON.parse(buf.slice(jsonStart, jsonStart + jsonLen).toString("utf8")) as GltfJson;
+  if (buf.length < 20 || buf.readUInt32LE(0) !== 0x46546c67) return null; // not "glTF" — skip
+  // Malformed GLBs past the magic throw from the shared parser, as the local JSON.parse did.
+  const doc = parseGlbDocument(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer, "clip-library://parse");
+  const json = doc.json as GltfJson;
   // BIN chunk follows the JSON chunk (8-byte chunk header: length + type 0x004E4942).
   let bin = Buffer.alloc(0);
-  const binHeader = jsonStart + jsonLen;
+  const binHeader = 20 + doc.jsonChunkBytes;
   if (binHeader + 8 <= buf.length && buf.readUInt32LE(binHeader + 4) === 0x004e4942) {
     const binLen = buf.readUInt32LE(binHeader);
     bin = buf.slice(binHeader + 8, binHeader + 8 + binLen);

package/templates/animation-studio/scripts/resolve-asset.ts

@@ -11,6 +11,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseGlbDocument } from "@aura3d/assets";
 import { ProbeSession } from "./asset-render-probe.js";
 import { probeEmbeddedMotion, type ClipMotionScore, type MotionProbeReport } from "./asset-motion-probe.js";
 
@@ -185,9 +186,11 @@ export function combineFidelity(rig: RigGrade, mesh: MeshGrade): RigGrade {
 const HUMANOID_BONE_HINTS = ["hips", "spine", "neck", "head", "shoulder", "arm", "forearm", "hand", "upleg", "leg", "foot", "thigh", "calf", "pelvis", "clavicle"];
 
 function inspectGlb(buf: Buffer): GlbInfo | null {
-  if (buf.readUInt32LE(0) !== 0x46546c67) return null;
-  const jlen = buf.readUInt32LE(12);
-  const json = JSON.parse(buf.slice(20, 20 + jlen).toString("utf8")) as Record<string, any>;
+  if (buf.length < 20 || buf.readUInt32LE(0) !== 0x46546c67) return null; // not "glTF"
+  // Malformed GLBs past the magic throw from the shared parser, as the local JSON.parse did.
+  const doc = parseGlbDocument(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer, "resolve-asset://inspect");
+  const json = doc.json as Record<string, any>;
+  const jsonChunkBytes = doc.jsonChunkBytes;
   const prims = (json.meshes ?? []).flatMap((m: any) => m.primitives ?? []);
   const imgs = json.images ?? [];
   const min = [1e9, 1e9, 1e9];
@@ -203,7 +206,7 @@ function inspectGlb(buf: Buffer): GlbInfo | null {
   }
   // ── Texture resolution: parse PNG/JPEG headers embedded in the BIN to read pixel dimensions.
   // glTF images don't carry width/height, so we sniff the actual encoded bytes. Largest wins.
-  const binStart = 20 + jlen + 8; // glb header(12) + json chunk header(8) + json + bin chunk header(8)
+  const binStart = 20 + jsonChunkBytes + 8; // glb header(12) + json chunk header(8) + json + bin chunk header(8)
   const views = (json.bufferViews ?? []) as any[];
   let textureMaxDim = 0;
   for (const img of imgs) {

package/templates/animation-studio/src/scene-player.ts

@@ -9,15 +9,15 @@
  * Dialogue/caption/viseme still come from the episode (`render-plan.ts`) — that timed
  * track is the AuraVoice contract and is shared across the pipeline.
  *
- * Imports resolve from the published `@aura3d/engine` (advanced-runtime A3DRenderer +
+ * Imports resolve from the published `@aura3d/engine` (renderer-subpath Renderer +
  * production-runtime typed GLB actors + rendering primitives), exactly as the old route.
  */
 
-import { A3DRenderer, TextureBinding as EngineTextureBinding } from "@aura3d/engine/advanced-runtime";
+import { Renderer, TextureBinding as EngineTextureBinding } from "@aura3d/engine/renderer";
 import { createPerformanceGovernor, createSideViewGameRenderPreset, createStudioLighting, createTypedGLBActor, type TypedGLBActor } from "@aura3d/engine/production-runtime";
 import { createCameraPathFromPreset, sampleCameraPath, type CameraPath } from "@aura3d/engine";
 // I1 clean-room correctness: import the rendering/scene PRIMITIVES from the engine's own subpaths
-// (`@aura3d/engine/rendering` / `@aura3d/engine/scene`) — the SAME copy the A3DRenderer uses — NOT
+// (`@aura3d/engine/rendering` / `@aura3d/engine/scene`) — the SAME copy the Renderer uses — NOT
 // the standalone `@aura3d/rendering` / `@aura3d/scene` packages. In a clean-room (tarball) install
 // those standalone packages are a SECOND copy of the rendering code, so a `Geometry`/`PBRMaterial`/
 // `TextureBinding` built from them is a DIFFERENT class than the renderer's, and the renderer's
@@ -537,7 +537,7 @@ export async function mountScenePlayer(doc: EpisodeDocument): Promise<void> {
   );
 
   // 7. Renderer + render source.
-  const renderer = await A3DRenderer.create({
+  const renderer = await Renderer.create({
     canvas,
     width,
     height,
@@ -569,7 +569,7 @@ export async function mountScenePlayer(doc: EpisodeDocument): Promise<void> {
   // mip chain, and its BRDF-LUT — is the SAME class and the renderer's `MaterialBinding.bind`
   // (`value instanceof TextureBinding`, see rendering/MaterialBinding.ts) accepts them. In a CLEAN-ROOM
   // install from tarballs the engine resolves into SEVERAL Vite-prebundled chunks: the app's
-  // `@aura3d/rendering` (which builds our env map) and `@aura3d/engine/advanced-runtime` (the renderer,
+  // `@aura3d/rendering` (which builds our env map) and `@aura3d/engine/renderer` (the renderer,
   // which builds the internal env-map/BRDF-LUT bindings) get DIFFERENT `TextureBinding` class objects,
   // so the `instanceof` check fails and the renderer throws `MaterialBindingError`
   // ("u_environmentMapTexture must be texture2d" / "Unsupported uniform value"). This is unfixable from
@@ -579,7 +579,7 @@ export async function mountScenePlayer(doc: EpisodeDocument): Promise<void> {
   //
   // The reliable, NON-POISONING signal is exactly that class-identity divergence: if our baked binding
   // (from `@aura3d/rendering`) is NOT `instanceof` the engine renderer's own `TextureBinding` (from
-  // `@aura3d/engine/advanced-runtime`), the engine is multi-chunk and its internal env bindings will be
+  // `@aura3d/engine/renderer`), the engine is multi-chunk and its internal env bindings will be
   // rejected too → skip IBL. When they ARE the same class (the monorepo / a correctly-deduped install)
   // IBL stays on, so this never changes the monorepo render's success.
   let iblBinding:

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

@@ -170,15 +170,18 @@ const MEADOW: SetSpec = {
 // themed keyword. This guarantees a non-matching prompt never silently inherits the
 // Moon Garden look; it gets a plain studio set instead.
 // ---------------------------------------------------------------------------
+// PRD-13 T3.10: the default stage adopts the `interior-warm` look's environment
+// and key (warm key light, warm softbox IBL, warm-grade background) instead of a
+// neutral grey rig. Episode tooling beyond this stage setup is out of scope.
 const STUDIO: SetSpec = {
-  clearColor: [0.06, 0.07, 0.09, 1],
+  clearColor: [0.11, 0.09, 0.07, 1], // interior-warm v0 background (#1c1712)
   studioLightingScale: 0.5,
   environment: {
-    color: [0.5, 0.52, 0.55],
-    intensity: 0.4,
-    proceduralMap: { skyColor: [0.18, 0.19, 0.21], horizonColor: [0.24, 0.25, 0.27], groundColor: [0.08, 0.08, 0.09], specularColor: [0.8, 0.82, 0.85], intensity: 0.4, specularIntensity: 0.5 },
-    // Neutral grey studio softbox IBL — even overhead key, no coloured cast (a clean cyc look).
-    hdri: { skyColor: [0.7, 0.71, 0.74], horizonColor: [0.34, 0.35, 0.38], groundColor: [0.12, 0.12, 0.14], sun: { color: [1, 1, 1], intensity: 1.4, azimuth: -0.3, elevation: 1.1, angularRadius: 0.22 }, intensity: 0.6, specularIntensity: 0.55 }
+    color: [0.55, 0.49, 0.42],
+    intensity: 0.45,
+    proceduralMap: { skyColor: [0.24, 0.2, 0.16], horizonColor: [0.3, 0.25, 0.2], groundColor: [0.1, 0.09, 0.08], specularColor: [0.9, 0.82, 0.72], intensity: 0.45, specularIntensity: 0.6 },
+    // Warm studio softbox IBL — interior-warm key (#ffe3c2) as the sun source.
+    hdri: { skyColor: [0.62, 0.55, 0.46], horizonColor: [0.38, 0.32, 0.26], groundColor: [0.14, 0.11, 0.09], sun: { color: [1, 0.89, 0.76], intensity: 1.9, azimuth: 0.87, elevation: 0.44, angularRadius: 0.22 }, intensity: 0.65, specularIntensity: 0.6 }
   },
   pieces: [
     // A FAR backdrop wall placed well behind the stage (not a giant enclosing dome): it reads as an
@@ -191,9 +194,10 @@ const STUDIO: SetSpec = {
     { id: "pillar-r", geometry: "cube", position: [3.4, 1.1, -2.6], scale: [0.42, 2.2, 0.42], baseColor: [0.16, 0.17, 0.2, 1], metallic: 0.3, roughness: 0.6, emissiveColor: [0.05, 0.05, 0.06], emissiveStrength: 0.12 }
   ],
   lights: [
-    { id: "key", kind: "point", color: [1, 0.97, 0.9], position: [-2.6, 3.8, 3.0], intensity: 4.4, range: 20 },
-    { id: "fill", kind: "point", color: [0.82, 0.84, 0.92], position: [2.8, 2.2, 1.6], intensity: 2.2, range: 14 },
-    { id: "rim", kind: "point", color: [0.9, 0.9, 1], position: [0.3, 2.2, -2.4], intensity: 2.4, range: 13 }
+    // interior-warm key/rim pair: warm key + warm accent rim (accent #e0a45c).
+    { id: "key", kind: "point", color: [1, 0.89, 0.76], position: [-2.6, 3.8, 3.0], intensity: 4.2, range: 20 },
+    { id: "fill", kind: "point", color: [0.85, 0.8, 0.72], position: [2.8, 2.2, 1.6], intensity: 2.0, range: 14 },
+    { id: "rim", kind: "point", color: [0.88, 0.64, 0.36], position: [0.3, 2.2, -2.4], intensity: 2.6, range: 13 }
   ]
 };