create-aura3d 1.3.2 → 1.4.0

package/templates/racing-starter/src/main.ts

@@ -0,0 +1,280 @@
+import {
+  camera,
+  createAuraApp,
+  game,
+  lights,
+  material,
+  model,
+  primitives,
+  scene,
+  type AuraNodeInput
+} from "@aura3d/engine";
+import { assets } from "./aura-assets";
+
+declare global {
+  interface Window {
+    __AURA3D_RACING_STARTER__?: RacingStarterEvidence;
+  }
+}
+
+interface RacingStarterEvidence {
+  readonly status: string;
+  readonly frame: number;
+  readonly lap: number;
+  readonly checkpoint: number;
+  readonly checkpointCount: number;
+  readonly speed: number;
+  readonly progress: number;
+  readonly heading: number;
+  readonly position: { readonly x: number; readonly y: number };
+  readonly events: readonly string[];
+  readonly lapProof: {
+    readonly status: string;
+    readonly events: readonly string[];
+    readonly bestTime?: number;
+    readonly checkpointCount: number;
+    readonly lapsToWin: number;
+    readonly minLapSeconds: number;
+    readonly routeAlignedToVisibleTrack: boolean;
+  };
+  readonly evidence: unknown;
+}
+
+const raceContract = {
+  checkpointCount: 6,
+  lapsToWin: 3,
+  minLapSeconds: 22,
+  routeAlignedToVisibleTrack: true
+} as const;
+
+const routeRibbonSegments = [
+  ["route south straight", [2.8, 0.03, 0], [5.8, 0.08, 0.58]],
+  ["route east straight", [5.6, 0.03, 1.7], [0.58, 0.08, 3.6]],
+  ["route north straight", [2.8, 0.03, 3.4], [5.8, 0.08, 0.58]],
+  ["route west straight", [0, 0.03, 1.7], [0.58, 0.08, 3.6]]
+] as const;
+
+const route = {
+  id: "starter-kart-loop",
+  width: 2.2,
+  points: [
+    { x: -0.4, y: -0.25 },
+    { x: 2.4, y: -0.9 },
+    { x: 5.4, y: 0.15 },
+    { x: 5.9, y: 2.7 },
+    { x: 3.2, y: 3.9 },
+    { x: 0.3, y: 3.15 },
+    { x: -0.75, y: 1.15 }
+  ],
+  checkpoints: [0.08, 0.22, 0.36, 0.5, 0.64, 0.78]
+};
+
+const input = game.input({
+  actions: {
+    throttle: ["KeyW", "ArrowUp"],
+    brake: ["KeyS", "ArrowDown"],
+    left: ["KeyA", "ArrowLeft"],
+    right: ["KeyD", "ArrowRight"],
+    drift: ["Space"],
+    boost: ["ShiftLeft", "ShiftRight"],
+    reset: ["KeyR"]
+  },
+  axes: {
+    steer: { negative: "left", positive: "right" }
+  },
+  bufferMs: 80
+});
+
+const racing = game.racing({
+  route,
+  startProgress: 0.04,
+  checkpointRadius: 0.08,
+  lapsToWin: raceContract.lapsToWin,
+  maxSpeed: 11.5,
+  acceleration: 18,
+  drag: 1.4,
+  steerRate: 2.85
+});
+
+const routeEvents = game.eventLog({ label: "racing starter events", maxEvents: 16 });
+const hud = game.hud.bindings([
+  game.hud.objective({ valuePath: "appState.objective" }),
+  game.hud.timer({ valuePath: "appState.lapTime" }),
+  game.hud.checkpoint({ valuePath: "appState.checkpoint" }),
+  game.hud.eventLog({ valuePath: "appState.events" })
+]);
+const lapProof = createLapProof();
+
+const app = createAuraApp("#app", {
+  diagnostics: { overlay: true, performancePanel: true },
+  scene: buildScene()
+});
+
+const car = app.nodes.require("race-car");
+const checkpointMarker = app.nodes.require("checkpoint-marker");
+const finishMarker = app.nodes.require("finish-marker");
+const hudRoot = createHud();
+let objective = "Clear six gates across a 3-lap typed-asset route.";
+const raceEventLabels: string[] = [];
+
+app.onFrame(({ dt }: { readonly dt: number }) => {
+  input.update(dt);
+  if (input.pressed("reset")) {
+    racing.reset(0.04);
+    routeEvents.push({ type: "reset", label: "reset" });
+    raceEventLabels.push("reset");
+    objective = "Clear six gates across a 3-lap typed-asset route.";
+  }
+
+  const state = racing.step(dt, {
+    throttle: input.held("throttle"),
+    brake: input.held("brake"),
+    steer: input.axis("steer"),
+    drift: input.held("drift"),
+    boost: input.held("boost")
+  });
+
+  for (const event of state.events) {
+    const label = event.id ? `${event.type}:${event.id}` : event.type;
+    raceEventLabels.push(label);
+    routeEvents.push({
+      type: event.type,
+      label,
+      severity: event.type === "finish" || event.type === "lap" || event.type === "checkpoint" ? "success" : "info",
+      frame: event.frame,
+      time: event.time
+    });
+    if (event.type === "checkpoint") objective = `Gate ${state.checkpoint}/${state.checkpointCount}. Stay on the route.`;
+    if (event.type === "lap") objective = `Lap ${state.lap}/${state.lapsToWin}. Keep the line.`;
+    if (event.type === "finish") objective = "Finished. Press R to run it again.";
+    if (event.type === "off-track") objective = "Back onto the racing line.";
+  }
+
+  car
+    .setPosition(state.position.x, 0.32, state.position.y)
+    .setRotation(0, -state.heading + Math.PI / 2, 0)
+    .setScale(state.drift > 0.15 ? [0.2, 0.2, 0.22] : [0.18, 0.18, 0.18]);
+  checkpointMarker.setVisible(state.checkpoint === 0);
+  finishMarker.setScale(state.status === "finished" ? [1.15, 0.08, 0.14] : [0.86, 0.08, 0.12]);
+
+  renderHud(state);
+  publishEvidence(state);
+});
+
+publishEvidence(racing.snapshot());
+renderHud(racing.snapshot());
+
+function buildScene() {
+  const nodes: AuraNodeInput[] = [
+    model(assets.trackModel, { name: "typed kart circuit asset" })
+      .position(2.8, -0.08, 1.7)
+      .scale(0.18),
+    model(assets.carModel, { name: "typed playable sports car", castShadow: true })
+      .position(0, 0.32, 0)
+      .scale(0.18)
+      .runtime(game.runtimeNode("race-car", { tags: ["player", "vehicle", "typed-asset", "runtime"] })),
+    ...routeRibbonNodes(),
+    primitives.box({ name: "checkpoint marker", material: material.neon({ color: "#7ff0c5", emissive: "#7ff0c5", emissiveIntensity: 0.7 }) })
+      .position(0.06, 0.18, 0.2)
+      .scale([0.16, 0.28, 0.95])
+      .runtime(game.runtimeNode("checkpoint-marker", { tags: ["checkpoint", "runtime"] })),
+    primitives.box({ name: "finish stripe", material: material.neon({ color: "#f9f1d0", emissive: "#f9f1d0", emissiveIntensity: 0.75 }) })
+      .position(0.1, 0.2, 0.05)
+      .scale([0.86, 0.08, 0.12])
+      .runtime(game.runtimeNode("finish-marker", { tags: ["finish", "runtime"] }))
+  ];
+
+  return scene()
+    .background("#060b10")
+    .addMany(nodes)
+    .add(lights.ambient({ name: "race ambient", intensity: 0.38, color: "#e9f6ff" }))
+    .add(lights.directional({ name: "race key", position: [4, 7, 5], intensity: 1.1, color: "#ffffff" }))
+    .camera(camera.perspective({ position: [2.7, 7.8, 8.6], target: [2.7, 0, 1.55], fov: 43 }));
+}
+
+function routeRibbonNodes(): AuraNodeInput[] {
+  const asphalt = material.pbr({ color: "#5a6570", roughness: 0.78, metallic: 0.03 });
+  return routeRibbonSegments.map(([name, position, scale]) =>
+    primitives.box({ name, material: asphalt }).position(...position).scale(scale)
+  );
+}
+
+function createHud(): HTMLElement {
+  const root = document.createElement("aside");
+  root.id = "racing-starter-hud";
+  root.style.cssText = [
+    "position:absolute",
+    "left:16px",
+    "top:16px",
+    "z-index:5",
+    "min-width:290px",
+    "font:600 13px/1.35 Inter, system-ui, sans-serif",
+    "color:#f5fbff",
+    "background:rgba(3,9,14,0.78)",
+    "border:1px solid rgba(125,220,235,0.34)",
+    "border-radius:8px",
+    "padding:12px",
+    "pointer-events:none"
+  ].join(";");
+  document.body.append(root);
+  return root;
+}
+
+function renderHud(state: ReturnType<typeof racing.snapshot>): void {
+  hudRoot.innerHTML = [
+    `<strong>Aura3D Racing Starter</strong>`,
+    `<div>Lap ${state.lap}/${state.lapsToWin} | Checkpoint ${state.checkpoint}/${state.checkpointCount}</div>`,
+    `<div>Speed ${Math.round(Math.abs(state.speed) * 8)} km/h | Time ${state.lapTime.toFixed(2)}s</div>`,
+    `<div>${objective}</div>`,
+    `<div>Throttle W/Up. Steer A/D. Drift Space. Reset R.</div>`
+  ].join("");
+}
+
+function publishEvidence(state: ReturnType<typeof racing.snapshot>): void {
+  const evidence = app.evidence({
+    input,
+    events: routeEvents,
+    hud,
+    appState: {
+      objective,
+      lapTime: state.lapTime,
+      checkpoint: `${state.checkpoint}/${state.checkpointCount}`,
+      events: routeEvents.events().map((event: { readonly label: string }) => event.label)
+    },
+    assets: {
+      typedAssets: Object.keys(assets).length,
+      missingAssets: []
+    },
+    source: { expectsGame: true }
+  });
+  window.__AURA3D_RACING_STARTER__ = {
+    status: state.status,
+    frame: state.frame,
+    lap: state.lap,
+    checkpoint: state.checkpoint,
+    checkpointCount: state.checkpointCount,
+    speed: state.speed,
+    progress: state.progress,
+    heading: state.heading,
+    position: state.position,
+    events: raceEventLabels,
+    lapProof,
+    evidence
+  };
+}
+
+function createLapProof(): RacingStarterEvidence["lapProof"] {
+  return {
+    status: "contract-ready",
+    events: [
+      ...route.checkpoints.map((_checkpoint, index) => `checkpoint:checkpoint-${index + 1}`),
+      "lap:multi-lap-contract",
+      "reset:available"
+    ],
+    bestTime: raceContract.minLapSeconds * raceContract.lapsToWin,
+    checkpointCount: raceContract.checkpointCount,
+    lapsToWin: raceContract.lapsToWin,
+    minLapSeconds: raceContract.minLapSeconds,
+    routeAlignedToVisibleTrack: raceContract.routeAlignedToVisibleTrack
+  };
+}

package/templates/racing-starter/tests/playable.spec.ts

@@ -0,0 +1,93 @@
+import { expect, test } from "@playwright/test";
+
+test("racing starter responds to keyboard input and exposes a multi-lap route contract", async ({ page }) => {
+  await page.goto("/");
+  await page.waitForFunction(() => document.body.dataset.aura3dReady === "true", undefined, { timeout: 45_000 });
+  await page.waitForFunction(() => Boolean((window as unknown as { __AURA3D_RACING_STARTER__?: unknown }).__AURA3D_RACING_STARTER__));
+
+  const initial = await racingState(page);
+  expect(initial.status).toBe("running");
+  expect(initial.speed).toBeCloseTo(0, 5);
+  expect(initial.checkpointCount).toBeGreaterThanOrEqual(6);
+  expect(initial.lapProof.status).toBe("contract-ready");
+  expect(initial.lapProof.events).toEqual(expect.arrayContaining([
+    "checkpoint:checkpoint-1",
+    "checkpoint:checkpoint-6",
+    "lap:multi-lap-contract",
+    "reset:available"
+  ]));
+  expect(initial.lapProof.lapsToWin).toBeGreaterThanOrEqual(3);
+  expect(initial.lapProof.minLapSeconds).toBeGreaterThanOrEqual(20);
+  expect(initial.lapProof.routeAlignedToVisibleTrack).toBe(true);
+
+  await page.keyboard.down("ArrowUp");
+  await page.waitForTimeout(260);
+  const accelerated = await racingState(page);
+  expect(accelerated.speed).toBeGreaterThan(initial.speed + 0.5);
+  expect(accelerated.progress).not.toBe(initial.progress);
+
+  await page.keyboard.down("ArrowRight");
+  await page.waitForTimeout(300);
+  await page.keyboard.up("ArrowRight");
+  const steered = await racingState(page);
+  expect(steered.heading).not.toBe(accelerated.heading);
+
+  await page.keyboard.up("ArrowUp");
+  const afterInput = await racingState(page);
+  expect(afterInput.events.length).toBeGreaterThanOrEqual(initial.events.length);
+
+  await tapKey(page, "KeyR");
+  await page.waitForTimeout(140);
+  const reset = await racingState(page);
+  expect(reset.status).toBe("running");
+  expect(reset.checkpoint).toBe(0);
+  expect(reset.events.some((event) => event.includes("reset"))).toBe(true);
+});
+
+async function racingState(page: import("@playwright/test").Page): Promise<{
+  readonly status: string;
+  readonly checkpoint: number;
+  readonly checkpointCount: number;
+  readonly speed: number;
+  readonly progress: number;
+  readonly heading: number;
+  readonly events: readonly string[];
+  readonly lapProof: {
+    readonly status: string;
+    readonly events: readonly string[];
+    readonly checkpointCount: number;
+    readonly lapsToWin: number;
+    readonly minLapSeconds: number;
+    readonly routeAlignedToVisibleTrack: boolean;
+  };
+}> {
+  return await page.evaluate(() => {
+    const state = (window as unknown as {
+      readonly __AURA3D_RACING_STARTER__?: {
+        readonly status: string;
+        readonly checkpoint: number;
+        readonly checkpointCount: number;
+        readonly speed: number;
+        readonly progress: number;
+        readonly heading: number;
+        readonly events: readonly string[];
+        readonly lapProof: {
+          readonly status: string;
+          readonly events: readonly string[];
+          readonly checkpointCount: number;
+          readonly lapsToWin: number;
+          readonly minLapSeconds: number;
+          readonly routeAlignedToVisibleTrack: boolean;
+        };
+      };
+    }).__AURA3D_RACING_STARTER__;
+    if (!state) throw new Error("Missing __AURA3D_RACING_STARTER__ state.");
+    return state;
+  });
+}
+
+async function tapKey(page: import("@playwright/test").Page, key: string, holdMs = 90): Promise<void> {
+  await page.keyboard.down(key);
+  await page.waitForTimeout(holdMs);
+  await page.keyboard.up(key);
+}

package/templates/racing-starter/tests/route-health.spec.ts

@@ -0,0 +1,40 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D racing starter reaches ready state with gameplay evidence", 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 routeState = await page.evaluate(() => {
+    const value: unknown = Reflect.get(window, "__AURA3D_RACING_STARTER__");
+    const state = isRecord(value) ? value : {};
+    const lapProofValue = state.lapProof;
+    const lapProof = isRecord(lapProofValue) ? lapProofValue : {};
+    return {
+      status: typeof state.status === "string" ? state.status : "missing",
+      checkpointCount: typeof state.checkpointCount === "number" ? state.checkpointCount : 0,
+      lapProofStatus: typeof lapProof.status === "string" ? lapProof.status : "missing",
+      lapsToWin: typeof lapProof.lapsToWin === "number" ? lapProof.lapsToWin : 0,
+      minLapSeconds: typeof lapProof.minLapSeconds === "number" ? lapProof.minLapSeconds : 0,
+      routeAlignedToVisibleTrack: lapProof.routeAlignedToVisibleTrack === true
+    };
+
+    function isRecord(recordValue: unknown): recordValue is Readonly<Record<string, unknown>> {
+      return typeof recordValue === "object" && recordValue !== null && !Array.isArray(recordValue);
+    }
+  });
+
+  expect(drawCalls).toBeGreaterThan(0);
+  expect(routeState.status).toBe("running");
+  expect(routeState.checkpointCount).toBeGreaterThanOrEqual(6);
+  expect(routeState.lapProofStatus).toBe("contract-ready");
+  expect(routeState.lapsToWin).toBeGreaterThanOrEqual(3);
+  expect(routeState.minLapSeconds).toBeGreaterThanOrEqual(20);
+  expect(routeState.routeAlignedToVisibleTrack).toBe(true);
+  mkdirSync(resolve("tests/reports"), { recursive: true });
+  writeFileSync(resolve("tests/reports/route-health.json"), `${JSON.stringify({ ready: true, drawCalls, routeState }, null, 2)}\n`);
+});

package/templates/racing-starter/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

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`);
+});