create-aura3d 3.0.0 → 4.0.0

package/templates/mini-game/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/mini-game/tests/playable.spec.ts

@@ -1,6 +1,6 @@
 import { expect, test } from "@playwright/test";
 
-test.setTimeout(60_000);
+test.setTimeout(240_000);
 
 type MiniGameState = {
   readonly score: number;
@@ -9,6 +9,8 @@ type MiniGameState = {
     readonly x: number;
     readonly y: number;
   };
+  readonly look: { readonly id: string };
+  readonly animation: { readonly clip: string; readonly tracksApplied: number };
 };
 
 function readMiniGameState(): MiniGameState | undefined {
@@ -17,10 +19,13 @@ function readMiniGameState(): MiniGameState | undefined {
 
 test("Aura3D mini game responds to keyboard input, scoring, and reset", async ({ page }) => {
   await page.goto("/");
-  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 150_000 }).toBe("true");
 
   const initial = await page.evaluate(readMiniGameState);
   expect(initial?.player.x).toBeLessThan(0.2);
+  // T3.1 floor evidence: the scene carries the genre look and the hero idles.
+  expect(initial?.look.id).toBe("outdoor-day");
+  expect(initial?.animation.clip).toBe("idle");
 
   await page.keyboard.down("ArrowRight");
   await page.waitForTimeout(650);
@@ -28,11 +33,17 @@ test("Aura3D mini game responds to keyboard input, scoring, and reset", async ({
 
   const moved = await page.evaluate(readMiniGameState);
   expect(moved?.player.x ?? 0).toBeGreaterThan((initial?.player.x ?? 0) + 1.2);
+  expect(["walk", "sprint"]).toContain(moved?.animation.clip);
+  // Report-only while the C-19 handle is a stub: tracksApplied is read into the
+  // report so the floor gate can tighten it once PRD 06 lands.
+  const tracks = moved?.animation.tracksApplied ?? 0;
+  console.log(`[mini-game] hero tracksApplied=${tracks} clip=${moved?.animation.clip}`);
 
   await page.keyboard.press("Space");
   await page.waitForTimeout(180);
   const jumped = await page.evaluate(readMiniGameState);
   expect(jumped?.player.y ?? 0).toBeGreaterThan(moved?.player.y ?? 0);
+  expect(jumped?.animation.clip).toBe("jump");
 
   await page.keyboard.down("ArrowRight");
   await page.waitForTimeout(1600);
@@ -41,9 +52,19 @@ test("Aura3D mini game responds to keyboard input, scoring, and reset", async ({
   expect(progressed?.score ?? 0).toBeGreaterThanOrEqual(50);
   expect(progressed?.events.length ?? 0).toBeGreaterThan(0);
 
+  // Hazard death path: dash right into the spike lane resets position and
+  // records a hazard/respawn event.
+  await page.keyboard.down("ArrowRight");
+  await page.waitForTimeout(2000);
+  await page.keyboard.up("ArrowRight");
+  const hazard = await page.evaluate(readMiniGameState);
+  const deathsOrEvents = hazard?.events ?? [];
+  expect(deathsOrEvents.some((event) => event.includes("hazard") || event.includes("respawn") || event.includes("collect"))).toBe(true);
+
   await page.keyboard.press("KeyR");
   await page.waitForTimeout(120);
   const reset = await page.evaluate(readMiniGameState);
   expect(reset?.player.x ?? 99).toBeLessThan(0.3);
   expect(reset?.events.some((event) => event.includes("reset"))).toBe(true);
+  expect(reset?.animation.clip).toBe("idle");
 });

package/templates/mini-game/tests/route-health.spec.ts

@@ -2,11 +2,11 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { expect, test } from "@playwright/test";
 
-test.setTimeout(60_000);
+test.setTimeout(240_000);
 
 test("Aura3D mini game reaches ready state", async ({ page }) => {
   await page.goto("/");
-  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 150_000 }).toBe("true");
   const drawCalls = Number(await page.locator("body").getAttribute("data-aura3d-draw-calls"));
   const diagnostics = await page.evaluate(() => (window as unknown as { __AURA3D_ROUTE_READY__?: { diagnostics?: { backend?: string } } }).__AURA3D_ROUTE_READY__?.diagnostics);
   expect(diagnostics?.backend).toBe("webgl2");

package/templates/mini-game/tests/screenshot.spec.ts

@@ -1,68 +1,59 @@
 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 mini game screenshot shows a readable playable scene", 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 mini game 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");
-
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 150_000 }).toBe("true");
+  // Hold ArrowRight until the player crosses the threshold rather than a
+  // wall-clock 550ms: sim time advances at most 0.25s per presented frame
+  // (dt clamp), so a fixed wall hold is meaningless on slow renderers.
   await page.keyboard.down("ArrowRight");
-  await page.waitForTimeout(550);
+  await page.waitForFunction(
+    () => ((window as unknown as { __AURA3D_MINI_GAME__?: { readonly player?: { readonly x?: number } } }).__AURA3D_MINI_GAME__?.player?.x ?? 0) > 0.8,
+    undefined,
+    { timeout: 180_000 }
+  );
   await page.keyboard.up("ArrowRight");
-
   const state = await page.evaluate(() =>
-    (window as unknown as {
-      readonly __AURA3D_MINI_GAME__?: {
-        readonly score: number;
-        readonly player: { readonly x: number };
-      };
-    }).__AURA3D_MINI_GAME__
+    (window as unknown as { __AURA3D_MINI_GAME__?: { readonly player?: { readonly x: number }; readonly look?: { readonly id: string } } }).__AURA3D_MINI_GAME__
   );
-  expect(state?.player.x ?? 0).toBeGreaterThan(0.8);
-
-  const canvas = page.locator("canvas");
-  const profile = await canvas.evaluate((element) => {
-    const target = element as HTMLCanvasElement;
-    const gl = target.getContext("webgl2", { preserveDrawingBuffer: true });
-    if (!gl) return { error: "missing-webgl2", brightPixels: 0, warmPixels: 0, cyanPixels: 0, redPixels: 0, uniqueBuckets: 0 };
-    const pixels = new Uint8Array(target.width * target.height * 4);
-    gl.readPixels(0, 0, target.width, target.height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
-    const buckets = new Set<string>();
-    let brightPixels = 0;
-    let warmPixels = 0;
-    let cyanPixels = 0;
-    let redPixels = 0;
-    for (let y = 0; y < target.height; y += 4) {
-      for (let x = 0; x < target.width; x += 4) {
-        const offset = (y * target.width + x) * 4;
-        const r = pixels[offset] ?? 0;
-        const g = pixels[offset + 1] ?? 0;
-        const b = pixels[offset + 2] ?? 0;
-        const luminance = r * 0.2126 + g * 0.7152 + b * 0.0722;
-        if (luminance > 30) {
-          brightPixels += 1;
-          buckets.add(`${r >> 5}-${g >> 5}-${b >> 5}`);
-        }
-        if (r > 130 && g > 105 && b < 155 && r >= g * 0.9) warmPixels += 1;
-        if (g > 115 && b > 105 && r < 190 && b >= r * 0.78) cyanPixels += 1;
-        if (r > 120 && g < 150 && b < 180 && r > g * 1.03) redPixels += 1;
-      }
-    }
-    return { brightPixels, warmPixels, cyanPixels, redPixels, uniqueBuckets: buckets.size };
+  expect(state?.player?.x ?? 0).toBeGreaterThan(0.8);
+  expect(state?.look?.id).toBe("outdoor-day");
+  const floor = await assertTemplateLookFloor(page, { subject: { x: 0.05, y: 0.35, width: 0.9, height: 0.55 } });
+  // class-(b) readback: capture through the app (C-05) instead of the
+  // compositor screenshot path — the output surface owns the frame.
+  // `__AURA3D_LIVE_APPS__` is the live-app registry (not an array); `output`
+  // is the C-05 extension installed under A3D_QR_CORE. A missing registry,
+  // app or surface fails the spec instead of writing an empty frame.
+  const pngBase64 = await page.evaluate(async () => {
+    const registry = (window as unknown as {
+      __AURA3D_LIVE_APPS__?: {
+        all(): readonly { output?: { capture(o: { type: "png-blob" }): Promise<Blob | ImageBitmap> } }[];
+      };
+    }).__AURA3D_LIVE_APPS__;
+    if (!registry) throw new Error("app.output.capture: __AURA3D_LIVE_APPS__ registry is not installed");
+    const app = registry.all()[0];
+    if (!app) throw new Error("app.output.capture: no live Aura3D app is mounted");
+    if (!app.output) throw new Error("app.output.capture: app.output (C-05, A3D_QR_CORE) is not installed");
+    const blob = await app.output.capture({ type: "png-blob" });
+    if (!(blob instanceof Blob)) throw new Error("app.output.capture: png-blob capture did not return a Blob");
+    const dataUrl = await new Promise<string>((resolvePromise) => {
+      const reader = new FileReader();
+      reader.onload = () => resolvePromise(String(reader.result));
+      reader.readAsDataURL(blob);
+    });
+    return dataUrl.split(",")[1] ?? "";
   });
-
-  const screenshot = await page.screenshot({ fullPage: false });
+  const screenshot = Buffer.from(pngBase64, "base64");
   mkdirSync(resolve("tests/reports"), { recursive: true });
   writeFileSync(resolve("tests/reports/screenshot.png"), screenshot);
-  writeFileSync(resolve("tests/reports/screenshot.json"), `${JSON.stringify({ bytes: screenshot.byteLength, profile, state }, null, 2)}\n`);
-
-  expect(profile.error).toBeUndefined();
-  expect(profile.brightPixels).toBeGreaterThan(900);
-  expect(profile.cyanPixels).toBeGreaterThan(20);
-  expect(profile.warmPixels).toBeGreaterThan(10);
-  expect(profile.redPixels).toBeGreaterThan(5);
-  expect(profile.uniqueBuckets).toBeGreaterThan(10);
+  writeFileSync(resolve("tests/reports/screenshot.json"), `${JSON.stringify({ bytes: screenshot.byteLength, floor }, null, 2)}\n`);
   expect(screenshot.byteLength).toBeGreaterThan(1000);
 });

package/templates/mini-game/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/postprocess-scene/.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/postprocess-scene/.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/postprocess-scene/AGENTS.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/postprocess-scene/README.md

@@ -0,0 +1,17 @@
+# Aura3D postprocess scene
+
+Three-compat starter on the public `@aura3d/engine` API.
+
+```bash
+npm install
+npm run dev
+npm run test
+```
+
+Heroes: two repository-owned showcase GLBs with real emissive materials
+(`luma` Cyberpunk_MAT, `miko` glow mat) blooming through the `neon-arcade`
+look's post pipeline plus an explicit `effects.bloom` node.
+
+Mirrors the three.js r185 example `webgl_postprocessing_unreal_bloom`
+(emissive subjects on a dark field under bloom); composition mirror only,
+no parity claim.

package/templates/postprocess-scene/aura.assets.json

@@ -0,0 +1,38 @@
+{
+  "schema": "aura3d.assets/1.0",
+  "assetBasePath": "/aura-assets/",
+  "outputDir": "public/aura-assets",
+  "typegen": "src/aura-assets.ts",
+  "assets": [
+    {
+      "id": "luma",
+      "type": "model",
+      "format": "glb",
+      "source": "public/aura-assets/showcaseLuma.ef389217.glb",
+      "outputPath": "public/aura-assets/showcaseLuma.ef389217.glb",
+      "url": "/aura-assets/showcaseLuma.ef389217.glb",
+      "hash": "sha256-ef3892179fe70cf2062cdbafcce131d33968a7667e087d630b866a4fd022c74d",
+      "sizeBytes": 2856452,
+      "bounds": [102.874, 100.914, 100.914],
+      "materials": ["Cyberpunk_MAT"],
+      "animations": ["Idle"],
+      "textures": [],
+      "provenance": "Aura3D showcase cast (repository-owned); emissive Cyberpunk_MAT"
+    },
+    {
+      "id": "miko",
+      "type": "model",
+      "format": "glb",
+      "source": "public/aura-assets/showcaseMiko.fcdc2b75.glb",
+      "outputPath": "public/aura-assets/showcaseMiko.fcdc2b75.glb",
+      "url": "/aura-assets/showcaseMiko.fcdc2b75.glb",
+      "hash": "sha256-fcdc2b7502031e556259dfe942fdfbd7abe41963433f2046ed2522d27bce9d65",
+      "sizeBytes": 1997240,
+      "bounds": [1.015, 1.95, 0.369],
+      "materials": ["miko_body_mat", "miko_dark_mat", "miko_glow_mat", "miko_skin_mat", "miko_accent_mat"],
+      "animations": ["Idle", "Wave", "Walk", "Talk"],
+      "textures": [],
+      "provenance": "Aura3D showcase cast (repository-owned); miko_glow_mat emissive"
+    }
+  ]
+}

package/templates/postprocess-scene/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "aura3d-postprocess-scene",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run typecheck && vite build",
+    "preview": "vite preview --host 127.0.0.1",
+    "test": "playwright test tests/route-health.spec.ts tests/screenshot.spec.ts --workers=1"
+  },
+  "dependencies": {
+    "@aura3d/engine": "4.0.0",
+    "@aura3d/navigation-recast": "4.0.0",
+    "@aura3d/assets": "4.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.59.1",
+    "@types/node": "^22.15.30",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.2"
+  }
+}