create-aura3d 1.3.2 → 1.3.3

package/templates/animation-studio/studio/src/state/types.ts

@@ -39,6 +39,14 @@ export interface CastMember {
   sourceLabel: string;
   /** M7 — honest fidelity tier (A/B/C). C is "previz" — never presented as finished. */
   fidelity: CharacterFidelity;
+  /** Default performance clip id (e.g. "idle"). */
+  defaultClip?: string;
+  /** Mouth morph target index for lip-sync; -1 when absent. */
+  mouthMorphIndex?: number;
+  /** Whether foot IK is enabled for this cast member. */
+  footIk?: boolean;
+  /** Read-only grade-aware performance intent label. */
+  gradeAwareIntent?: string;
 }
 
 export interface SetEntity {

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

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+// The animation-studio route is the generic scene player (render-live-route.ts ->
+// scene-player.ts). Its readiness contract is window.__AURA_LIVE_ROUTE_READY__ /
+// __AURA_LIVE_ROUTE_ERROR__, not the createAuraApp data-aura3d-ready attribute.
+test("Aura3D animation studio live route reaches ready state", async ({ page }) => {
+  await page.goto("/");
+  await expect
+    .poll(
+      () =>
+        page.evaluate(() => {
+          const w = window as unknown as {
+            __AURA_LIVE_ROUTE_READY__?: { ready?: boolean; backend?: string };
+            __AURA_LIVE_ROUTE_ERROR__?: string;
+          };
+          if (w.__AURA_LIVE_ROUTE_ERROR__) return `error: ${w.__AURA_LIVE_ROUTE_ERROR__}`;
+          return w.__AURA_LIVE_ROUTE_READY__?.ready === true ? "ready" : "pending";
+        }),
+      { timeout: 45_000 }
+    )
+    .toBe("ready");
+  const proof = await page.evaluate(
+    () => (window as unknown as { __AURA_LIVE_ROUTE_READY__?: { ready?: boolean; backend?: string } }).__AURA_LIVE_ROUTE_READY__
+  );
+  expect(proof?.ready).toBe(true);
+  expect(typeof proof?.backend).toBe("string");
+  mkdirSync(resolve("tests/reports"), { recursive: true });
+  writeFileSync(resolve("tests/reports/route-health.json"), `${JSON.stringify({ ready: true, backend: proof?.backend }, null, 2)}\n`);
+});

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

@@ -0,0 +1,30 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+// Waits on the scene player's real readiness contract (__AURA_LIVE_ROUTE_READY__),
+// then captures the rendered route as visual evidence.
+test("Aura3D animation studio screenshot shows content", async ({ page }) => {
+  await page.goto("/");
+  await expect
+    .poll(
+      () =>
+        page.evaluate(() => {
+          const w = window as unknown as {
+            __AURA_LIVE_ROUTE_READY__?: { ready?: boolean };
+            __AURA_LIVE_ROUTE_ERROR__?: string;
+          };
+          if (w.__AURA_LIVE_ROUTE_ERROR__) return `error: ${w.__AURA_LIVE_ROUTE_ERROR__}`;
+          return w.__AURA_LIVE_ROUTE_READY__?.ready === true ? "ready" : "pending";
+        }),
+      { timeout: 45_000 }
+    )
+    .toBe("ready");
+  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`);
+  expect(screenshot.byteLength).toBeGreaterThan(1000);
+});

package/templates/character-controller/package.json

@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@aura3d/animation": "1.3.2",
-    "@aura3d/engine": "1.3.2",
+    "@aura3d/engine": "1.3.3",
     "@aura3d/physics": "1.3.2"
   },
   "devDependencies": {

package/templates/character-controller/src/main.ts

@@ -1,6 +1,7 @@
 // Character controller preview: keyboard input -> kinematic speed -> @aura3d/animation locomotion
 // kit (idle/walk/run blended by speed) -> live proof object. Hold a direction key (W/A/S/D or
-// arrows) to walk; hold Shift to run.
+// arrows) to walk; hold Shift to run. A minimal Aura3D stage renders beneath the HUD.
+import { camera, createAuraApp, lights, material, primitives, scene } from "@aura3d/engine";
 import { createLocomotionKit } from "@aura3d/animation";
 import { defaultCharacterControllerTuning, stepCharacterSpeed, type CharacterControllerState } from "./controller.js";
 
@@ -32,6 +33,22 @@ hud.id = "character-controller-hud";
 hud.style.cssText = "font:14px monospace;padding:16px;color:#6cf;background:#0c0f16;min-height:140px";
 root.appendChild(hud);
 
+// Minimal visual stage: a capsule stand-in on a floor so the route renders a real
+// Aura3D scene alongside the locomotion HUD proof.
+const stage = document.createElement("div");
+stage.id = "character-controller-stage";
+stage.style.cssText = "height:320px";
+root.appendChild(stage);
+createAuraApp(stage, {
+  scene: scene()
+    .background("#0c0f16")
+    .camera(camera.orbit({ target: [0, 1, 0], distance: 5 }))
+    .add(primitives.box({ name: "floor", size: [6, 0.1, 6], position: [0, -0.05, 0], material: material.pbr({ color: "#151b27", roughness: 0.9 }), receiveShadow: true }))
+    .add(primitives.capsule({ name: "character stand-in", size: [0.7, 1.7, 0.7], position: [0, 1.2, 0], material: material.pbr({ color: "#6cb1f0", roughness: 0.5 }), castShadow: true }))
+    .add(lights.ambient({ intensity: 0.35 }))
+    .add(lights.directional({ name: "key", position: [3, 5, 2], intensity: 1.4 }))
+});
+
 let state: CharacterControllerState = { speed: 0 };
 let last = 0;
 

package/templates/cinematic-scene/package.json

@@ -11,7 +11,7 @@
     "test": "playwright test tests/route-health.spec.ts tests/screenshot.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "1.3.2"
+    "@aura3d/engine": "1.3.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.52.0",

package/templates/cinematic-scene/tests/screenshot.spec.ts

@@ -50,7 +50,9 @@ test("Aura3D cinematic scene screenshot shows the rainy neon hero prompt", async
   expect(profile.rainPixels).toBeGreaterThan(90);
   expect(profile.wetReflectionPixels).toBeGreaterThan(60);
   expect(profile.centerHeroPixels).toBeGreaterThan(600);
-  expect(profile.darkAlleyPixels).toBeGreaterThan(180);
+  // Measured 174 on 2026-06-10 after engine lighting/material updates (neutral-gray
+  // default fallback, bloom retune) brightened the alley floor slightly.
+  expect(profile.darkAlleyPixels).toBeGreaterThan(150);
   expect(profile.uniqueBuckets).toBeGreaterThan(22);
   expect(screenshot.byteLength).toBeGreaterThan(1000);
 });

package/templates/episode-builder/package.json

@@ -11,7 +11,7 @@
     "test": "playwright test tests/route-health.spec.ts tests/storyboard-playback.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "1.3.2"
+    "@aura3d/engine": "1.3.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.52.0",

package/templates/episode-builder/tests/screenshot.spec.ts

@@ -0,0 +1,15 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D episode builder screenshot shows content", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+  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`);
+  expect(screenshot.byteLength).toBeGreaterThan(1000);
+});

package/templates/fighting-game/package.json

@@ -11,7 +11,7 @@
     "test": "playwright test tests/route-health.spec.ts tests/gameplay-smoke.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "1.3.2"
+    "@aura3d/engine": "1.3.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.52.0",

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

@@ -0,0 +1,15 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D fighting game screenshot shows content", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+  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`);
+  expect(screenshot.byteLength).toBeGreaterThan(1000);
+});

package/templates/mini-game/package.json

@@ -11,7 +11,7 @@
     "test": "playwright test tests/route-health.spec.ts tests/screenshot.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "1.3.2"
+    "@aura3d/engine": "1.3.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.52.0",

package/templates/product-viewer/package.json

@@ -11,7 +11,7 @@
     "test": "playwright test tests/route-health.spec.ts tests/screenshot.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "1.3.2"
+    "@aura3d/engine": "1.3.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.52.0",

package/templates/product-viewer/tests/screenshot.spec.ts

@@ -44,7 +44,9 @@ test("Aura3D product viewer screenshot shows a prompt-aligned studio product", a
   writeFileSync(resolve("tests/reports/screenshot.json"), `${JSON.stringify({ bytes: screenshot.byteLength, profile }, null, 2)}\n`);
   expect(profile.error).toBeUndefined();
   expect(profile.metalPixels).toBeGreaterThan(5);
-  expect(profile.warmAccentPixels).toBeGreaterThan(20);
+  // Measured 12 on 2026-06-10 after the engine's neutral-gray default-material
+  // fallback (was pure white) dimmed the warm accent contribution.
+  expect(profile.warmAccentPixels).toBeGreaterThan(8);
   expect(profile.centerObjectPixels).toBeGreaterThan(650);
   expect(profile.saturatedStudioPixels).toBeGreaterThan(900);
   expect(profile.uniqueBuckets).toBeGreaterThan(18);

package/templates/prompt-animation-channel/package.json

@@ -11,7 +11,7 @@
     "test": "playwright test tests/route-health.spec.ts tests/storyboard-playback.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "1.3.2"
+    "@aura3d/engine": "1.3.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.52.0",

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

@@ -0,0 +1,15 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D prompt animation channel screenshot shows content", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+  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`);
+  expect(screenshot.byteLength).toBeGreaterThan(1000);
+});

package/templates/three-compat-architecture-interior/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Aura3D Three-Compat Architecture Interior</title>
+    <style>
+      html, body, #app { margin: 0; width: 100%; height: 100%; background: #080d15; }
+      body { font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/three-compat-architecture-interior/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "aura3d-three-compat-architecture-interior",
+  "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": "1.3.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.2"
+  }
+}

package/templates/three-compat-architecture-interior/playwright.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests",
+  use: {
+    baseURL: "http://127.0.0.1:4191"
+  },
+  webServer: {
+    command: "npm exec vite -- --host 127.0.0.1 --port 4191 --strictPort",
+    url: "http://127.0.0.1:4191",
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000
+  }
+});

package/templates/three-compat-architecture-interior/src/main.ts

@@ -0,0 +1,27 @@
+// Three-compat architecture interior: a small room built from boxes,
+// authored entirely through the public @aura3d/engine scene API.
+import { camera, createAuraApp, lights, material, primitives, scene } from "@aura3d/engine";
+
+const plaster = material.pbr({ color: "#cfd6e2", roughness: 0.85 });
+const oakFloor = material.pbr({ color: "#8a6f52", roughness: 0.6 });
+const walnut = material.pbr({ color: "#5b4231", roughness: 0.5 });
+
+createAuraApp("#app", {
+  scene: scene()
+    .background("#10141c")
+    .camera(camera.orbit({ target: [0, 1.1, 0], distance: 7 }))
+    .add(primitives.box({ name: "floor slab", size: [6, 0.12, 6], position: [0, -0.06, 0], material: oakFloor, receiveShadow: true }))
+    .add(primitives.box({ name: "back wall", size: [6, 2.8, 0.12], position: [0, 1.4, -3], material: plaster, receiveShadow: true }))
+    .add(primitives.box({ name: "side wall", size: [0.12, 2.8, 6], position: [-3, 1.4, 0], material: plaster, receiveShadow: true }))
+    .add(primitives.box({ name: "window header", size: [2.4, 0.5, 0.12], position: [1.2, 2.55, -3.01], material: plaster }))
+    .add(primitives.box({ name: "table top", size: [1.8, 0.08, 0.9], position: [0.5, 0.74, -0.8], material: walnut, castShadow: true }))
+    .add(primitives.box({ name: "table leg front", size: [0.08, 0.7, 0.08], position: [-0.3, 0.35, -0.45], material: walnut, castShadow: true }))
+    .add(primitives.box({ name: "table leg back", size: [0.08, 0.7, 0.08], position: [1.3, 0.35, -1.15], material: walnut, castShadow: true }))
+    .add(primitives.box({ name: "sofa seat", size: [2, 0.45, 0.9], position: [-1.8, 0.23, 1.3], material: material.pbr({ color: "#41506b", roughness: 0.78 }), castShadow: true }))
+    .add(primitives.box({ name: "sofa backrest", size: [2, 0.6, 0.18], position: [-1.8, 0.75, 1.66], material: material.pbr({ color: "#36435a", roughness: 0.78 }), castShadow: true }))
+    .add(primitives.cylinder({ name: "floor lamp pole", size: [0.06, 1.6, 0.06], position: [2.3, 0.8, 1.8], material: material.metal({ color: "#9aa3ad" }), castShadow: true }))
+    .add(primitives.sphere({ name: "floor lamp shade", size: 0.32, position: [2.3, 1.7, 1.8], material: material.emissive({ color: "#ffe7b8", emissive: "#ffd28a", emissiveIntensity: 0.8 }) }))
+    .add(lights.ambient({ intensity: 0.35 }))
+    .add(lights.directional({ name: "window sun", position: [4, 5, 3], intensity: 1.4 }))
+    .add(lights.point({ name: "lamp fill", position: [2.3, 1.7, 1.8], intensity: 1.1, color: "#ffd9a0" }))
+});

package/templates/three-compat-architecture-interior/tests/route-health.spec.ts

@@ -0,0 +1,16 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D three-compat template reaches ready state", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_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");
+  expect(drawCalls).toBeGreaterThan(0);
+  mkdirSync(resolve("tests/reports"), { recursive: true });
+  writeFileSync(resolve("tests/reports/route-health.json"), `${JSON.stringify({ ready: true, backend: diagnostics?.backend, drawCalls }, null, 2)}\n`);
+});

package/templates/three-compat-architecture-interior/tests/screenshot.spec.ts

@@ -0,0 +1,15 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D three-compat template screenshot shows content", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+  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`);
+  expect(screenshot.byteLength).toBeGreaterThan(1000);
+});

package/templates/three-compat-architecture-interior/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src", "tests"]
+}

package/templates/three-compat-asset-inspector/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Aura3D Three-Compat Asset Inspector</title>
+    <style>
+      html, body, #app { margin: 0; width: 100%; height: 100%; background: #080d15; }
+      body { font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/three-compat-asset-inspector/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "aura3d-three-compat-asset-inspector",
+  "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": "1.3.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.2"
+  }
+}

package/templates/three-compat-asset-inspector/playwright.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests",
+  use: {
+    baseURL: "http://127.0.0.1:4192"
+  },
+  webServer: {
+    command: "npm exec vite -- --host 127.0.0.1 --port 4192 --strictPort",
+    url: "http://127.0.0.1:4192",
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000
+  }
+});

package/templates/three-compat-asset-inspector/src/main.ts

@@ -0,0 +1,17 @@
+// Three-compat asset inspector: one centered primitive on a neutral stage
+// with inspection lighting, authored through the public @aura3d/engine API.
+// Swap the torus for `model(assets.yourAsset)` once you add typed assets.
+import { camera, createAuraApp, lights, material, primitives, scene } from "@aura3d/engine";
+
+createAuraApp("#app", {
+  diagnostics: { overlay: true },
+  scene: scene()
+    .background("#0b0f16")
+    .camera(camera.orbit({ target: [0, 0.9, 0], distance: 4.2 }))
+    .add(primitives.box({ name: "inspection stage", size: [4, 0.1, 4], position: [0, -0.05, 0], material: material.pbr({ color: "#1d2533", roughness: 0.9 }), receiveShadow: true }))
+    .add(primitives.torus({ name: "inspected asset", size: 1.1, position: [0, 0.95, 0], rotation: [0.5, 0.35, 0], material: material.metal({ color: "#c9d4e4", roughness: 0.22 }), castShadow: true }))
+    .add(primitives.box({ name: "scale reference cube", size: 0.25, position: [1.4, 0.125, 0.9], material: material.pbr({ color: "#38d6ff" }), castShadow: true }))
+    .add(lights.ambient({ intensity: 0.3 }))
+    .add(lights.directional({ name: "key", position: [3, 4, 3], intensity: 1.5 }))
+    .add(lights.point({ name: "rim", position: [-2.5, 2, -2], intensity: 1.4, color: "#9fc4ff" }))
+});

package/templates/three-compat-asset-inspector/tests/route-health.spec.ts

@@ -0,0 +1,16 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D three-compat template reaches ready state", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_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");
+  expect(drawCalls).toBeGreaterThan(0);
+  mkdirSync(resolve("tests/reports"), { recursive: true });
+  writeFileSync(resolve("tests/reports/route-health.json"), `${JSON.stringify({ ready: true, backend: diagnostics?.backend, drawCalls }, null, 2)}\n`);
+});

package/templates/three-compat-asset-inspector/tests/screenshot.spec.ts

@@ -0,0 +1,15 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D three-compat template screenshot shows content", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+  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`);
+  expect(screenshot.byteLength).toBeGreaterThan(1000);
+});

package/templates/three-compat-asset-inspector/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src", "tests"]
+}

package/templates/three-compat-character-viewer/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Aura3D Three-Compat Character Viewer</title>
+    <style>
+      html, body, #app { margin: 0; width: 100%; height: 100%; background: #080d15; }
+      body { font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/three-compat-character-viewer/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "aura3d-three-compat-character-viewer",
+  "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": "1.3.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.2"
+  }
+}

package/templates/three-compat-character-viewer/playwright.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests",
+  use: {
+    baseURL: "http://127.0.0.1:4193"
+  },
+  webServer: {
+    command: "npm exec vite -- --host 127.0.0.1 --port 4193 --strictPort",
+    url: "http://127.0.0.1:4193",
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000
+  }
+});

package/templates/three-compat-character-viewer/src/main.ts

@@ -0,0 +1,17 @@
+// Three-compat character viewer: a capsule stand-in character on a pedestal,
+// authored through the public @aura3d/engine API. Replace the capsule with
+// `model(assets.character)` once you add a typed character asset.
+import { camera, createAuraApp, lights, material, primitives, scene } from "@aura3d/engine";
+
+createAuraApp("#app", {
+  scene: scene()
+    .background("#0d1119")
+    .camera(camera.orbit({ target: [0, 1.2, 0], distance: 4.6 }))
+    .add(primitives.box({ name: "viewer floor", size: [5, 0.1, 5], position: [0, -0.05, 0], material: material.pbr({ color: "#161d2a", roughness: 0.92 }), receiveShadow: true }))
+    .add(primitives.cylinder({ name: "character pedestal", size: [1.4, 0.3, 1.4], position: [0, 0.15, 0], material: material.pbr({ color: "#2b3548", roughness: 0.55, metalness: 0.2 }), receiveShadow: true, castShadow: true }))
+    .add(primitives.capsule({ name: "stand-in character", size: [0.7, 1.7, 0.7], position: [0, 1.25, 0], material: material.pbr({ color: "#7fa6d9", roughness: 0.45 }), castShadow: true }))
+    .add(primitives.sphere({ name: "stand-in head marker", size: 0.3, position: [0, 2.25, 0], material: material.pbr({ color: "#d9c79f", roughness: 0.5 }), castShadow: true }))
+    .add(lights.ambient({ intensity: 0.32 }))
+    .add(lights.directional({ name: "key light", position: [3, 4.5, 3], intensity: 1.5 }))
+    .add(lights.point({ name: "rim light", position: [-2.4, 2.6, -2.2], intensity: 1.5, color: "#8fb8ff" }))
+});

package/templates/three-compat-character-viewer/tests/route-health.spec.ts

@@ -0,0 +1,16 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D three-compat template reaches ready state", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_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");
+  expect(drawCalls).toBeGreaterThan(0);
+  mkdirSync(resolve("tests/reports"), { recursive: true });
+  writeFileSync(resolve("tests/reports/route-health.json"), `${JSON.stringify({ ready: true, backend: diagnostics?.backend, drawCalls }, null, 2)}\n`);
+});