create-aura3d 3.0.0 → 4.0.0

package/templates/fighting-game/src/main.ts

@@ -1,4 +1,8 @@
-import { camera, createGameApp, effects, game, lights, scene, ui } from "@aura3d/engine";
+import { camera, effects, game, gameFeel, lights, looks, scene, ui } from "@aura3d/engine";
+// PRD-09: mounted via the shared runtime — createGame owns mount/lifecycle,
+// the §7.7 fighting HUD theme, the §6.11 dpad-4btn touch preset,
+// game-sfx-core cues, and the juice event map.
+import { createGame, sfxUrl } from "@aura3d/engine/game";
 import { assets } from "./aura-assets";
 import {
   animationLayer,
@@ -26,6 +30,7 @@ import {
 import "./styles.css";
 
 type Aura3DGameWindow = Window & {
+  __AURA3D_GAME__?: { readonly state?: string };
   __AURA3D_GAME_DEBUG__?: unknown;
   __AURA3D_GAME_EVIDENCE__?: unknown;
   __AURA3D_GAME_RUNTIME__?: unknown;
@@ -61,7 +66,6 @@ ui.html(
     <section class="hud__panel hud__panel--meta" aria-label="Runtime evidence">
       <span id="hud-round">Round 1 - 99</span>
       <span id="hud-frame">Frame 0</span>
-      <span id="hud-camera">Camera zoom 1.00</span>
       <span id="hud-assets">Typed assets ${typedFighterAssetCount}/2</span>
       <span id="hud-stage">Stage ${fightingStage.id}</span>
       <span id="hud-replay">Replay ready</span>
@@ -79,43 +83,59 @@ const hudRivalHealth = ui.text("#hud-rival-health");
 const hudPlayerMeter = ui.text("#hud-player-meter");
 const hudRound = ui.text("#hud-round");
 const hudFrame = ui.text("#hud-frame");
-const hudCamera = ui.text("#hud-camera");
 const hudAssets = ui.text("#hud-assets");
 const hudStage = ui.text("#hud-stage");
 const hudReplay = ui.text("#hud-replay");
 const replayButton = ui.button("#hud-replay-button");
 const pauseButton = ui.button("#hud-pause-button");
 
-const hudBindings = game.hud.bindings([
-  game.hud.health({ actorId: "player", label: "Player health", a11yLabel: "player health" }),
-  game.hud.health({ actorId: "rival", label: "Rival health", a11yLabel: "rival health" }),
-  game.hud.meter({ actorId: "player", label: "Player meter", a11yLabel: "player special meter" }),
-  game.hud.timer({ label: "Round timer", valuePath: "round.timeRemaining", a11yLabel: "round timer" }),
-  game.hud.combo({ actorId: "player", label: "Player combo", valuePath: "combat.player.combo", a11yLabel: "player combo" }),
-  game.hud.round({ label: "Round", valuePath: "round.index", a11yLabel: "round index" }),
-  game.hud.debugToggle({ label: "Runtime evidence", action: "debug", statePath: "debug.visible" })
-]);
+// Descriptor literals replace the deprecated game.hud.* / game.accessibility.*
+// helpers — same evidence shape, no factory call.
+const hudBindings = [
+  { kind: "aura-game-hud-binding", owner: "app", binding: "health", id: "hud:player:health", label: "Player health", source: "combat", targetId: "player", valuePath: "combat.actors.player.health", maxPath: "rules.maxHealth", format: "percent", a11yLabel: "player health" },
+  { kind: "aura-game-hud-binding", owner: "app", binding: "health", id: "hud:rival:health", label: "Rival health", source: "combat", targetId: "rival", valuePath: "combat.actors.rival.health", maxPath: "rules.maxHealth", format: "percent", a11yLabel: "rival health" },
+  { kind: "aura-game-hud-binding", owner: "app", binding: "meter", id: "hud:player:meter", label: "Player meter", source: "combat", targetId: "player", valuePath: "combat.actors.player.meter", maxPath: "rules.maxMeter", format: "percent", a11yLabel: "player super meter value" },
+  { kind: "aura-game-hud-binding", owner: "app", binding: "timer", id: "hud:round:timer", label: "Round timer", source: "app-state", valuePath: "round.timeRemaining", format: "clock", a11yLabel: "round timer" },
+  { kind: "aura-game-hud-binding", owner: "app", binding: "combo", id: "hud:player:combo", label: "Player combo", source: "combat", targetId: "player", valuePath: "combat.player.combo", format: "number", a11yLabel: "player combo" },
+  { kind: "aura-game-hud-binding", owner: "app", binding: "round", id: "hud:round:index", label: "Round", source: "app-state", valuePath: "round.index", format: "number", a11yLabel: "round index" },
+  { kind: "aura-game-hud-binding", owner: "app", binding: "debug-toggle", id: "hud:debug:toggle", label: "Runtime evidence", source: "app-state", valuePath: "debug.visible", format: "boolean", a11yLabel: "runtime evidence toggle", debugOnly: true }
+] as const;
 
 const accessibilitySources = [
-  game.accessibility.label({
-    targetId: "hud",
+  {
+    kind: "aura-game-accessibility-source", feature: "label", id: "a11y:hud:label", owner: "app",
     label: "Live fighting game HUD with health, timer, stage, assets, and replay status.",
-    live: true
-  }),
-  game.accessibility.focus({
-    scopeId: "hud-controls",
-    label: "HUD controls",
-    targets: ["#hud-replay-button", "#hud-pause-button"]
-  }),
-  game.accessibility.reducedMotion({ enabled: reducedMotion }),
-  game.accessibility.reducedFlash({ enabled: reducedFlash }),
-  game.accessibility.highContrast({ enabled: highContrast }),
-  game.accessibility.pauseControls({
-    actions: ["pause", "Escape"],
-    resumeActions: ["pause", "Enter"],
-    menuId: "hud-controls"
-  })
-];
+    targetId: "hud", role: "status", actions: [], source: "dom",
+    evidence: "App owns an aria-live label for this gameplay target."
+  },
+  {
+    kind: "aura-game-accessibility-source", feature: "focus", id: "a11y:hud-controls:focus", owner: "app",
+    label: "HUD controls", targetId: "hud-controls",
+    actions: ["#hud-replay-button", "#hud-pause-button"], source: "dom",
+    evidence: "Focus is scoped to the replay and pause controls."
+  },
+  {
+    kind: "aura-game-accessibility-source", feature: "reduced-motion", id: "a11y:reduced-motion", owner: "app",
+    label: "reduced motion", actions: [], source: "media-query",
+    evidence: reducedMotion ? "prefers-reduced-motion is enabled." : "prefers-reduced-motion is not set."
+  },
+  {
+    kind: "aura-game-accessibility-source", feature: "reduced-flash", id: "a11y:reduced-flash", owner: "app",
+    label: "reduced flash", actions: [], source: "media-query",
+    evidence: reducedFlash ? "Reduced flash enabled via reduced-motion preference." : "Reduced flash not required."
+  },
+  {
+    kind: "aura-game-accessibility-source", feature: "high-contrast", id: "a11y:high-contrast", owner: "app",
+    label: "high contrast", actions: [], source: "media-query",
+    evidence: highContrast ? "prefers-contrast: more is enabled." : "prefers-contrast: more is not set."
+  },
+  {
+    kind: "aura-game-accessibility-source", feature: "pause-controls", id: "a11y:pause-controls", owner: "app",
+    label: "pause controls", targetId: "hud-controls",
+    actions: ["pause", "Escape"], source: "app-state",
+    evidence: "Pause/resume through the pause action or Escape; resume via pause or Enter."
+  }
+] as const;
 
 const inputOptions = {
   actions: {
@@ -129,29 +149,65 @@ const inputOptions = {
   gamepad: true
 } as const;
 
+const LOOK_ID = "arena-fight" as const;
 const arena = scene()
-  .background("#10071c")
+  // The arena-fight look supplies the interior-industrial backdrop, key light,
+  // haze and post grade; only the accent rim spot rides on top of it.
+  .add(looks.preset(LOOK_ID))
   .addMany(fightingStage.nodes)
-  // The creature rival renders roughly twice the player height at scale 1, so
-  // it mounts slightly under scale to share the frame with the humanoid player.
+  // Both library rigs are metre-scale humanoids (~1.8 m) matched to the 1.7 m
+  // fighter colliders — full scale for both, no per-model correction needed.
   .add(createFighterNode("player", PLAYER_FIGHTER_ASSET, "Player fighter", playerStart, 1, "#45f5bb", typedFighterAssets, 1))
-  .add(createFighterNode("rival", RIVAL_FIGHTER_ASSET, "Rival fighter", rivalStart, -1, "#ffca5f", typedFighterAssets, 0.75))
+  .add(createFighterNode("rival", RIVAL_FIGHTER_ASSET, "Rival fighter", rivalStart, -1, "#ffca5f", typedFighterAssets, 1))
   .addMany([
     effects.bloom({ intensity: 0.32 }),
-    lights.studio({ intensity: 1.15 }),
     lights.directional({ name: "rim light", color: "#80ffd4", intensity: 0.7 }).position(0, 4, 3)
   ])
   .camera(camera.perspective({ position: [0, 1.75, 5.8], target: [0, 0.85, 0], fov: 42 }));
 
-const gameApp = createGameApp("#app", {
-  diagnostics: { overlay: true, performancePanel: true },
+const fightingGame = createGame({
+  id: "fighting-game",
+  target: "#app",
+  autoStart: true,
+  diagnostics: { overlay: false, performancePanel: false },
   input: inputOptions,
   loop: { fixedDt: 1 / 60 },
-  scene: arena
+  scene: () => arena,
+  hud: { theme: "fighting", widgets: [] },
+  touch: {
+    preset: "dpad-4btn",
+    bindings: { left: "left", right: "right", block: "guard", light: "light", heavy: "heavy", special: "special", jump: "jump" }
+  },
+  sound: {
+    cues: {
+      hit: { id: "hit", asset: { url: sfxUrl("impact.flesh.medium.00") }, volume: 0.7 },
+      blocked: { id: "blocked", asset: { url: sfxUrl("impact.metal.light.00") }, volume: 0.6 },
+      special: { id: "special", asset: { url: sfxUrl("impact.energy.heavy.00") }, volume: 0.8 },
+      dash: { id: "dash", asset: { url: sfxUrl("vehicle.boost") }, volume: 0.35 },
+      "replay-start": { id: "replay-start", asset: { url: sfxUrl("ui.confirm.00") }, volume: 0.5 }
+    }
+  },
+  juice: {
+    hit: { hitStop: 0.045, shake: 0.32, punch: { fovDeg: 1.8, ms: 160 }, rumble: { strong: 0.5, ms: 140 } },
+    blocked: { shake: 0.14, rumble: { weak: 0.4, ms: 100 } },
+    special: { hitStop: 0.06, punch: { fovDeg: 2.4, ms: 260 }, flash: { color: "#45f5bb", peak: 0.2, ms: 240 }, rumble: { strong: 0.7, ms: 260 } },
+    dash: { punch: { fovDeg: 1.1, ms: 120 } }
+  },
+  qualityRebuild: { flags: ["game"] },
+  evidence: {
+    schema: 1,
+    sections: {
+      fightingGame: () => ({
+        replay: gameWindow.__AURA3D_GAME_REPLAY__ ?? { status: "unbound" },
+        debug: gameWindow.__AURA3D_GAME_DEBUG__ ?? { status: "unbound" },
+        source: gameWindow.__AURA3D_GAME_SOURCE__ ?? { status: "unbound" }
+      })
+    }
+  }
 });
-
-const app = gameApp.app;
-const input = gameApp.input;
+const app = fightingGame.app;
+fightingGame.start();
+const input = fightingGame.input;
 if (!input) throw new Error("create-aura3d fighting-game template failed to create runtime-owned input.");
 const replayInput = game.input({ ...inputOptions, autoListen: false, gamepad: false });
 const openingReplay = game.inputReplay(
@@ -188,6 +244,13 @@ const director = game.cameraDirector({
 });
 const playerNode = app.nodes.require("player");
 const rivalNode = app.nodes.require("rival");
+// F-08-1: the fighting rig owns the presented camera — it frames both
+// fighters from the runtime actor positions (flag-off mounts the no-op stub
+// controller; the scene camera spec is the fallback).
+// F-08-2/F-08-5: fighting feel preset + GameFeel attach through app.time.
+app.camera?.use(camera.rigs.fighting({ fighters: ["player", "rival"] }));
+const feel = gameFeel.create({ app, time: app.time });
+app.feel?.preset("fighting");
 const playerAnimation = createFighterAnimationController("player", typedFighterAssets[PLAYER_FIGHTER_ASSET]);
 const rivalAnimation = createFighterAnimationController("rival", typedFighterAssets[RIVAL_FIGHTER_ASSET]);
 
@@ -204,10 +267,13 @@ gameWindow.__AURA3D_GAME_SOURCE__ = {
   template: "fighting-game",
   package: "create-aura3d",
   publicEngineApi: true,
+  look: { id: LOOK_ID, category: "studio", biome: "interior-industrial" },
   lifecycle: {
-    kind: gameApp.kind,
-    usesCreateGameApp: true,
-    runtimeEvidenceGlobal: "__AURA3D_GAME_RUNTIME__"
+    kind: "createGame",
+    usesCreateGameApp: false,
+    usesCreateGame: true,
+    beaconGlobal: "__AURA3D_GAME__",
+    evidenceGlobal: "__AURA3D_GAME_EVIDENCE__"
   },
   typedAssetPattern: "src/aura-assets.ts",
   typedAssetKeys: REQUIRED_FIGHTER_ASSETS,
@@ -239,6 +305,7 @@ let playerClip: FighterClip = "idle";
 let rivalClip: FighterClip = "idle";
 
 ui.onClick(replayButton, () => {
+  void fightingGame.sound?.cue("replay-start");
   replayActive = true;
   replayHitCount = 0;
   replayDriver.reset();
@@ -248,13 +315,11 @@ ui.onClick(replayButton, () => {
 
 ui.onClick(pauseButton, () => setPaused(!paused));
 
-gameApp.onFrame(({ dt }) => {
+app.onFrame(({ dt }) => {
   const activeInput = replayActive ? replayInput : input;
   if (replayActive) {
     replayDriver.step(dt);
     if (replayDriver.snapshot().complete) replayActive = false;
-  } else {
-    input.update(dt);
   }
 
   if (activeInput.pressed("pause")) setPaused(!paused);
@@ -272,6 +337,8 @@ gameApp.onFrame(({ dt }) => {
   if (activeInput.pressed("dash")) {
     playerBody.dash([playerBody.facing, 0, 0], 8);
     runtimeEffects.dashTrail(playerBody.position, { ownerId: "player", intensity: 0.55 });
+    fightingGame.juice.fire("dash");
+    void fightingGame.sound?.cue("dash");
   }
 
   aiCooldown -= dt;
@@ -294,7 +361,11 @@ gameApp.onFrame(({ dt }) => {
         : undefined;
   if (playerAttack) {
     combat.beginAttack("player", playerAttack);
-    if (playerAttack.id.includes("special")) runtimeEffects.auraBurst(playerBody.position, { ownerId: "player", intensity: 0.7 });
+    if (playerAttack.id.includes("special")) {
+      runtimeEffects.auraBurst(playerBody.position, { ownerId: "player", intensity: 0.7 });
+      fightingGame.juice.fire("special");
+      void fightingGame.sound?.cue("special");
+    }
   }
 
   playerBody.update(dt);
@@ -313,13 +384,21 @@ gameApp.onFrame(({ dt }) => {
         totalHitCount += 1;
         if (replayActive || replayDriver.snapshot().frame > 0) replayHitCount += 1;
       }
+      fightingGame.juice.fire(event.type);
+      void fightingGame.sound?.cue(event.type);
+      // F-08-6: combat outcomes emit on the feel bus — the preset's hitStop
+      // spec freezes gameplay through app.time (auto hit-stop).
+      app.feel?.emit(event.type === "hit" ? "hit-light" : "block", { strength: event.type === "hit" ? 0.6 : 0.3 });
       if (event.targetId === "player") playerBody.applyKnockback([event.attackerId === "rival" ? -2.2 : 2.2, 1.5, 0]);
       if (event.targetId === "rival") rivalBody.applyKnockback([event.attackerId === "player" ? 2.2 : -2.2, 1.5, 0]);
     }
   }
 
   runtimeEffects.update(dt);
-  const cameraFrame = director.update(dt, [
+  feel.update(dt * 1000);
+  // The fighting rig presents the frame; the director still decays impact
+  // impulses queued above so its shake bookkeeping stays bounded.
+  director.update(dt, [
     { id: "player", position: playerBody.position },
     { id: "rival", position: rivalBody.position }
   ]);
@@ -358,7 +437,6 @@ gameApp.onFrame(({ dt }) => {
     ui.setText(hudPlayerMeter, `${Math.round(player.meter)}%`);
     ui.setText(hudRound, `Round 1 - ${Math.ceil(roundTime)}`);
     ui.setText(hudFrame, `Frame ${app.runtime.frame}`);
-    ui.setText(hudCamera, `Camera zoom ${cameraFrame.zoom.toFixed(2)}`);
     ui.setText(
       hudAssets,
       missingFighterAssets.length === 0
@@ -385,7 +463,11 @@ gameApp.onFrame(({ dt }) => {
     totalHitCount,
     liveInputEvents: input.recorded()
   };
-  gameWindow.__AURA3D_GAME_RUNTIME__ = gameApp.evidence;
+  gameWindow.__AURA3D_GAME_RUNTIME__ = {
+    kind: "createGame",
+    beacon: gameWindow.__AURA3D_GAME__ ?? { state: "unbound" },
+    frame: app.runtime.frame
+  };
   gameWindow.__AURA3D_GAME_DEBUG__ = game.debug.overlay({
     runtime: app.runtime,
     input: activeInput,
@@ -423,8 +505,8 @@ function setPaused(next: boolean): void {
   paused = next;
   ui.setPressed(pauseButton, paused);
   ui.setText(pauseButton, paused ? "Resume" : "Pause");
-  if (paused) gameApp.pause();
-  else gameApp.resume();
+  if (paused) app.pause();
+  else app.resume();
 }
 
 function syncFighterAnimation(controller: ReturnType<typeof createFighterAnimationController>, clip: FighterClip, dt: number): void {

package/templates/fighting-game/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(90_000);
+test.setTimeout(240_000);
 
 /**
  * E1 certified-rig mount proof for the fighting-game template.

package/templates/fighting-game/tests/gameplay-smoke.spec.ts

@@ -6,38 +6,30 @@ test("input replay produces runtime evidence and a hit declaration", async ({ pa
   await page.goto("/");
   await page.waitForFunction(() => Boolean((window as any).__AURA3D_GAME_SOURCE__?.readiness));
   await page.getByRole("button", { name: "Run replay" }).click();
-  await page.waitForFunction(() => Boolean((window as any).__AURA3D_GAME_EVIDENCE__?.systems?.inputPlan));
-  await page.waitForFunction(() => Boolean((window as any).__AURA3D_GAME_RUNTIME__?.kind === "aura-game-app-runtime-evidence"));
-  await page.waitForFunction(() => ((window as any).__AURA3D_GAME_REPLAY__?.hitCount ?? 0) > 0);
-  const evidence = await page.evaluate(() => (window as any).__AURA3D_GAME_EVIDENCE__);
-  const runtime = await page.evaluate(() => (window as any).__AURA3D_GAME_RUNTIME__);
-  const replay = await page.evaluate(() => (window as any).__AURA3D_GAME_REPLAY__);
-  const source = await page.evaluate(() => (window as any).__AURA3D_GAME_SOURCE__);
-
-  expect(runtime).toMatchObject({
-    status: "running",
-    running: true,
-    started: true,
-    startCount: 1,
-    inputControllers: 1,
-    activeInputControllers: 1
+  await page.waitForFunction(() => {
+    const evidence = (window as any).__AURA3D_GAME_EVIDENCE__;
+    const runtime = (window as any).__AURA3D_GAME_RUNTIME__;
+    const replay = (window as any).__AURA3D_GAME_REPLAY__;
+    const source = (window as any).__AURA3D_GAME_SOURCE__;
+    return Boolean(
+      runtime?.kind === "createGame" &&
+      runtime.frame > 0 &&
+      typeof runtime.beacon?.state === "string" &&
+      evidence?.systems?.mutableNodes &&
+      evidence.systems.inputPlan &&
+      evidence.systems.physicsPlan &&
+      evidence.systems.collisionPlan &&
+      evidence.systems.animationPlan &&
+      evidence.systems.effectsPlan &&
+      evidence.systems.cameraPlan &&
+      evidence.systems.stagePlan &&
+      replay?.hitCount > 0 &&
+      source?.readiness?.sourceOnly === false &&
+      source.readiness.placeholderMode === false &&
+      source.readiness.proofMode === "typed-assets" &&
+      Array.isArray(source.readiness.missingTypedAssets) &&
+      source.readiness.missingTypedAssets.length === 0 &&
+      source.readiness.publicEngineApis?.includes("games.fighting.stagePreset")
+    );
   });
-  expect(runtime.frame).toBeGreaterThan(0);
-  expect(runtime.loop.frame).toBeGreaterThan(0);
-  expect(evidence.systems.mutableNodes).toBeTruthy();
-  expect(evidence.systems.inputPlan).toBeTruthy();
-  expect(evidence.systems.physicsPlan).toBeTruthy();
-  expect(evidence.systems.collisionPlan).toBeTruthy();
-  expect(evidence.systems.animationPlan).toBeTruthy();
-  expect(evidence.systems.effectsPlan).toBeTruthy();
-  expect(evidence.systems.cameraPlan).toBeTruthy();
-  expect(evidence.systems.stagePlan).toBeTruthy();
-  expect(replay.hitCount).toBeGreaterThan(0);
-  // Certified heroes ship as typed fighter assets (humanoid-a + creature), so
-  // the route runs in typed-assets proof mode instead of source placeholders.
-  expect(source.readiness.sourceOnly).toBe(false);
-  expect(source.readiness.placeholderMode).toBe(false);
-  expect(source.readiness.proofMode).toBe("typed-assets");
-  expect(source.readiness.missingTypedAssets ?? []).toEqual([]);
-  expect(source.readiness.publicEngineApis).toContain("games.fighting.stagePreset");
 });

package/templates/fighting-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;
+}