create-aura3d 3.0.0 → 4.0.0

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

@@ -1,7 +1,21 @@
-// 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. A minimal Aura3D stage renders beneath the HUD.
-import { camera, createAuraApp, lights, material, model, primitives, scene } from "@aura3d/engine";
+// Character controller: keyboard input -> kinematic speed -> locomotion state
+// -> the E1 humanoid rig driven through its certified clip (playback speed
+// tracks locomotion) -> shoulder camera + DOM HUD + live proof object.
+// PRD-09: mounted via the shared runtime — createGame owns mount/lifecycle,
+// the §7.7 sci-fi-telemetry HUD theme, the §6.11 dpad-2btn touch preset,
+// game-sfx-core cues, and the juice event map.
+import {
+  camera,
+  game,
+  gameFeel,
+  looks,
+  material,
+  model,
+  primitives,
+  scene,
+  type AuraRuntimeNodeHandle
+} from "@aura3d/engine";
+import { createGame, sfxUrl } from "@aura3d/engine/game";
 import { createPerformanceGovernor, createTopDownGameRenderPreset } from "@aura3d/engine/production-runtime";
 import { createLocomotionKit } from "@aura3d/animation";
 import { assets } from "./aura-assets.js";
@@ -13,7 +27,11 @@ interface CharacterControllerProof {
   moving: boolean;
   running: boolean;
   clipWeights: ReadonlyArray<{ clip: string; weight: number }>;
-  hero: { readonly assetId: string; readonly url: string; readonly clip: string };
+  hero: { readonly assetId: string; readonly url: string; readonly clip: string; readonly metres: readonly [number, number, number] };
+  position: readonly [number, number, number];
+  yawDegrees: number;
+  look: { readonly id: string; readonly category: string };
+  camera: { readonly rig: string; readonly presented: boolean };
   debugDraw: boolean;
   governor: { readonly resolutionScale: number; readonly particleScale: number; readonly lodBias: number; readonly shadowSize: number };
 }
@@ -24,80 +42,205 @@ declare global {
   }
 }
 
+const LOOK_ID = "outdoor-day" as const;
 const tuning = defaultCharacterControllerTuning;
 const kit = createLocomotionKit({ idleClip: "Idle", walkClip: "Walk", runClip: "Run", walkSpeed: tuning.walkSpeed, runSpeed: tuning.runSpeed });
 
+// auraclash-player-rig is authored in metres (1.79 m tall); the derived
+// scale keeps the hero at the 1.62 m height the level was tuned for.
+const HERO_SCALE = 1.62 / assets.auraclashPlayerRig.bounds[1];
+// Locomotion is played by pacing the rig's walk loop to the movement speed
+// (0 = posed idle frame, >1 = run-paced walk).
+const CERTIFIED_CLIP = "Walk_Loop";
+const CLIP_SPEED: Record<"idle" | "walk" | "run", number> = {
+  idle: 0,
+  walk: 1,
+  run: Number((tuning.runSpeed / tuning.walkSpeed).toFixed(2))
+};
+
 const moveKeys = new Set(["KeyW", "KeyA", "KeyS", "KeyD", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
 const held = new Set<string>();
 window.addEventListener("keydown", (event) => held.add(event.code));
 window.addEventListener("keyup", (event) => held.delete(event.code));
 
-// J3 scaffold surface: the engine perf governor watches frame cost against the
-// top-down preset budget, and the debug key gates overlay detail in the HUD.
 const governorBudget = createTopDownGameRenderPreset().performanceBudget;
 let governor = createPerformanceGovernor("conservative");
 let debugDraw = false;
 
-const root = document.getElementById("app") ?? document.body;
-const hud = document.createElement("pre");
-hud.id = "character-controller-hud";
-hud.style.cssText = "font:14px monospace;padding:16px;color:#6cf;background:#0c0f16;min-height:140px";
-root.appendChild(hud);
-
-// Certified hero stage: the E1 humanoid-a rig (showcaseWalkAnimatedGirl, "Take
-// 001") plays its certified clip 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, 0.8, 0], distance: 3.2 }))
-    .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(model(assets.showcaseWalkAnimatedGirl, { name: "certified hero humanoid-a" }).position(0, 0, 0).animate({ clip: "Take 001", loop: true }))
-    .add(lights.ambient({ intensity: 0.35 }))
-    .add(lights.directional({ name: "key", position: [3, 5, 2], intensity: 1.4 }))
+// Full-bleed canvas: the app mounts straight into #app, which flexes to fill
+// the viewport (see index.html).
+const controllerGame = createGame({
+  id: "character-controller",
+  target: "#app",
+  autoStart: true,
+  input: {
+    actions: {
+      left: ["KeyA", "ArrowLeft"],
+      right: ["KeyD", "ArrowRight"],
+      run: ["ShiftLeft", "ShiftRight"],
+      debug: ["KeyT"]
+    },
+    bufferMs: 100
+  },
+  hud: { theme: "sci-fi-telemetry", widgets: [] },
+  touch: {
+    preset: "dpad-2btn",
+    bindings: { left: "left", right: "right", dash: "run", jump: "debug", attack: "debug" }
+  },
+  sound: {
+    cues: {
+      step: { id: "step", asset: { url: sfxUrl("footsteps.grass.00") }, volume: 0.4 },
+      "run-start": { id: "run-start", asset: { url: sfxUrl("vehicle.boost") }, volume: 0.4 },
+      "debug-toggle": { id: "debug-toggle", asset: { url: sfxUrl("ui.toggle.00") }, volume: 0.5 }
+    }
+  },
+  juice: {
+    "run-start": { punch: { fovDeg: 1.4, ms: 260 } },
+    "debug-toggle": { flash: { color: "#9fc7ff", peak: 0.12, ms: 120 } }
+  },
+  qualityRebuild: { flags: ["game"] },
+  evidence: {
+    schema: 1,
+    sections: { characterController: () => window.__AURA3D_CHARACTER_CONTROLLER_PROOF__ ?? { status: "unbound" } }
+  },
+  scene: () => scene()
+    .add(looks.preset(LOOK_ID))
+    .add(primitives.box({ name: "walkable ground", size: [30, 0.1, 30], position: [0, -0.05, 0], material: material.pbr({ color: "#4a6b3a", roughness: 0.92 }), receiveShadow: true }))
+    .add(primitives.box({ name: "distance marker north", size: [0.4, 1.4, 0.4], position: [0, 0.7, -6], material: material.pbr({ color: "#d97a3a", roughness: 0.6 }), castShadow: true }))
+    .add(primitives.box({ name: "distance marker east", size: [0.4, 1.4, 0.4], position: [5, 0.7, 0], material: material.pbr({ color: "#7fa3c2", roughness: 0.6 }), castShadow: true }))
+    .add(primitives.box({ name: "distance marker south-east", size: [0.4, 1.4, 0.4], position: [3.5, 0.7, 4.5], material: material.pbr({ color: "#b987d0", roughness: 0.6 }), castShadow: true }))
+    // C-10: a world wall for the shoulder rig's collision damper to pull in on.
+    .add(primitives.box({ name: "collision wall", size: [0.4, 2.4, 4], position: [2.4, 1.2, 4.2], material: material.pbr({ color: "#8a94a6", roughness: 0.85 }), castShadow: true }))
+    .add(
+      model(assets.auraclashPlayerRig, { name: "certified hero humanoid-a", castShadow: true })
+        .position(0, 0, 0)
+        .scale(HERO_SCALE)
+        .animate({ clip: CERTIFIED_CLIP, loop: true, speed: 0 })
+        .runtime(game.runtimeNode("hero", { tags: ["player"] }))
+    )
+    .camera(camera.perspective({ position: [0.55, 1.75, -2.8], target: [0, 1.35, 1.1], fov: 55 }))
 });
+const app = controllerGame.app;
+controllerGame.start();
+
+const heroNode: AuraRuntimeNodeHandle = app.nodes.require("hero");
+// F-08-1/C-10: the shoulder rig owns the presented camera and damps through
+// world collision (flag-off mounts the no-op stub controller; the authored
+// perspective spec stays the fallback). Right-half drag binds an orbit rig's
+// pointer handler for look input (no-op while rigs resolve to stubs).
+app.camera?.use(camera.rigs.shoulder({ target: "hero", collision: true }));
+const orbit = camera.rigs.orbit({ target: "hero" });
+const lookPad = document.createElement("div");
+lookPad.id = "look-pad";
+lookPad.setAttribute("style", "position:fixed;right:0;top:0;width:50%;height:100%;touch-action:none;");
+document.body.appendChild(lookPad);
+const orbitPointer = (orbit as { bindPointer?: (el: HTMLElement) => void }).bindPointer;
+if (orbitPointer) orbitPointer.call(orbit, lookPad);
+const feel = gameFeel.create({ app, time: app.time });
+app.feel?.preset("platformer");
 
+const hudRoot = createHud();
 let state: CharacterControllerState = { speed: 0 };
-let last = 0;
+let position = { x: 0, y: 0, z: 0 };
+let yaw = 0;
+let locomotionState: "idle" | "walk" | "run" = "idle";
 
-function frame(time: number): void {
-  const dt = last === 0 ? 1 / 60 : Math.min(0.05, (time - last) / 1000);
-  last = time;
+app.onFrame(({ dt }: { readonly dt: number }) => {
+  const seconds = Math.min(0.05, dt);
   if (held.has("KeyT")) {
     debugDraw = !debugDraw;
     held.delete("KeyT");
+    controllerGame.juice.fire("debug-toggle");
+    void controllerGame.sound?.cue("debug-toggle");
+  }
+
+  const dx = (held.has("KeyD") || held.has("ArrowRight") ? 1 : 0) - (held.has("KeyA") || held.has("ArrowLeft") ? 1 : 0);
+  const dz = (held.has("KeyS") || held.has("ArrowDown") ? 1 : 0) - (held.has("KeyW") || held.has("ArrowUp") ? 1 : 0);
+  const moving = [...held].some((code) => moveKeys.has(code));
+  const running = held.has("ShiftLeft") || held.has("ShiftRight");
+  const wasRunning = state.speed >= tuning.runSpeed - 0.01;
+  state = stepCharacterSpeed(state, { move: moving, run: running }, seconds, tuning);
+  const isRunning = state.speed >= tuning.runSpeed - 0.01;
+  if (isRunning && !wasRunning) {
+    controllerGame.juice.fire("run-start");
+    void controllerGame.sound?.cue("run-start");
+  }
+
+  if (dx !== 0 || dz !== 0) {
+    const length = Math.hypot(dx, dz);
+    const dirX = dx / length;
+    const dirZ = dz / length;
+    position = { x: position.x + dirX * state.speed * seconds, y: 0, z: position.z + dirZ * state.speed * seconds };
+    yaw = Math.atan2(dirX, dirZ);
+  }
+
+  const sample = kit.sample(state.speed, seconds);
+  const nextLocomotion = sample.state === "run" ? "run" : sample.state === "walk" ? "walk" : "idle";
+  heroNode.setPosition(position.x, position.y, position.z).setRotation(0, yaw, 0);
+  if (nextLocomotion !== locomotionState) {
+    locomotionState = nextLocomotion;
+    heroNode.setAnimation({ clip: CERTIFIED_CLIP, loop: true, speed: CLIP_SPEED[locomotionState] });
   }
-  const move = [...held].some((code) => moveKeys.has(code));
-  const run = held.has("ShiftLeft") || held.has("ShiftRight");
-  state = stepCharacterSpeed(state, { move, run }, dt, tuning);
-  const sample = kit.sample(state.speed, dt);
+
+  // The shoulder rig presents the camera; dt arrives scaled by app.time.
+  feel.update(dt * 1000);
+
   governor = governor.step(
-    { fps: 1 / Math.max(1 / 240, dt), frameTimeMs: dt * 1000, draws: 0, tris: 0, particles: 0, shadowBytes: 0 },
+    { fps: 1 / Math.max(1 / 240, seconds), frameTimeMs: seconds * 1000, draws: 0, tris: 0, particles: 0, shadowBytes: 0 },
     governorBudget
   );
+
+  const presented = Boolean(app.camera?.presented());
   const proof: CharacterControllerProof = {
     speed: Number(state.speed.toFixed(3)),
     state: sample.state,
     moving: sample.moving,
     running: sample.running,
     clipWeights: sample.clipWeights.map((w) => ({ clip: w.clip, weight: Number(w.weight.toFixed(3)) })),
-    hero: { assetId: assets.showcaseWalkAnimatedGirl.id, url: assets.showcaseWalkAnimatedGirl.url, clip: "Take 001" },
+    hero: {
+      assetId: assets.auraclashPlayerRig.id,
+      url: assets.auraclashPlayerRig.url,
+      clip: CERTIFIED_CLIP,
+      metres: assets.auraclashPlayerRig.bounds
+    },
+    position: [Number(position.x.toFixed(3)), position.y, Number(position.z.toFixed(3))],
+    yawDegrees: Number((yaw * 180 / Math.PI).toFixed(1)),
+    look: { id: LOOK_ID, category: "environment" },
+    camera: { rig: heroNode ? "shoulder:hero" : "", presented },
     debugDraw,
     governor: { ...governor.settings }
   };
   window.__AURA3D_CHARACTER_CONTROLLER_PROOF__ = proof;
-  hud.textContent = [
-    "Aura3D Character Controller — hold W/A/S/D (Shift = run, T = debug)",
-    `speed: ${proof.speed}`,
-    `state: ${proof.state}`,
-    `clips: ${proof.clipWeights.map((w) => `${w.clip} ${w.weight}`).join("  ")}`,
-    ...(debugDraw ? [`governor: res ${proof.governor.resolutionScale} lod ${proof.governor.lodBias} shadow ${proof.governor.shadowSize}`] : [])
-  ].join("\n");
-  requestAnimationFrame(frame);
+  renderHud(proof);
+});
+
+function createHud(): HTMLElement {
+  const root = document.createElement("aside");
+  root.id = "character-controller-hud";
+  root.style.cssText = [
+    "position:absolute",
+    "left:16px",
+    "top:16px",
+    "z-index:5",
+    "min-width:300px",
+    "font:600 13px/1.4 Inter, system-ui, sans-serif",
+    "color:#f2f8ff",
+    "background:rgba(16,26,34,0.72)",
+    "border:1px solid rgba(160,200,255,0.3)",
+    "border-radius:8px",
+    "padding:12px",
+    "pointer-events:none"
+  ].join(";");
+  document.body.append(root);
+  return root;
 }
 
-requestAnimationFrame(frame);
+function renderHud(proof: CharacterControllerProof): void {
+  hudRoot.innerHTML = [
+    `<strong>Aura3D Character Controller</strong> — hold W/A/S/D (Shift = run, T = debug)`,
+    `<div>speed: ${proof.speed} | state: ${proof.state} | pos: ${proof.position[0]}, ${proof.position[2]}</div>`,
+    `<div>clips: ${proof.clipWeights.map((w) => `${w.clip} ${w.weight}`).join("  ")}</div>`,
+    `<div>look: ${proof.look.id} | camera: ${proof.camera.rig} presented=${proof.camera.presented}</div>`,
+    ...(proof.debugDraw ? [`<div>governor: res ${proof.governor.resolutionScale} lod ${proof.governor.lodBias} shadow ${proof.governor.shadowSize}</div>`] : [])
+  ].join("");
+}

package/templates/character-controller/tests/certified-rig.spec.ts

@@ -3,7 +3,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expect, test } from "@playwright/test";
 
-test.setTimeout(60_000);
+test.setTimeout(240_000);
 
 /**
  * E1 certified-rig mount proof for the character-controller template.
@@ -38,7 +38,7 @@ test("character-controller hero mounts the certified humanoid-a rig", async ({ p
   await page.waitForFunction(
     () => Boolean((window as unknown as { __AURA3D_CHARACTER_CONTROLLER_PROOF__?: unknown }).__AURA3D_CHARACTER_CONTROLLER_PROOF__),
     undefined,
-    { timeout: 45_000 }
+    { timeout: 150_000 }
   );
   const hero = await page.evaluate(
     () =>

package/templates/character-controller/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/character-controller/tests/route-health.spec.ts

@@ -1,5 +1,12 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { expect, test } from "@playwright/test";
 
+// The locomotion proof's threshold hold alone can need most of a slow
+// software-GL minute; give the whole spec the same 300s headroom the
+// screenshot spec gets.
+test.setTimeout(300_000);
+
 test("character controller route exposes a live locomotion proof", async ({ page }) => {
   const errors: string[] = [];
   page.on("pageerror", (error) => errors.push(error.message));
@@ -8,19 +15,57 @@ test("character controller route exposes a live locomotion proof", async ({ page
   await page.waitForFunction(() => Boolean((window as unknown as { __AURA3D_CHARACTER_CONTROLLER_PROOF__?: unknown }).__AURA3D_CHARACTER_CONTROLLER_PROOF__));
 
   // idle at rest
-  const idle = await page.evaluate(() => (window as unknown as { __AURA3D_CHARACTER_CONTROLLER_PROOF__?: { state: string } }).__AURA3D_CHARACTER_CONTROLLER_PROOF__);
+  const idle = await page.evaluate(() => (window as unknown as { __AURA3D_CHARACTER_CONTROLLER_PROOF__?: { state: string; look?: { id: string }; camera?: { rig: string; presented: boolean } } }).__AURA3D_CHARACTER_CONTROLLER_PROOF__);
   expect(idle!.state).toBe("idle");
+  expect(idle!.look?.id).toBe("outdoor-day");
+  expect(idle!.camera?.rig).toBe("shoulder:hero");
+  expect(idle!.camera?.presented).toBe(true);
 
-  // holding a movement key accelerates into walk/run
+  // holding a movement key accelerates into walk/run and moves the hero
+  const before = await page.evaluate(() => (window as unknown as { __AURA3D_CHARACTER_CONTROLLER_PROOF__?: { position: readonly number[] } }).__AURA3D_CHARACTER_CONTROLLER_PROOF__?.position ?? [0, 0, 0]);
   await page.keyboard.down("KeyD");
-  await page.waitForTimeout(600);
-  const moving = await page.evaluate(() => (window as unknown as { __AURA3D_CHARACTER_CONTROLLER_PROOF__?: { state: string; speed: number; clipWeights: { weight: number }[] } }).__AURA3D_CHARACTER_CONTROLLER_PROOF__);
+  // Hold KeyD until the hero actually crosses the threshold rather than a
+  // wall-clock 600ms: sim time advances at most 0.25s per presented frame
+  // (dt clamp), so a fixed hold is meaningless on slow software-GL runners.
+  await page.waitForFunction(
+    (startX) => ((window as unknown as { __AURA3D_CHARACTER_CONTROLLER_PROOF__?: { position?: readonly number[] } }).__AURA3D_CHARACTER_CONTROLLER_PROOF__?.position?.[0] ?? 0) > startX + 0.05,
+    before[0] ?? 0,
+    { timeout: 180_000 }
+  );
+  const moving = await page.evaluate(() => (window as unknown as { __AURA3D_CHARACTER_CONTROLLER_PROOF__?: { state: string; speed: number; position: readonly number[]; clipWeights: { weight: number }[] } }).__AURA3D_CHARACTER_CONTROLLER_PROOF__);
   await page.keyboard.up("KeyD");
 
   expect(moving!.speed).toBeGreaterThan(0.1);
   expect(["walk", "run"]).toContain(moving!.state);
+  expect(moving!.position[0]).toBeGreaterThan((before[0] ?? 0) + 0.05);
   const sum = moving!.clipWeights.reduce((acc, w) => acc + w.weight, 0);
   expect(sum).toBeGreaterThan(0.9);
   expect(sum).toBeLessThan(1.1);
   expect(errors).toEqual([]);
+  // Playwright's visibility engine and bare evaluate() can starve behind the
+  // continuously rendering main thread just like boundingBox() below.
+  // waitForFunction polls inside the page's own animation frame, so it always
+  // gets a slot — assert the same semantics there.
+  await page.waitForFunction(() => {
+    const element = document.querySelector("canvas");
+    if (!(element instanceof HTMLCanvasElement)) return false;
+    const style = getComputedStyle(element);
+    return style.display !== "none" && style.visibility !== "hidden";
+  }, undefined, { timeout: 60_000 });
+  // Locator boundingBox() can block behind the continuously rendering main
+  // thread even after Playwright has resolved the canvas as visible. Read the
+  // same layout rectangle synchronously in the page, as the proof reads its
+  // runtime state above.
+  const canvasBounds = await page.evaluate(() => {
+    const element = document.querySelector("canvas");
+    if (!(element instanceof HTMLCanvasElement)) return null;
+    const bounds = element.getBoundingClientRect();
+    return { x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height };
+  });
+  expect(canvasBounds?.width ?? 0).toBeGreaterThan(0);
+  expect(canvasBounds?.height ?? 0).toBeGreaterThan(0);
+  mkdirSync(resolve("tests/reports"), { recursive: true });
+  writeFileSync(resolve("tests/reports/route-health.json"), `${JSON.stringify({
+    template: "character-controller", url: page.url(), canvasBounds, idle, moving, clipWeightSum: sum, errors
+  }, null, 2)}\n`);
 });