@aura3d/engine 3.0.0 → 4.0.0

package/dist/game/shell/transition.js

@@ -0,0 +1,50 @@
+/** rAF-timed driver over the overlay element's `opacity` style. */
+export function domTransitionDriver(overlay, deps) {
+    return {
+        setOverlay(opacity, ms, color) {
+            // ms 0 must cancel a running fade: a 0 ms duration with the same end
+            // value leaves the running CSS transition untouched (CSS Transitions
+            // §3), while `none` cancels it and applies the value at once.
+            overlay.style.transition = ms > 0 ? `opacity ${ms}ms linear` : "none";
+            overlay.style.opacity = String(opacity);
+            if (color)
+                overlay.style.background = color;
+            overlay.classList.toggle("a3g-overlay-opaque", opacity > 0);
+        },
+        firstPresentedFrame: deps.firstPresentedFrame,
+        sleep: deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)))
+    };
+}
+const FIRST_PRESENTED_TIMEOUT_MS = 2000;
+export async function runTransition(driver, run, spec) {
+    const kind = spec?.kind ?? "fade";
+    if (kind === "cut")
+        return run();
+    const outMs = spec?.ms ?? 180;
+    const inMs = Math.round(outMs * 1.22); // §6.2 default 180 out / 220 in
+    driver.setOverlay(1, outMs, spec?.color);
+    await driver.sleep(outMs);
+    // The CSS fade can lag its timer on a loaded main thread (L4 run 38187300912
+    // swapped the scene at opacity 0.9724). Snap to fully opaque before the
+    // swap so the remount gap is never visible.
+    driver.setOverlay(1, 0, spec?.color);
+    // Present one more old-scene frame under the snapped, fully opaque overlay:
+    // the frame that ran in the same tick as the timer was composed before it.
+    await driver.sleep(0);
+    const result = await run();
+    // firstPresentedFrame only resolves for `frame.source === "raf"` frames —
+    // under a stepper/offscreen present it would hang forever with the overlay
+    // opaque. Bound the wait, then fail visibly with the overlay released.
+    const presented = await Promise.race([
+        driver.firstPresentedFrame().then(() => "presented"),
+        driver.sleep(FIRST_PRESENTED_TIMEOUT_MS).then(() => "timeout")
+    ]);
+    if (presented === "timeout") {
+        driver.setOverlay(0, inMs);
+        throw new Error(`A3D_TRANSITION_NO_PRESENTED_FRAME: firstPresentedFrame() did not resolve within ${FIRST_PRESENTED_TIMEOUT_MS}ms; overlay released.`);
+    }
+    driver.setOverlay(0, inMs);
+    await driver.sleep(inMs);
+    return result;
+}
+//# sourceMappingURL=transition.js.map

package/dist/game/shell/transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition.js","sourceRoot":"","sources":["../../../../../packages/game/src/shell/transition.ts"],"names":[],"mappings":"AAuBA,mEAAmE;AACnE,MAAM,UAAU,mBAAmB,CACjC,OAAmB,EACnB,IAGC;IAED,OAAO;QACL,UAAU,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK;YAC3B,qEAAqE;YACrE,qEAAqE;YACrE,8DAA8D;YAC9D,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC;YACtE,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;YACxC,IAAI,KAAK;gBAAE,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC;YAC5C,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,oBAAoB,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;QAC9D,CAAC;QACD,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;QAC7C,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;KACrE,CAAC;AACJ,CAAC;AAED,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAExC,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAwB,EACxB,GAAyB,EACzB,IAAqB;IAErB,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI,IAAI,MAAM,CAAC;IAClC,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,GAAG,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,EAAE,EAAE,IAAI,GAAG,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,gCAAgC;IACvE,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACzC,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1B,6EAA6E;IAC7E,wEAAwE;IACxE,4CAA4C;IAC5C,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACrC,4EAA4E;IAC5E,2EAA2E;IAC3E,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC;IAC3B,0EAA0E;IAC1E,2EAA2E;IAC3E,uEAAuE;IACvE,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;QACnC,MAAM,CAAC,mBAAmB,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,WAAoB,CAAC;QAC7D,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAkB,CAAC;KACxE,CAAC,CAAC;IACH,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,mFAAmF,0BAA0B,uBAAuB,CACrI,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3B,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/game/styles/hud-base.css

@@ -0,0 +1,52 @@
+/* a3g-hud layout (PRD-09 1758): 3x3 anchored slot grid, safe-area padded.
+   All visual theming is via --a3g-* custom properties (see themes/*.css). */
+.a3g-hud { position: absolute; inset: 0; pointer-events: none; z-index: 40;
+  font-family: var(--a3g-font, system-ui, sans-serif); color: var(--a3g-fg, #eee);
+  display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: 1fr 1fr 1fr;
+  padding: calc(8px + env(safe-area-inset-top,0px)) calc(8px + env(safe-area-inset-right,0px))
+           calc(8px + env(safe-area-inset-bottom,0px)) calc(8px + env(safe-area-inset-left,0px)); }
+.a3g-hud.a3g-hidden { display: none; }
+.a3g-hud-slot { display: flex; gap: 6px; min-width: 0; min-height: 0; }
+.a3g-a-top-left { grid-area: 1/1; flex-direction: column; align-items: flex-start; }
+.a3g-a-top { grid-area: 1/2; flex-direction: column; align-items: center; }
+.a3g-a-top-right { grid-area: 1/3; flex-direction: column; align-items: flex-end; }
+.a3g-a-left { grid-area: 2/1; flex-direction: column; justify-content: center; align-items: flex-start; }
+.a3g-a-center { grid-area: 2/2; flex-direction: column; justify-content: center; align-items: center; }
+.a3g-a-right { grid-area: 2/3; flex-direction: column; justify-content: center; align-items: flex-end; }
+.a3g-a-bottom-left { grid-area: 3/1; flex-direction: column; justify-content: flex-end; align-items: flex-start; }
+.a3g-a-bottom { grid-area: 3/2; flex-direction: column; justify-content: flex-end; align-items: center; }
+.a3g-a-bottom-right { grid-area: 3/3; flex-direction: column; justify-content: flex-end; align-items: flex-end; }
+.a3g-w { background: var(--a3g-bg); border: 1px solid var(--a3g-edge); border-radius: var(--a3g-radius);
+  padding: 4px 10px; box-shadow: var(--a3g-glow); font-size: 15px; line-height: 1.2; white-space: nowrap; }
+.a3g-w.a3g-hidden { display: none; }
+.a3g-w-label { display: block; font-size: 10px; letter-spacing: .08em; text-transform: uppercase;
+  color: var(--a3g-fg-dim); }
+.a3g-w-value { font-weight: 700; font-variant-numeric: tabular-nums; }
+.a3g-w-value.a3g-warn { color: var(--a3g-warn); }
+.a3g-w-unit { font-size: 10px; color: var(--a3g-fg-dim); margin-left: 4px; }
+.a3g-meter-track { position: relative; width: 180px; height: 12px; background: rgba(0,0,0,.5);
+  border: 1px solid var(--a3g-edge); border-radius: var(--a3g-radius); overflow: hidden; }
+.a3g-meter-fill, .a3g-meter-ghost { position: absolute; inset: 0 auto 0 0; background: var(--a3g-accent); }
+.a3g-meter-ghost { background: var(--a3g-danger); opacity: .55; }
+.a3g-life-pip { display: inline-block; width: 12px; height: 12px; margin-right: 4px;
+  background: var(--a3g-accent); border-radius: 50%; }
+.a3g-minimap { position: relative; border: 1px solid var(--a3g-edge); background: var(--a3g-bg); }
+.a3g-minimap-marker { position: absolute; width: 8px; height: 8px; margin: -4px;
+  background: var(--a3g-accent); border-radius: 50%; }
+.a3g-indicator-arrow { color: var(--a3g-accent); font-size: 22px; transition: transform .15s; }
+.a3g-banner { position: absolute; left: 50%; top: 34%; transform: translate(-50%,-50%);
+  font-size: 42px; font-weight: 800; letter-spacing: .06em; text-shadow: var(--a3g-glow);
+  color: var(--a3g-accent); }
+.a3g-banner.a3g-hidden { display: none; }
+.a3g-toasts { position: absolute; left: 50%; bottom: 18%; transform: translateX(-50%);
+  display: flex; flex-direction: column; align-items: center; gap: 4px; }
+.a3g-toast { background: var(--a3g-bg); border: 1px solid var(--a3g-edge); border-radius: var(--a3g-radius);
+  padding: 4px 12px; font-size: 13px; }
+.a3g-damage { position: absolute; inset: 0; overflow: hidden; }
+.a3g-dmg { position: absolute; font-weight: 800; font-size: 18px; color: var(--a3g-fg);
+  text-shadow: 0 1px 2px rgba(0,0,0,.7); will-change: transform, opacity; }
+.a3g-dmg-crit { font-size: 26px; color: var(--a3g-danger); }
+@media (orientation: portrait) and (max-width: 480px) {
+  .a3g-mobile-hidden { display: none; }
+  .a3g-w { font-size: 13px; padding: 3px 8px; }
+}

package/dist/game/styles/themes/arcade-neon.css

@@ -0,0 +1,14 @@
+/* §7.7 theme "arcade-neon" — mirror of HUD_THEMES["arcade-neon"] in hud/themes.ts (runtime source of truth). */
+.a3g-hud.a3g-theme-arcade-neon {
+  --a3g-font: "A3G Orbitron","Orbitron",system-ui,sans-serif;
+  --a3g-fg: #e8fbff;
+  --a3g-fg-dim: #9ad9e6;
+  --a3g-accent: #39f5ff;
+  --a3g-accent2: #ff42c8;
+  --a3g-warn: #ffd166;
+  --a3g-danger: #ff4d6d;
+  --a3g-bg: rgba(6,10,26,0.72);
+  --a3g-edge: rgba(57,245,255,0.55);
+  --a3g-glow: 0 0 12px rgba(57,245,255,0.6);
+  --a3g-radius: 4px;
+}

package/dist/game/styles/themes/fighting.css

@@ -0,0 +1,14 @@
+/* §7.7 theme "fighting" — mirror of HUD_THEMES["fighting"] in hud/themes.ts (runtime source of truth). */
+.a3g-hud.a3g-theme-fighting {
+  --a3g-font: "A3G Russo One","Russo One",sans-serif;
+  --a3g-fg: #fff6e8;
+  --a3g-fg-dim: #d9c9a8;
+  --a3g-accent: #ffcc00;
+  --a3g-accent2: #ff5722;
+  --a3g-warn: #ffa726;
+  --a3g-danger: #ff1744;
+  --a3g-bg: rgba(20,8,4,0.78);
+  --a3g-edge: rgba(255,204,0,0.6);
+  --a3g-glow: 0 2px 0 rgba(0,0,0,0.6);
+  --a3g-radius: 3px;
+}

package/dist/game/styles/themes/motorsport.css

@@ -0,0 +1,14 @@
+/* §7.7 theme "motorsport" — mirror of HUD_THEMES["motorsport"] in hud/themes.ts (runtime source of truth). */
+.a3g-hud.a3g-theme-motorsport {
+  --a3g-font: "A3G Barlow Condensed","Barlow Condensed","Arial Narrow",sans-serif;
+  --a3g-fg: #f5f7fa;
+  --a3g-fg-dim: #aab4c0;
+  --a3g-accent: #ffcf3f;
+  --a3g-accent2: #2ec4ff;
+  --a3g-warn: #ff9f1c;
+  --a3g-danger: #ef233c;
+  --a3g-bg: rgba(10,12,16,0.78);
+  --a3g-edge: rgba(255,207,63,0.5);
+  --a3g-glow: none;
+  --a3g-radius: 2px;
+}

package/dist/game/styles/themes/plain.css

@@ -0,0 +1,14 @@
+/* §7.7 theme "plain" — mirror of HUD_THEMES["plain"] in hud/themes.ts (runtime source of truth). */
+.a3g-hud.a3g-theme-plain {
+  --a3g-font: system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+  --a3g-fg: #e6e6e6;
+  --a3g-fg-dim: #9aa0a8;
+  --a3g-accent: #8ab4ff;
+  --a3g-accent2: #a78bfa;
+  --a3g-warn: #fbbf24;
+  --a3g-danger: #f87171;
+  --a3g-bg: rgba(0,0,0,0.65);
+  --a3g-edge: rgba(255,255,255,0.2);
+  --a3g-glow: none;
+  --a3g-radius: 4px;
+}

package/dist/game/styles/themes/sci-fi-telemetry.css

@@ -0,0 +1,14 @@
+/* §7.7 theme "sci-fi-telemetry" — mirror of HUD_THEMES["sci-fi-telemetry"] in hud/themes.ts (runtime source of truth). */
+.a3g-hud.a3g-theme-sci-fi-telemetry {
+  --a3g-font: "A3G IBM Plex Mono","IBM Plex Mono",ui-monospace,monospace;
+  --a3g-fg: #c9ffe8;
+  --a3g-fg-dim: #6fbf9d;
+  --a3g-accent: #00ff9f;
+  --a3g-accent2: #7bd5ff;
+  --a3g-warn: #f7b32b;
+  --a3g-danger: #ff5c5c;
+  --a3g-bg: rgba(4,16,12,0.7);
+  --a3g-edge: rgba(0,255,159,0.4);
+  --a3g-glow: 0 0 8px rgba(0,255,159,0.35);
+  --a3g-radius: 0px;
+}

package/dist/game/styles/themes/sports-broadcast.css

@@ -0,0 +1,14 @@
+/* §7.7 theme "sports-broadcast" — mirror of HUD_THEMES["sports-broadcast"] in hud/themes.ts (runtime source of truth). */
+.a3g-hud.a3g-theme-sports-broadcast {
+  --a3g-font: "A3G Barlow Condensed","Barlow Condensed","Arial Narrow",sans-serif;
+  --a3g-fg: #ffffff;
+  --a3g-fg-dim: #cfd8e3;
+  --a3g-accent: #00e06d;
+  --a3g-accent2: #2b7fff;
+  --a3g-warn: #ffc93c;
+  --a3g-danger: #ff3b30;
+  --a3g-bg: rgba(8,14,26,0.85);
+  --a3g-edge: rgba(255,255,255,0.28);
+  --a3g-glow: none;
+  --a3g-radius: 6px;
+}

package/dist/game/styles/themes/tabletop.css

@@ -0,0 +1,14 @@
+/* §7.7 theme "tabletop" — mirror of HUD_THEMES["tabletop"] in hud/themes.ts (runtime source of truth). */
+.a3g-hud.a3g-theme-tabletop {
+  --a3g-font: "A3G Barlow Condensed","Barlow Condensed","Arial Narrow",sans-serif;
+  --a3g-fg: #f2ead9;
+  --a3g-fg-dim: #b9ab8d;
+  --a3g-accent: #7ce8ff;
+  --a3g-accent2: #d4a94f;
+  --a3g-warn: #e0a63f;
+  --a3g-danger: #e0523f;
+  --a3g-bg: rgba(24,18,10,0.8);
+  --a3g-edge: rgba(212,169,79,0.45);
+  --a3g-glow: none;
+  --a3g-radius: 8px;
+}

package/dist/game/styles.css

@@ -0,0 +1,45 @@
+/* @aura3d/game styles — PRD-09 day-0 shell/HUD base. Theme tokens are the
+   --a3g-* custom properties the HUD themes fill in during phase 2. */
+
+:root {
+  --a3g-font: system-ui, -apple-system, "Segoe UI", sans-serif;
+  --a3g-fg: #f4f6fb;
+  --a3g-bg: #0b0d12;
+  --a3g-accent: #54d1ff;
+  --a3g-banner-bg: rgb(11 13 18 / 0.72);
+  --a3g-widget-gap: 0.5rem;
+}
+
+.a3g-shell {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  font-family: var(--a3g-font);
+  color: var(--a3g-fg);
+  background: var(--a3g-bg);
+}
+
+.a3g-shell[data-layout="letterbox-16x9"] canvas,
+.a3g-shell[data-layout="letterbox-4x3"] canvas {
+  margin: auto;
+}
+
+.a3g-hud {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  display: grid;
+  grid-template-areas:
+    "top-left top top-right"
+    "left center right"
+    "bottom-left bottom bottom-right";
+  gap: var(--a3g-widget-gap);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .a3g-shell * {
+    animation-duration: 0.001s !important;
+    transition-duration: 0.001s !important;
+  }
+}

package/dist/game/testHook.d.ts

@@ -0,0 +1,45 @@
+/**
+ * testHook.ts — §15 deterministic-clock hook.
+ *
+ * Installs `window.__AURA3D_GAME_TEST__` so browser specs can advance the
+ * session clock by exactly `dt` per frame (`runtime.step(dt)` fires the
+ * engine frame callbacks, which tick the session) and inspect presented-
+ * frame ordering via `presentLog`. Installed only when the build defines
+ * `import.meta.env.MODE === "test"` — `layout.spec.ts` asserts the global
+ * is absent on production bundles.
+ */
+interface GameTestStepper {
+    step(dt?: number): unknown;
+    firstPresentedFrame(): Promise<number>;
+    readonly evidence?: {
+        frame?: number;
+    };
+}
+export interface PresentedLogEntry {
+    frame: number;
+    overlayOpacity: number;
+    sceneId: number;
+}
+export interface GameTestHook {
+    stepFrames(n: number, dt?: number): Promise<void>;
+    presentLog: PresentedLogEntry[];
+}
+declare global {
+    interface Window {
+        __AURA3D_GAME_TEST__?: GameTestHook;
+    }
+}
+/**
+ * Install the hook. `stepper` is the mounted `createGameApp` runtime (its
+ * `step(dt)` advances the loop, renders, and fires the frame callbacks the
+ * session listens to). `getSceneId` reads the route's scene revision so the
+ * presentLog can correlate entries with `game.setScene` calls.
+ */
+export declare function installGameTestHook(args: {
+    stepper: GameTestStepper;
+    getSceneId: () => number;
+    /** False once the owning game is disposed; the presentLog stops re-arming. */
+    isActive?: () => boolean;
+}): GameTestHook;
+export {};
+//# sourceMappingURL=testHook.d.ts.map

package/dist/game/testHook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testHook.d.ts","sourceRoot":"","sources":["../../../../packages/game/src/testHook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,oBAAoB,CAAC,EAAE,YAAY,CAAC;KACrC;CACF;AASD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,OAAO,EAAE,eAAe,CAAC;IACzB,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC;CAC1B,GAAG,YAAY,CA2Bf"}

package/dist/game/testHook.js

@@ -0,0 +1,52 @@
+/**
+ * testHook.ts — §15 deterministic-clock hook.
+ *
+ * Installs `window.__AURA3D_GAME_TEST__` so browser specs can advance the
+ * session clock by exactly `dt` per frame (`runtime.step(dt)` fires the
+ * engine frame callbacks, which tick the session) and inspect presented-
+ * frame ordering via `presentLog`. Installed only when the build defines
+ * `import.meta.env.MODE === "test"` — `layout.spec.ts` asserts the global
+ * is absent on production bundles.
+ */
+function overlayOpacityNow() {
+    const el = document.querySelector(".a3g-overlay");
+    if (!el)
+        return 0;
+    const opacity = Number.parseFloat(getComputedStyle(el).opacity);
+    return Number.isFinite(opacity) ? opacity : 0;
+}
+/**
+ * Install the hook. `stepper` is the mounted `createGameApp` runtime (its
+ * `step(dt)` advances the loop, renders, and fires the frame callbacks the
+ * session listens to). `getSceneId` reads the route's scene revision so the
+ * presentLog can correlate entries with `game.setScene` calls.
+ */
+export function installGameTestHook(args) {
+    const { stepper, getSceneId, isActive = () => true } = args;
+    const presentLog = [];
+    // Re-arm a presented-frame waiter: one entry per actually presented frame,
+    // with the overlay opacity sampled inside the same task as the resolve.
+    const armPresentLog = () => {
+        if (!isActive())
+            return;
+        void stepper.firstPresentedFrame().then((frame) => {
+            presentLog.push({ frame, overlayOpacity: overlayOpacityNow(), sceneId: getSceneId() });
+            armPresentLog();
+        });
+    };
+    armPresentLog();
+    const hook = {
+        presentLog,
+        async stepFrames(n, dt = 1 / 60) {
+            const presented = stepper.firstPresentedFrame();
+            for (let i = 0; i < n; i += 1)
+                stepper.step(dt);
+            // `step()` resolves presented waiters synchronously after its render;
+            // awaiting the waiter still covers runtimes that defer presentation.
+            await presented;
+        }
+    };
+    window.__AURA3D_GAME_TEST__ = hook;
+    return hook;
+}
+//# sourceMappingURL=testHook.js.map

package/dist/game/testHook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testHook.js","sourceRoot":"","sources":["../../../../packages/game/src/testHook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyBH,SAAS,iBAAiB;IACxB,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAc,cAAc,CAAC,CAAC;IAC/D,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,CAAC;IAClB,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAChE,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAKnC;IACC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC;IAC5D,MAAM,UAAU,GAAwB,EAAE,CAAC;IAE3C,2EAA2E;IAC3E,wEAAwE;IACxE,MAAM,aAAa,GAAG,GAAG,EAAE;QACzB,IAAI,CAAC,QAAQ,EAAE;YAAE,OAAO;QACxB,KAAK,OAAO,CAAC,mBAAmB,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YAChD,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;YACvF,aAAa,EAAE,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IACF,aAAa,EAAE,CAAC;IAEhB,MAAM,IAAI,GAAiB;QACzB,UAAU;QACV,KAAK,CAAC,UAAU,CAAC,CAAS,EAAE,EAAE,GAAG,CAAC,GAAG,EAAE;YACrC,MAAM,SAAS,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;YAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAChD,sEAAsE;YACtE,qEAAqE;YACrE,MAAM,SAAS,CAAC;QAClB,CAAC;KACF,CAAC;IACF,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/game/touch/TouchControls.d.ts

@@ -0,0 +1,74 @@
+/**
+ * §6.11 touch controls (PRD-09 1766): presets built on
+ * `@aura3d/input`'s `VirtualTouchJoystick` + `TouchLayouts.ts`, writing into
+ * `GameInputController` (`press`/`release`/`setAction`) — the same action
+ * path as physical keys, no parallel input stack.
+ *
+ * Visibility rule: shown after the first `touchstart`, or at mount when
+ * `(pointer: coarse)` matches; hidden otherwise (desktop fine pointers never
+ * see it). While visible, keyboard-hint elements marked `data-a3g-keyhint`
+ * are hidden. Every target is ≥ 48 CSS px (enforced by the TouchLayouts unit
+ * test at 390×844) and rects are expressed in safe-area-relative units.
+ */
+import { type TouchLayoutGenre } from "../../input/index.js";
+import type { HudDocument, HudElement } from "../hud/dom.js";
+export type TouchPreset = "twin-stick" | "dpad-2btn" | "dpad-4btn" | "steer-pedals" | "aim-drag" | "flight" | "lane-swipe" | "flippers";
+/** §6.11: preset → TouchLayouts genre (dpad-2btn→platform, dpad-4btn→fight, steer-pedals→race). */
+export declare const TOUCH_PRESET_GENRE: Readonly<Record<TouchPreset, TouchLayoutGenre>>;
+export interface TouchControlsOptions {
+    readonly preset: TouchPreset;
+    /**
+     * Control-id → action/code map. Button ids are the layout's element suffixes
+     * (`"jump"`, `"light"`, …); stick directions are `"stick.up"`, `"stick.down"`,
+     * `"stick.left"`, `"stick.right"`, and `"rstick.*"` for the second stick.
+     * Values are `GameInputController` actions (via `setAction`).
+     */
+    readonly bindings: Readonly<Record<string, string>>;
+    /** Force visibility (overrides the §6.11 rule). */
+    readonly show?: boolean;
+    /** Android-style tick on press — calls `navigator.vibrate(ms)`. */
+    readonly haptics?: boolean | {
+        ms?: number;
+    };
+    /** Uniform scale multiplier for rect size (default 1). */
+    readonly scale?: number;
+}
+/** The `GameInputController` surface touch writes into (structural). */
+export interface TouchInputSink {
+    press(binding: string): void;
+    release(binding: string): void;
+    setAction(action: string, held: boolean): void;
+}
+export interface TouchControls {
+    readonly visible: boolean;
+    readonly preset: TouchPreset;
+    setVisible(visible: boolean): void;
+    /** Feed a frame tick so stick values stay current; safe to call every frame. */
+    update(): void;
+    dispose(): void;
+    /** Per-control snapshot for evidence (bound/missing, live values). */
+    evidence(): {
+        readonly preset: TouchPreset;
+        readonly genre: TouchLayoutGenre;
+        readonly bound: readonly string[];
+        readonly visible: boolean;
+        readonly sticks: readonly string[];
+    };
+}
+export interface TouchControlsDeps {
+    readonly doc: HudDocument;
+    /** Parent element the `.a3g-touch` host is appended to (the shell layer). */
+    readonly root: HudElement;
+    /** Viewport px the safe-area rects are scaled against. */
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** `(pointer: coarse)` matcher — when true the controls show at mount. */
+    readonly coarsePointer?: () => boolean;
+    /** Haptics sink; default `navigator.vibrate` when present. */
+    readonly vibrate?: (ms: number) => void;
+    readonly warn?: (m: string) => void;
+}
+export declare function mountTouchControls(input: TouchInputSink, options: TouchControlsOptions, deps: TouchControlsDeps): TouchControls;
+//# sourceMappingURL=TouchControls.d.ts.map

package/dist/game/touch/TouchControls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TouchControls.d.ts","sourceRoot":"","sources":["../../../../../packages/game/src/touch/TouchControls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAGL,KAAK,gBAAgB,EAGtB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE7D,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,WAAW,GACX,WAAW,GACX,cAAc,GACd,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,UAAU,CAAC;AAEf,mGAAmG;AACnG,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAS7E,CAAC;AAEH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,gFAAgF;IAChF,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;IAChB,sEAAsE;IACtE,QAAQ,IAAI;QACV,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;QAC7B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;QACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AASD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,iBAAiB,GACtB,aAAa,CAgKf"}

package/dist/game/touch/TouchControls.js

@@ -0,0 +1,210 @@
+/**
+ * §6.11 touch controls (PRD-09 1766): presets built on
+ * `@aura3d/input`'s `VirtualTouchJoystick` + `TouchLayouts.ts`, writing into
+ * `GameInputController` (`press`/`release`/`setAction`) — the same action
+ * path as physical keys, no parallel input stack.
+ *
+ * Visibility rule: shown after the first `touchstart`, or at mount when
+ * `(pointer: coarse)` matches; hidden otherwise (desktop fine pointers never
+ * see it). While visible, keyboard-hint elements marked `data-a3g-keyhint`
+ * are hidden. Every target is ≥ 48 CSS px (enforced by the TouchLayouts unit
+ * test at 390×844) and rects are expressed in safe-area-relative units.
+ */
+import { createTouchLayoutPreset, VirtualTouchJoystick } from "../../input/index.js";
+/** §6.11: preset → TouchLayouts genre (dpad-2btn→platform, dpad-4btn→fight, steer-pedals→race). */
+export const TOUCH_PRESET_GENRE = Object.freeze({
+    "twin-stick": "twin-stick",
+    "dpad-2btn": "platform",
+    "dpad-4btn": "fight",
+    "steer-pedals": "race",
+    "aim-drag": "aim-drag",
+    "flight": "flight",
+    "lane-swipe": "lane-swipe",
+    "flippers": "flippers"
+});
+const STICK_DIRS = [
+    ["stick.left", -1, 0],
+    ["stick.right", 1, 0],
+    ["stick.up", 0, -1],
+    ["stick.down", 0, 1]
+];
+export function mountTouchControls(input, options, deps) {
+    const { doc } = deps;
+    const genre = TOUCH_PRESET_GENRE[options.preset];
+    const viewport = deps.viewport ?? { width: 390, height: 844 };
+    const scale = options.scale ?? 1;
+    const warn = deps.warn ?? ((m) => console.warn(m));
+    const vibrate = deps.vibrate ??
+        ((ms) => {
+            navigator?.vibrate?.(ms);
+        });
+    const preset = createTouchLayoutPreset(genre, {
+        width: viewport.width,
+        height: viewport.height,
+        elementIdPrefix: `a3g-touch-${options.preset}`
+    });
+    const host = doc.createElement("div");
+    host.className = `a3g-touch a3g-touch-${options.preset} a3g-hidden`;
+    deps.root.appendChild(host);
+    const bound = [];
+    const sticks = [];
+    const stickHeld = new Map();
+    const place = (name, rect, extra = "") => {
+        const el = doc.createElement("div");
+        el.className = `a3g-tc ${extra}`.trim();
+        el.dataset.control = name;
+        el.style.left = `${rect.x * 100}%`;
+        el.style.top = `${rect.y * 100}%`;
+        el.style.width = `${rect.w * scale * 100}%`;
+        el.style.height = `${rect.h * scale * 100}%`;
+        host.appendChild(el);
+        return el;
+    };
+    const bindButton = (suffix, action) => {
+        const rect = preset.rects[suffix];
+        if (!rect) {
+            warn(`a3g-touch: no rect for "${suffix}" in preset ${options.preset}`);
+            return;
+        }
+        if (!action)
+            return; // unbound controls are not rendered
+        const el = place(suffix, rect, "a3g-tc-btn");
+        el.setAttribute("role", "button");
+        let down = false;
+        el.addEventListener("touchstart", () => {
+            down = true;
+            input.setAction(action, true);
+            el.classList.add("a3g-tc-down");
+            if (options.haptics)
+                vibrate(typeof options.haptics === "object" ? options.haptics.ms ?? 12 : 12);
+        });
+        const release = () => {
+            if (!down)
+                return;
+            down = false;
+            input.setAction(action, false);
+            el.classList.remove("a3g-tc-down");
+        };
+        el.addEventListener("touchend", release);
+        el.addEventListener("touchcancel", release);
+        bound.push(suffix);
+    };
+    for (const b of [...preset.hold, ...preset.pulse]) {
+        const suffix = b.elementId.split(":").pop();
+        bindButton(suffix, options.bindings[suffix] ?? options.bindings[b.elementId]);
+    }
+    // Sticks: DOM zone + VirtualTouchJoystick writing directional actions.
+    const stickSpecs = [
+        { name: "stick", cfg: preset.leftStick },
+        { name: "rstick", cfg: preset.rightStick }
+    ];
+    for (const { name, cfg } of stickSpecs) {
+        const rect = preset.rects[name];
+        if (!cfg || !rect)
+            continue;
+        const el = place(name, rect, "a3g-tc-stick");
+        const nub = doc.createElement("div");
+        nub.className = "a3g-tc-stick-nub";
+        el.appendChild(nub);
+        const pxW = rect.w * viewport.width;
+        const pxH = rect.h * viewport.height;
+        const joystick = new VirtualTouchJoystick({
+            center: [pxW / 2, pxH / 2],
+            radius: Math.min(pxW, pxH) / 2,
+            deadZone: cfg.deadZone ?? 0.18,
+            fixed: cfg.fixed,
+            returnToCenter: cfg.returnToCenter
+        });
+        let nextId = 0;
+        el.addEventListener("touchstart", (ev) => {
+            const t = ev.changedTouches?.[0];
+            const r = el.getBoundingClientRect();
+            joystick.touchStart({
+                id: ++nextId,
+                x: (t?.clientX ?? r.left + pxW / 2) - r.left,
+                y: (t?.clientY ?? r.top + pxH / 2) - r.top
+            });
+        });
+        el.addEventListener("touchmove", (ev) => {
+            const t = ev.changedTouches?.[0];
+            if (!t)
+                return;
+            const r = el.getBoundingClientRect();
+            joystick.touchMove({ id: nextId, x: t.clientX - r.left, y: t.clientY - r.top });
+        });
+        el.addEventListener("touchend", () => joystick.touchEnd({ id: nextId, x: 0, y: 0 }));
+        el.addEventListener("touchcancel", () => joystick.touchEnd({ id: nextId, x: 0, y: 0 }));
+        sticks.push({ name, stick: joystick, rect });
+        bound.push(name);
+    }
+    const syncStick = (name, stick) => {
+        const [vx, vy] = stick.snapshot().value;
+        for (const [dir, dx, dy] of STICK_DIRS) {
+            const controlId = `${name}.${dir.split(".").pop()}`;
+            const action = options.bindings[controlId];
+            if (!action)
+                continue;
+            const shouldHold = (dx !== 0 ? vx * dx : vy * dy) > 0.35;
+            const key = `${name}.${dir}`;
+            const wasHeld = stickHeld.get(key) === action;
+            if (shouldHold && !wasHeld) {
+                input.setAction(action, true);
+                stickHeld.set(key, action);
+            }
+            else if (!shouldHold && wasHeld) {
+                input.setAction(action, false);
+                stickHeld.delete(key);
+            }
+        }
+        // Nub visual offset
+        void name;
+    };
+    let visible = false;
+    const applyVisibility = (v) => {
+        visible = v;
+        host.classList.toggle("a3g-hidden", !v);
+        // §6.11: keyboard-hint strips hide whenever touch controls are visible.
+        doc.body?.children?.forEach?.(() => { });
+        for (const hint of keyhints(doc))
+            hint.classList.toggle("a3g-hidden", v);
+    };
+    const onFirstTouch = () => { if (!visible)
+        applyVisibility(true); };
+    // First touchstart anywhere reveals the controls (§6.11).
+    doc.body.addEventListener("touchstart", onFirstTouch);
+    applyVisibility(options.show ?? deps.coarsePointer?.() ?? false);
+    return {
+        get visible() { return visible; },
+        preset: options.preset,
+        setVisible: applyVisibility,
+        update() {
+            for (const s of sticks)
+                syncStick(s.name, s.stick);
+        },
+        dispose() {
+            doc.body.removeEventListener("touchstart", onFirstTouch);
+            host.remove();
+        },
+        evidence: () => ({
+            preset: options.preset,
+            genre,
+            bound,
+            visible,
+            sticks: sticks.map((s) => s.name)
+        })
+    };
+}
+/** Elements flagged `data-a3g-keyhint` under the document. */
+function keyhints(doc) {
+    const found = [];
+    const walk = (el) => {
+        if (el.dataset?.a3gKeyhint !== undefined || el.getAttribute?.("data-a3g-keyhint") !== null)
+            found.push(el);
+        for (const c of el.children)
+            walk(c);
+    };
+    for (const c of doc.body.children)
+        walk(c);
+    return found;
+}
+//# sourceMappingURL=TouchControls.js.map