@aura3d/engine 3.0.0 → 4.0.0

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

@@ -1,14 +1,20 @@
 import {
   camera,
-  createAuraApp,
   game,
+  gameFeel,
+  looks,
   material,
   model,
-  primitives,
   scene,
-  type AuraLeanNodeBuilder,
-  type LeanPlatformerEvent
-} from "@aura3d/lean/game";
+  type AuraNodeBuilder,
+  type AuraSceneNode,
+  type GamePlatformerEvent,
+  type GamePlatformerSnapshot
+} from "@aura3d/engine";
+// PRD-09: mounted via the shared runtime — createGame owns mount/lifecycle,
+// the §7.7 tabletop HUD theme, the §6.11 dpad-2btn touch preset, game-sfx-core
+// cues, and the juice event map.
+import { createGame, sfxUrl } from "@aura3d/engine/game";
 import { assets } from "./aura-assets";
 
 declare global {
@@ -22,11 +28,26 @@ interface MiniGameEvidence {
   readonly deaths: number;
   readonly checkpointId: string;
   readonly collected: readonly string[];
+  readonly hero: { readonly assetId: string; readonly url: string };
   readonly player: { readonly x: number; readonly y: number; readonly grounded: boolean };
   readonly events: readonly string[];
-  readonly evidence: { readonly entry: string; readonly physics: string; readonly typedAssets: number };
+  readonly look: { readonly id: string; readonly category: string };
+  readonly animation: {
+    readonly clip: string;
+    readonly clips: readonly string[];
+    readonly tracksApplied: number;
+  };
+  readonly camera: {
+    readonly rig: string;
+    readonly presented: boolean;
+  };
+  readonly evidence: { readonly entry: string; readonly typedAssets: number };
 }
 
+// The look sets palette + sky + sun + fog + grade; the scene adds only the
+// foreground. Genre row (aura3d-browser-game): mini-game → outdoor-day.
+const LOOK_ID = "outdoor-day" as const;
+
 const level = {
   start: { x: 0, y: 0.35 },
   finish: { x: 12.4, y: 0.35 },
@@ -51,7 +72,12 @@ const level = {
   dashSpeed: 9.5
 };
 
-const input = game.input({
+// Side-follow framing: the camera sits 10.4 m off the play plane and tracks
+// the hero on x only (side-scroller). The C-22 rig is the live camera
+// surface; the mounted rig owns the presented pose.
+const CAMERA_OFFSET = { y: 3.45, z: 10.4, targetY: 0.47 } as const;
+
+const inputOptions = {
   actions: {
     left: ["KeyA", "ArrowLeft"],
     right: ["KeyD", "ArrowRight"],
@@ -62,24 +88,85 @@ const input = game.input({
   },
   axes: { moveX: { negative: "left", positive: "right" } },
   bufferMs: 140
-});
+} as const;
 const platformer = game.platformer(level);
 const routeEvents: string[] = [];
-const app = createAuraApp("#app", { scene: buildScene() });
+
+const miniGame = createGame({
+  id: "mini-game",
+  target: "#app",
+  autoStart: true,
+  scene: buildScene,
+  input: inputOptions,
+  hud: { theme: "tabletop", widgets: [] },
+  touch: {
+    preset: "dpad-2btn",
+    bindings: { left: "left", right: "right", dash: "dash", jump: "jump", attack: "down" }
+  },
+  sound: {
+    cues: {
+      collect: { id: "collect", asset: { url: sfxUrl("pickup.coin.00") }, volume: 0.7 },
+      checkpoint: { id: "checkpoint", asset: { url: sfxUrl("stinger.checkpoint.00") }, volume: 0.7 },
+      complete: { id: "complete", asset: { url: sfxUrl("stinger.win.00") }, volume: 0.8 },
+      hazard: { id: "hazard", asset: { url: sfxUrl("impact.rubber-ball.heavy.00") }, volume: 0.7 },
+      land: { id: "land", asset: { url: sfxUrl("impact.rubber-ball.light.00") }, volume: 0.35 },
+      jump: { id: "jump", asset: { url: sfxUrl("ui.toggle.00") }, volume: 0.4 }
+    }
+  },
+  juice: {
+    collect: { punch: { fovDeg: 1.2, ms: 140 }, flash: { color: "#f7d76b", peak: 0.12, ms: 160 } },
+    checkpoint: { punch: { fovDeg: 1.6, ms: 200 }, flash: { color: "#9df59e", peak: 0.16, ms: 220 } },
+    complete: { hitStop: 0.06, punch: { fovDeg: 2.4, ms: 360 }, rumble: { strong: 0.7, ms: 320 } },
+    hazard: { shake: 0.45, hitStop: 0.04, flash: { color: "#f06b7a", peak: 0.28, ms: 240 }, rumble: { strong: 0.5, ms: 200 } },
+    land: { shake: 0.12 },
+    jump: {}
+  },
+  qualityRebuild: { flags: ["game"] },
+  evidence: {
+    schema: 1,
+    sections: { miniGame: () => window.__AURA3D_MINI_GAME__ ?? { status: "unbound" } }
+  }
+});
+const app = miniGame.app;
+miniGame.start();
+const input = miniGame.input;
+if (!input) throw new Error("create-aura3d mini-game failed to create runtime-owned input.");
+
 const player = app.nodes.require("mini-player");
 const lift = app.nodes.require("platform-lift");
 const coins = level.collectibles.map((coin) => [coin.id, app.nodes.require(`coin-${coin.id}`)] as const);
 const checkpoint = app.nodes.require("checkpoint-mid");
 const goal = app.nodes.require("goal");
 const hudRoot = createHud();
-let objective = "Collect coins, avoid spikes, reach the goal";
+let objective = "Collect stars, avoid the hazard, reach the gate";
+// Locomotion states map onto the KayKit barbarian's clip names (the
+// catalog hero's literal clip ids are replaced by the library rig's).
+const LOCOMOTION_CLIPS = {
+  idle: "Idle",
+  walk: "Walking_A",
+  sprint: "Running_A",
+  jump: "Jump_Start",
+  fall: "Jump_Idle"
+} as const;
+type LocomotionState = keyof typeof LOCOMOTION_CLIPS;
+let activeClip: LocomotionState = "idle";
+player.play(LOCOMOTION_CLIPS.idle);
 
-app.onFrame((dt) => {
-  input.update(dt);
+// Mount the C-22 camera surface (stub controller flag-off, real under PRD 08).
+// F-08-1: the follow2d rig owns the presented camera (flag-off mounts the
+// no-op stub controller, so the scene's camera.follow spec stays the
+// fallback). F-08-5: feel bus + GameFeel attach through app.time.
+app.camera?.use(
+  camera.rigs.follow2d({ target: "mini-player", framing: { subjectHeightFraction: 0.28 } })
+);
+const feel = gameFeel.create({ app, time: app.time });
+app.feel?.preset("platformer");
+
+app.onFrame(({ dt }) => {
   if (input.pressed("reset")) {
     platformer.reset();
     routeEvents.push("reset:Route reset");
-    objective = "Collect coins, avoid spikes, reach the goal";
+    objective = "Collect stars, avoid the hazard, reach the gate";
   }
   const moveX = input.axis("moveX");
   const jumpPressed = input.buffered("jump");
@@ -96,26 +183,38 @@ app.onFrame((dt) => {
       dashPressed: firstSubstep && dashPressed,
       fastFall: input.held("down")
     });
-    for (const event of state.events) updateObjective(event);
+    for (const event of state.events) {
+      updateObjective(event);
+      if (event.type === "collect" || event.type === "checkpoint" || event.type === "complete" || event.type === "hazard" || event.type === "land") {
+        miniGame.juice.fire(event.type);
+        void miniGame.sound?.cue(event.type);
+      }
+      if (event.type === "jump") void miniGame.sound?.cue("jump");
+    }
     remaining -= substep;
     firstSubstep = false;
   } while (remaining > 0.000_001);
 
-  player.setPosition(state.player.x + 0.38, state.player.y + 0.5, 0);
+  // The KayKit barbarian hero is feet-origin (GLB min y = 0), so the visual
+  // rides at the physics point instead of a +0.5 lift.
+  player.setPosition(state.player.x + 0.38, state.player.y + 0.01, 0);
+  player.setRotation(0, state.player.facing === 1 ? Math.PI / 2 : -Math.PI / 2, 0);
+  playLocomotionClip(state);
   lift.setPosition(level.movingPlatforms[0].x + level.movingPlatforms[0].width / 2, movingLiftY(state.time), 0);
   for (const [id, node] of coins) node.setVisible(!state.collected.includes(id));
   checkpoint.setVisible(!state.activatedCheckpoints.includes("mid"));
-  goal.setScale(state.status === "completed" ? [0.28, 1.08, 0.18] : [0.22, 0.92, 0.16]);
+  goal.setScale(state.status === "completed" ? [1.35, 1.35, 1.35] : 1);
+  feel.update(dt * 1000);
   renderHud(state);
   publishEvidence(state);
 });
 
 publishEvidence(platformer.snapshot());
 renderHud(platformer.snapshot());
-void app.ready().then(() => {
+void miniGame.ready().then(() => {
   const diagnostics = app.diagnostics();
   document.body.dataset.aura3dReady = "true";
-  document.body.dataset.aura3dRuntimeBackend = diagnostics.runtimeBackend;
+  document.body.dataset.aura3dRuntimeBackend = diagnostics.backend;
   document.body.dataset.aura3dDrawCalls = String(diagnostics.drawCalls);
   (window as unknown as { __AURA3D_ROUTE_READY__?: unknown }).__AURA3D_ROUTE_READY__ = { ready: true, diagnostics };
 }).catch((error: unknown) => {
@@ -123,29 +222,85 @@ void app.ready().then(() => {
 });
 
 function buildScene() {
-  const nodes: AuraLeanNodeBuilder[] = [
-    ...level.platforms.map((platform) => primitives.box({ name: `${platform.id} platform`, material: material.pbr({ color: "#62d8ef", roughness: 0.28 }) })
-      .position(platform.x + platform.width / 2, platform.y + platform.height / 2, -0.05).scale([platform.width, platform.height, 0.22])),
-    primitives.box({ name: "moving lift platform", material: material.pbr({ color: "#b5f77d", roughness: 0.24 }) })
-      .position(level.movingPlatforms[0].x + level.movingPlatforms[0].width / 2, movingLiftY(0), 0)
-      .scale([level.movingPlatforms[0].width, level.movingPlatforms[0].height, 0.22]).runtime("platform-lift"),
-    ...level.collectibles.map((coin) => primitives.sphere({ name: `${coin.id} collectible`, material: material.pbr({ color: "#f7d76b", metallic: 0.35, roughness: 0.22 }) })
-      .position(coin.x, coin.y, 0.02).scale(0.18).runtime(`coin-${coin.id}`)),
-    primitives.box({ name: "hazard spikes", material: material.pbr({ color: "#f06b7a", roughness: 0.2 }) })
-      .position(level.hazards[0].x + level.hazards[0].width / 2, level.hazards[0].y + level.hazards[0].height / 2, 0.05)
-      .scale([level.hazards[0].width, level.hazards[0].height, 0.2]),
-    primitives.box({ name: "checkpoint marker", material: material.pbr({ color: "#9df59e", roughness: 0.2 }) })
-      .position(level.checkpoints[0].x, level.checkpoints[0].y + 0.42, 0.08).scale([0.14, 0.85, 0.14]).runtime("checkpoint-mid"),
-    primitives.box({ name: "finish portal", material: material.pbr({ color: "#ffad57", metallic: 0.2, roughness: 0.18 }) })
-      .position(level.finish.x, level.finish.y + 0.7, 0.08).scale([0.22, 0.92, 0.16]).runtime("goal")
+  // Platform geometry comes from the library crate (PRD 05 template-starters
+  // swap, #481 mapping); the 0.824 m cube scales to each collision rect.
+  const block = assets.quaterniusCrate;
+  const BLOCK_SIZE = assets.quaterniusCrate.bounds;
+  const blockScale = (width: number, height: number, depth: number) =>
+    [width / BLOCK_SIZE[0], height / BLOCK_SIZE[1], depth / BLOCK_SIZE[2]] as const;
+  const nodes: AuraNodeBuilder<AuraSceneNode>[] = [
+    ...level.platforms.map((platform) =>
+      model(block, { name: `${platform.id} platform` })
+        .position(platform.x + platform.width / 2, platform.y, -0.05)
+        .scale(blockScale(platform.width, platform.height, 1.24))),
+    ...level.movingPlatforms.map((platform) =>
+      model(assets.quaterniusCubeCrate, { name: `${platform.id} moving platform` })
+        .position(platform.x + platform.width / 2, movingLiftY(0) - platform.height / 2, 0)
+        .scale([platform.width / assets.quaterniusCubeCrate.bounds[0], platform.height / assets.quaterniusCubeCrate.bounds[1], 0.7])
+        .runtime(game.runtimeNode("platform-lift", { tags: ["platform", "moving"] }))),
+    // Stars are models, not primitives: emissive 3–5 reads as coin sparkle
+    // under the daylight-outdoor grade.
+    ...level.collectibles.map((coin) =>
+      model(assets.kenneyPlatformerKitStar, {
+        name: `${coin.id} collectible`,
+        material: material.emissive({ color: "#ffd54d", emissive: "#ffd54d", emissiveIntensity: 4, roughness: 0.3 })
+      })
+        .position(coin.x, coin.y, 0.02)
+        .scale(1.15)
+        .runtime(game.runtimeNode(`coin-${coin.id}`, { tags: ["collectible"] }))),
+    model(assets.quaterniusCubeCrate, {
+      name: "spikes hazard",
+      material: material.emissive({ color: "#e5484d", emissive: "#e5484d", emissiveIntensity: 0.9, roughness: 0.4 })
+    })
+      .position(level.hazards[0].x + level.hazards[0].width / 2, level.hazards[0].y, 0.05)
+      .scale([level.hazards[0].width / assets.quaterniusCubeCrate.bounds[0], level.hazards[0].height / assets.quaterniusCubeCrate.bounds[1], 0.5]),
+    model(assets.kenneyPlatformerKitKey, { name: "checkpoint key" })
+      .position(level.checkpoints[0].x, level.checkpoints[0].y + 0.2, 0.08)
+      .scale(2)
+      .runtime(game.runtimeNode("checkpoint-mid", { tags: ["checkpoint"] })),
+    model(assets.kenneyPlatformerKitStar, {
+      name: "finish gate",
+      material: material.emissive({ color: "#ffd54d", emissive: "#ffd54d", emissiveIntensity: 3, roughness: 0.3 })
+    })
+      .position(level.finish.x, level.finish.y + 0.5, 0.08)
+      .scale(3.4)
+      .runtime(game.runtimeNode("goal", { tags: ["finish"] }))
   ];
-  return scene().background("#071015")
-    .add(model(assets.playerModel, { name: "typed mini-game player" }).position(level.start.x + 0.38, level.start.y + 0.5, 0).scale(0.28).runtime("mini-player"))
+  // The scene-level follow spec frames the hero today; the C-22 rig (mounted
+  // above build) owns presented camera state once PRD 08 lands.
+  return scene()
+    .add(looks.preset(LOOK_ID))
+    .add(
+      model(assets.kaykitBarbarian, { name: "certified hero" })
+        .position(level.start.x + 0.38, level.start.y + 0.01, 0)
+        // Barbarian is 2.4 m tall vs the 0.9 m hero the level was tuned for.
+        .scale(0.91 / assets.kaykitBarbarian.bounds[1])
+        .runtime(game.runtimeNode("mini-player", { tags: ["player"] }))
+    )
     .addMany(nodes)
-    .camera(camera.perspective({ position: [6.1, 3.8, 10.4], target: [6.1, 0.82, 0], fov: 46 }));
+    .camera(
+      camera.follow({
+        targetNode: "mini-player",
+        position: [level.start.x, level.start.y + CAMERA_OFFSET.y, CAMERA_OFFSET.z],
+        target: [level.start.x, level.start.y + CAMERA_OFFSET.targetY, 0],
+        fov: 50
+      })
+    );
+}
+
+function playLocomotionClip(state: GamePlatformerSnapshot): void {
+  // C-19 stub surface: `play` switches clips immediately (`crossFadeTo` is the
+  // PRD 06 blend path on the same handle when it lands).
+  const next: LocomotionState = !state.player.grounded
+    ? state.player.vy > 0 ? "jump" : "fall"
+    : Math.abs(state.player.vx) > level.dashSpeed * 0.7 ? "sprint"
+      : Math.abs(state.player.vx) > 0.4 ? "walk" : "idle";
+  if (next === activeClip) return;
+  activeClip = next;
+  player.play(LOCOMOTION_CLIPS[next]);
 }
 
-function updateObjective(event: LeanPlatformerEvent): void {
+function updateObjective(event: GamePlatformerEvent): void {
   routeEvents.push(event.id ? `${event.type}:${event.id}` : event.type);
   if (routeEvents.length > 16) routeEvents.shift();
   if (event.type === "checkpoint") objective = "Checkpoint reached. Finish the route.";
@@ -161,16 +316,17 @@ function movingLiftY(time: number): number {
 function createHud(): HTMLElement {
   const root = document.createElement("aside");
   root.id = "mini-game-hud";
-  root.style.cssText = "position:absolute;left:16px;top:16px;z-index:5;min-width:260px;font:600 13px/1.35 Inter,system-ui,sans-serif;color:#f5fbff;background:rgba(3,9,14,.78);border:1px solid rgba(125,220,235,.34);border-radius:8px;padding:12px;pointer-events:none";
+  root.style.cssText = "position:absolute;left:16px;top:16px;z-index:5;min-width:260px;font:600 13px/1.35 Inter,system-ui,sans-serif;color:#f5fbff;background:rgba(6,18,26,.66);border:1px solid rgba(160,210,240,.34);border-radius:8px;padding:12px;pointer-events:none";
   document.body.append(root);
   return root;
 }
 
-function renderHud(state: ReturnType<typeof platformer.snapshot>): void {
+function renderHud(state: GamePlatformerSnapshot): void {
   hudRoot.innerHTML = `<strong>Aura3D Mini Game</strong><div>Score ${state.score} | Lives ${state.lives} | Deaths ${state.deaths}</div><div>Checkpoint ${state.checkpointId}</div><div>${objective}</div><div>Move A/D or arrows. Jump Space. Dash Shift. Reset R.</div>`;
 }
 
-function publishEvidence(state: ReturnType<typeof platformer.snapshot>): void {
+function publishEvidence(state: GamePlatformerSnapshot): void {
+  const animation = player.importedAssetEvidence();
   window.__AURA3D_MINI_GAME__ = {
     status: state.status,
     frame: state.frame,
@@ -178,8 +334,20 @@ function publishEvidence(state: ReturnType<typeof platformer.snapshot>): void {
     deaths: state.deaths,
     checkpointId: state.checkpointId,
     collected: state.collected,
+    hero: { assetId: assets.kaykitBarbarian.id, url: assets.kaykitBarbarian.url },
     player: { x: state.player.x, y: state.player.y, grounded: state.player.grounded },
     events: [...routeEvents],
-    evidence: { entry: "@aura3d/lean/game", physics: "solver-free deterministic arcade", typedAssets: Object.keys(assets).length }
+    look: { id: LOOK_ID, category: looks.describe(LOOK_ID).category },
+    animation: {
+      clip: activeClip,
+      clips: animation?.clips ?? [],
+      // Report-only while the C-19 handle is a stub (T3.1 test reads it).
+      tracksApplied: animation?.lastMaterialTracksApplied ?? 0
+    },
+    camera: {
+      rig: app.camera?.rig.id ?? "scene-follow",
+      presented: app.camera !== undefined
+    },
+    evidence: { entry: "@aura3d/engine/game createGame", typedAssets: Object.keys(assets).length }
   };
 }

package/templates/mini-game/tests/certified-rig.spec.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(240_000);
+
+/**
+ * E1 certified-rig mount proof for the mini-game template.
+ *
+ * The template hero must be one of the E1-certified hero rigs
+ * (docs/rendering/skinning-and-morphs.md "Certified hero rigs") — currently
+ * the vehicle-driver slot: showcaseKenneyOobiPlatformerHero / "walk".
+ * The mounted asset id AND url assert against that roster; a fixture swap
+ * regresses this spec instead of silently shipping an uncertified hero.
+ *
+ * No raw GLB URL literal lives in this file (public-example-boundary): the
+ * expected url is read from the template's own generated typed assets.
+ */
+const CERTIFIED_ROSTER = ["showcaseKenneyOobiPlatformerHero"] as const;
+function certifiedHeroFromTypedAssets(): { assetId: string; url: string } {
+  const source = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "src", "aura-assets.ts"), "utf8");
+  for (const assetId of CERTIFIED_ROSTER) {
+    const pattern = new RegExp(`${assetId}:[\\s\\S]*?url:\\s*"([^"]+)"`);
+    const match = pattern.exec(source);
+    if (match?.[1]) return { assetId, url: match[1] };
+  }
+  throw new Error(`no certified-roster hero declared in the template typed assets (roster: ${CERTIFIED_ROSTER.join(", ")})`);
+}
+const CERTIFIED_HERO = certifiedHeroFromTypedAssets();
+
+test("mini-game hero mounts the certified vehicle-driver rig", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 150_000 }).toBe("true");
+  const hero = await page.evaluate(
+    () => (window as unknown as { readonly __AURA3D_MINI_GAME__?: { readonly hero?: { readonly assetId?: string; readonly url?: string } } }).__AURA3D_MINI_GAME__?.hero
+  );
+  expect(hero?.assetId).toBe(CERTIFIED_HERO.assetId);
+  expect(hero?.url).toBe(CERTIFIED_HERO.url);
+});

package/templates/mini-game/tests/look-floor.ts

@@ -0,0 +1,270 @@
+/**
+ * PRD-13 T3.12/T3.13 — the shared template look floor.
+ *
+ * Every create-aura3d template's `tests/screenshot.spec.ts` calls
+ * `assertTemplateLookFloor(page, ...)` after readiness: the same five checks
+ * everywhere (PRD §6.5/T3.12):
+ *
+ *   1. non-blank — sampled WebGL pixels are lit and varied (not a uniform
+ *      clear/void frame);
+ *   2. `diagnostics().look.lint` carries no `severity === "error"` finding
+ *      (empty when A3D_QR_LOOKS is off — the check never silently skips);
+ *   3. `appliedLook.environment.specularIntensity > 0` — an environment map
+ *      actually reached the frame;
+ *   4. `appliedLook.shadows.strength >= 0.8` when the look declares a shadow
+ *      caster (a null ShadowReport means the renderer produced no shadow
+ *      evidence — recorded, not failed);
+ *   5. `appliedLook.pixelRatio >= min(devicePixelRatio, tierCap)` — the
+ *      renderer used the display density up to the tier cap (2).
+ *
+ * …plus the optional §T3.12 subject check: the lit-pixel bounding box of the
+ * canvas' central region must sit within `tolerance` of the expected subject
+ * bounds (default ±10% of frame).
+ *
+ * Templates that mount through `createAuraApp` surface `appliedLook`/`look`
+ * via the global `__AURA3D_LIVE_APPS__` registry — no per-template wiring.
+ * `skipAppDiagnostics` covers the bespoke-renderer template (animation-studio),
+ * which reports its stage environment through its own readiness evidence.
+ */
+
+import { expect, type Page } from "@playwright/test";
+
+/** Normalized canvas-space bounds the lit subject mass is expected to occupy. */
+export interface LookFloorSubjectBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface LookFloorOptions {
+  /** Expected subject bounds in normalized canvas units. Omit to skip. */
+  readonly subject?: LookFloorSubjectBounds;
+  /** Fractional tolerance on each bound axis. Default 0.1 (±10%). */
+  readonly tolerance?: number;
+  /** Template has no `__AURA3D_LIVE_APPS__` app (bespoke renderer). */
+  readonly skipAppDiagnostics?: boolean;
+}
+
+export interface LookFloorReport {
+  readonly sampledPixels: number;
+  readonly brightPixels: number;
+  readonly uniqueBuckets: number;
+  readonly subjectBounds: LookFloorSubjectBounds | null;
+  readonly appliedLook: {
+    readonly specularIntensity: number;
+    readonly shadowStrength: number | null;
+    readonly pixelRatio: number;
+    readonly renderPath: string;
+    readonly background: string | null;
+  } | null;
+  readonly lookLintErrors: readonly string[];
+  readonly devicePixelRatio: number;
+}
+
+const MIN_BRIGHT_FRACTION = 0.02;
+const MIN_UNIQUE_BUCKETS = 8;
+
+export async function assertTemplateLookFloor(page: Page, options: LookFloorOptions = {}): Promise<LookFloorReport> {
+  const canvas = page.locator("canvas").first();
+  await expect(canvas).toBeVisible();
+
+  /*
+   * Deterministic frame before profiling: pause every live app, rewind its
+   * runtime clock and step a fixed 45 frames at 1/60 — through `stepAsync`,
+   * not the synchronous registry `settle()`. The production renderer mounts
+   * asynchronously, so a sync step loop renders nothing while the mount is in
+   * flight and never yields for it to finish (the failure mode on software-GL
+   * runners: blank frames, `environment.intensity` still NaN in diagnostics).
+   * Awaiting each step also lets pending environment/IBL/asset promises resolve
+   * between frames, and one final dt=0 step re-renders the same simulated
+   * instant once that work has applied.
+   */
+  const report = await page.evaluate(async (): Promise<LookFloorReport> => {
+    interface LiveApp {
+      pause?: () => void;
+      resetRuntimeClock?: () => void;
+      step?: (dt?: number) => void;
+      stepAsync?: (dt?: number) => Promise<unknown>;
+      diagnostics?: () => Record<string, unknown>;
+    }
+    const empty = (code: string): LookFloorReport => ({
+      sampledPixels: 0,
+      brightPixels: 0,
+      uniqueBuckets: 0,
+      subjectBounds: null,
+      appliedLook: null,
+      lookLintErrors: [code],
+      devicePixelRatio: globalThis.devicePixelRatio ?? 1
+    });
+    const registry = (globalThis as { __AURA3D_LIVE_APPS__?: { all?: () => readonly LiveApp[] } }).__AURA3D_LIVE_APPS__;
+    const apps = [...(registry?.all?.() ?? [])];
+    const stepApp = async (app: LiveApp, dt: number): Promise<void> => {
+      if (app.stepAsync) {
+        try {
+          await Promise.race([
+            app.stepAsync(dt),
+            new Promise((resolvePromise) => setTimeout(resolvePromise, 30_000))
+          ]);
+          return;
+        } catch {
+          // synchronous step fallback below
+        }
+      }
+      app.step?.(dt);
+    };
+    /*
+     * Wall-clock bound on the settle loop: on software-GL CI runners a single
+     * stepped render of a heavy scene costs several seconds, so an unbounded
+     * 45-step loop outlives the test budget and fails with a bare timeout and
+     * no report. Cap the stepping and always take the dt=0 settle frame — a
+     * partially settled scene still yields a readable floor report.
+     */
+    const STEP_WALLCLOCK_BUDGET_MS = 420_000;
+    const settleStartedAt = Date.now();
+    for (const app of apps) {
+      app.pause?.();
+      app.resetRuntimeClock?.();
+      for (let index = 0; index < 45; index += 1) {
+        if (Date.now() - settleStartedAt > STEP_WALLCLOCK_BUDGET_MS) break;
+        await stepApp(app, 1 / 60);
+      }
+      await stepApp(app, 0);
+    }
+    /*
+     * Renderers outside the liveApps registry (bespoke renderers, e.g.
+     * animation-studio's A3DRenderer) cannot be stepped. Two animation
+     * frames guarantee at least one full app render finished inside this
+     * evaluate task, so the readPixels below sees a real presented frame
+     * instead of a compositor-cleared buffer.
+     */
+    if (apps.length === 0) {
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+      });
+    }
+
+    const diagnostics = apps[0]?.diagnostics?.() as
+      | { appliedLook?: { environment?: { specularIntensity?: number; background?: string }; shadows?: { strength?: number | null } | null; pixelRatio?: number; renderPath?: string }; look?: { lint?: readonly { severity?: string; code?: string }[] } }
+      | undefined;
+    const appliedLook = diagnostics?.appliedLook
+      ? {
+          specularIntensity: diagnostics.appliedLook.environment?.specularIntensity ?? 0,
+          shadowStrength: diagnostics.appliedLook.shadows?.strength ?? null,
+          pixelRatio: diagnostics.appliedLook.pixelRatio ?? 0,
+          renderPath: diagnostics.appliedLook.renderPath ?? "unknown",
+          background: diagnostics.appliedLook.environment?.background ?? null
+        }
+      : null;
+    const lookLintErrors = (diagnostics?.look?.lint ?? [])
+      .filter((finding) => finding.severity === "error")
+      .map((finding) => finding.code ?? "unknown");
+    const devicePixelRatio = globalThis.devicePixelRatio ?? 1;
+
+    /*
+     * The app's WebGL context is not preserveDrawingBuffer, so readPixels must
+     * run in the same task as the stepped render, before compositing clears the
+     * drawing buffer. That also removes the composited element screenshot that
+     * software-GL runners could not produce inside a test timeout.
+     */
+    const target = [...document.querySelectorAll("canvas")]
+      .map((element) => ({
+        element,
+        gl: (element.getContext("webgl2") ?? element.getContext("webgl")) as WebGL2RenderingContext | WebGLRenderingContext | null
+      }))
+      .find((entry) => entry.gl !== null);
+    if (!target?.gl) return { ...empty("no-webgl-context"), appliedLook, lookLintErrors };
+    const gl = target.gl;
+    const width = gl.drawingBufferWidth;
+    const height = gl.drawingBufferHeight;
+    if (width === 0 || height === 0) return { ...empty("empty-drawing-buffer"), appliedLook, lookLintErrors };
+    // readPixels reads the currently bound framebuffer: renderers that end a
+    // frame with an offscreen target bound (shadow/post FBOs — e.g.
+    // animation-studio's bespoke renderer) would return that target's pixels
+    // instead of the canvas backbuffer. Rebind the default framebuffer first;
+    // every renderer rebinds its own targets at the start of its next frame.
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    const pixels = new Uint8Array(width * height * 4);
+    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+
+    const BRIGHT_LUMA = 48;
+    const stride = 4; // pixels — 16×16 sample grid
+    let sampled = 0;
+    let bright = 0;
+    const buckets = new Set<number>();
+    // Central-region lit-pixel bbox: edges carry floor/backdrop, the subject
+    // mass is what every §6.4 template frames mid-frame.
+    const x0 = Math.floor(width * 0.1);
+    const x1 = Math.floor(width * 0.9);
+    const y0 = Math.floor(height * 0.1);
+    const y1 = Math.floor(height * 0.9);
+    let minX = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (let y = 0; y < height; y += stride) {
+      for (let x = 0; x < width; x += stride) {
+        const offset = (y * width + x) * 4;
+        const r = pixels[offset] ?? 0;
+        const g = pixels[offset + 1] ?? 0;
+        const b = pixels[offset + 2] ?? 0;
+        sampled += 1;
+        buckets.add(((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4));
+        const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+        if (luma > BRIGHT_LUMA) {
+          bright += 1;
+          if (x >= x0 && x <= x1 && y >= y0 && y <= y1) {
+            minX = Math.min(minX, x);
+            maxX = Math.max(maxX, x);
+            minY = Math.min(minY, y);
+            maxY = Math.max(maxY, y);
+          }
+        }
+      }
+    }
+    // readPixels rows run bottom-up; report `y` in the same top-down
+    // convention the composited-screenshot path produced so stored
+    // expectations stay comparable across the switch.
+    const subjectBounds = Number.isFinite(minX)
+      ? { x: minX / width, y: 1 - maxY / height, width: (maxX - minX) / width, height: (maxY - minY) / height }
+      : null;
+
+    return {
+      sampledPixels: sampled,
+      brightPixels: bright,
+      uniqueBuckets: buckets.size,
+      subjectBounds,
+      appliedLook,
+      lookLintErrors,
+      devicePixelRatio
+    };
+  });
+
+  // 1. Non-blank.
+  expect(report.brightPixels / Math.max(1, report.sampledPixels)).toBeGreaterThan(MIN_BRIGHT_FRACTION);
+  expect(report.uniqueBuckets).toBeGreaterThan(MIN_UNIQUE_BUCKETS);
+
+  if (!options.skipAppDiagnostics) {
+    // 2–5. Renderer/look evidence via __AURA3D_LIVE_APPS__.
+    expect(report.appliedLook, "appliedLook diagnostics missing — is the app mounted via createAuraApp?").not.toBeNull();
+    expect(report.lookLintErrors).toEqual([]);
+      expect(report.appliedLook!.specularIntensity).toBeGreaterThan(0);
+    if (report.appliedLook!.shadowStrength !== null) {
+      expect(report.appliedLook!.shadowStrength!).toBeGreaterThanOrEqual(0.8);
+    }
+    expect(report.appliedLook!.pixelRatio).toBeGreaterThanOrEqual(Math.min(report.devicePixelRatio, 2));
+  }
+
+  // 6. Subject bounds ±10%.
+  if (options.subject) {
+    const tolerance = options.tolerance ?? 0.1;
+    const measured = `measured ${JSON.stringify(report.subjectBounds)}`;
+    expect(report.subjectBounds, "no lit subject mass in the central frame").not.toBeNull();
+    expect(Math.abs(report.subjectBounds!.x - options.subject.x), measured).toBeLessThanOrEqual(tolerance);
+    expect(Math.abs(report.subjectBounds!.y - options.subject.y), measured).toBeLessThanOrEqual(tolerance);
+    expect(Math.abs(report.subjectBounds!.width - options.subject.width), measured).toBeLessThanOrEqual(tolerance);
+    expect(Math.abs(report.subjectBounds!.height - options.subject.height), measured).toBeLessThanOrEqual(tolerance);
+  }
+
+  return report;
+}