perf(web): PRD-752 run web games in a worker so the page cannot stall them

docs/PRDs/performance/PRD-573-unreal-class-performance-in-release-cycles.md

@@ -56,6 +56,7 @@ shares: animation about 13%, cull and project about 11%, `Renderer::render` 21%,
   when its web and desktop rows both pass on the engine ([PRD-617](PRD-617-every-template-runs-on-the-native-engine.md)).
   The engine exposes the upstream Three.js API, and a game uses the same source on every back end.
   This refines the previous decision: the default is not reverted while templates remain pinned.
+- 2026-10-26 (owner): the worker HUD contract is confirmed (one state snapshot per frame out, intents back): "Yes, and v5.2 threads too". Cycle v5 moves to [PRD-752](./PRD-752-web-games-run-in-a-worker-so-the-page-cannot-stall-them.md).
 - 2026-10-15 (owner): housekeeping. Delete junk and reduce the file count; keep every behaviour.
 - Deferred, filed again only on scorecard evidence: transform compose skip (if
   `updateMatrixWorldSelf` is above 2% of the frame), projection reuse and SIMD world matrices (if
@@ -311,6 +312,8 @@ TN today: HZB declined ([PRD-489](../done/PRD-489-gpu-scene-occlusion-culling.md
 
 ## Cycle v5 — web worker
 
+**Owned by [PRD-752](./PRD-752-web-games-run-in-a-worker-so-the-page-cannot-stall-them.md)** (owner, 2026-10-26: worker HUD contract confirmed, "Yes, and v5.2 threads too"). The boxes below stay as the summary; PRD-752 carries the proof.
+
 The game side reads the DOM directly (23 core files read `document.` or `window.`; audio, pointer lock, gamepads, `localStorage`). A worker keeps frame p50; only Wasm threads can cut it.
 
 #### Phase v5.1: Worker mode
@@ -328,7 +331,6 @@ The game side reads the DOM directly (23 core files read `document.` or `window.
 - The v3 margin over Godot is an owner number, set before v3 starts.
 - Whether engine-only commits may skip `native-platforms` is an owner call (slice 0b).
 - `AnimationMixer.updateRate` adds a non-three property; João confirms the name before v2.3.
-- The worker HUD contract (state out once per frame) needs João's confirmation before v5.1.
 - Android timing rows need the Pixel 8 attached; the emulator holds counter and memory rows.
 - Safari rows need a macOS machine.
 

packages/core/__tests__/game.spec.ts

@@ -3519,6 +3519,58 @@ describe("IGame", () => {
     }
   });
 
+  it("takes the platform source a worker host installs when the game names none (PRD-752)", async () => {
+    // Worker mode: game.ts is the unchanged portable entry, so the worker host cannot pass
+    // `platform` to defineGame. It installs the source on the global scope before start().
+    const canvas = new EventTarget() as HTMLCanvasElement;
+    let mounted = 0;
+    let unmounted = 0;
+    const platform: IGamePlatformSource = {
+      input: () => [],
+      inputTarget: new EventTarget(),
+      mountCanvas: () => {
+        mounted += 1;
+      },
+      renderer: {
+        createCanvas: () => canvas,
+        hasWebGPU: () => false,
+        observeResize: () => () => undefined,
+        readSize: () => [320, 180],
+      },
+      unmountCanvas: () => {
+        unmounted += 1;
+      },
+      viewport: {
+        observeResize: () => () => undefined,
+        readSize: () => ({ aspect: 16 / 9, height: 180, width: 320 }),
+      },
+    };
+    vi.stubGlobal("__tnGamePlatform", platform);
+    const game = defineGame({
+      renderer: {
+        preferWebGPU: false,
+        webgl2Factory: () => ({
+          dispose: () => undefined,
+          domElement: canvas,
+          render: () => undefined,
+          setSize: () => undefined,
+        }),
+      },
+      scenes: { test: EmptyScene },
+      start: "test",
+    });
+    try {
+      await game.start();
+      expect(mounted).toBe(1);
+      expect(game.ctx?.viewport.size).toEqual({ aspect: 16 / 9, height: 180, width: 320 });
+      game.stop();
+      expect(unmounted).toBe(1);
+    } finally {
+      game.stop();
+      vi.unstubAllGlobals();
+    }
+  });
+
   it.each([
     { opaque: false, worldDrawn: false },
     { opaque: true, worldDrawn: true },

packages/core/__tests__/input.spec.ts

@@ -572,6 +572,17 @@ describe("InputMap", () => {
     input.dispose();
   });
 
+  it("takes the lock state a worker host forwards with pointerlockchange, where no document exists (PRD-752)", () => {
+    const canvas = Object.assign(new EventTarget(), { requestPointerLock: () => undefined });
+    const input = new InputMap({ look: { pointerRelative: true } }, canvas, canvas);
+    input.captureMouse();
+    expect(input.raw.pointer.captured).toBe(true);
+    // Escape on the page: the host forwards the change with the page's verdict.
+    canvas.dispatchEvent(Object.assign(new Event("pointerlockchange"), { captured: false }));
+    expect(input.raw.pointer.captured).toBe(false);
+    input.dispose();
+  });
+
   it("releases a held mouse button on a button-less move while the pointer is free", () => {
     // Released outside the window, no pointerup arrives: the next move is what clears it.
     const target = new EventTarget();

packages/core/__tests__/platform.spec.ts

@@ -1,7 +1,8 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
   detectPlatform,
   getPlatform,
+  hostGestureTarget,
   isMobile,
   isNative,
   isTouchscreenAvailable,
@@ -133,3 +134,21 @@ describe("platform detection", () => {
     expect(isWeb()).not.toBe(isNative());
   });
 });
+
+describe("host gesture target (PRD-752)", () => {
+  it("is the page window, else the input target a worker host installed", () => {
+    // AudioBus waits for a gesture before it plays. A worker has no window, so without the
+    // platform's input target every cue would stay queued.
+    const inputTarget = new EventTarget();
+    const view = new EventTarget();
+    vi.stubGlobal("__tnGamePlatform", { inputTarget });
+    try {
+      vi.stubGlobal("window", undefined);
+      expect(hostGestureTarget()).toBe(inputTarget);
+      vi.stubGlobal("window", view);
+      expect(hostGestureTarget()).toBe(view);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});

packages/core/__tests__/renderer.spec.ts

@@ -953,6 +953,32 @@ describe("createRenderer", () => {
     }
   });
 
+  it("names the WebGPU failure in TN_NO_RENDERER instead of swallowing it (PRD-752)", async () => {
+    // A worker boot fell back because the Wasm renderer called a DOM-only canvas method; the
+    // boot error said only "WebGPU is not available", which hid the fix.
+    const descriptor = Object.getOwnPropertyDescriptor(globalThis, "navigator");
+    Object.defineProperty(globalThis, "navigator", { configurable: true, value: { gpu: {} } });
+    try {
+      await expect(
+        createRenderer({
+          canvas: testCanvas(),
+          preferWebGPU: true,
+          webgl2Factory: () => {
+            throw new Error("no WebGL");
+          },
+          webgpuFactory: () => {
+            throw new TypeError("this.domElement.setAttribute is not a function");
+          },
+        }),
+      ).rejects.toThrow(
+        /^TN_NO_RENDERER: .* WebGPU failed: this\.domElement\.setAttribute is not a function$/u,
+      );
+    } finally {
+      if (descriptor === undefined) Reflect.deleteProperty(globalThis, "navigator");
+      else Object.defineProperty(globalThis, "navigator", descriptor);
+    }
+  });
+
   it("reports a facade and Wasm engine of two web host ABIs as that, not as a device without WebGPU", async () => {
     const descriptor = Object.getOwnPropertyDescriptor(globalThis, "navigator");
     Object.defineProperty(globalThis, "navigator", { configurable: true, value: { gpu: {} } });

packages/core/__tests__/ui-bridge-inbound.spec.ts

@@ -61,3 +61,36 @@ describe("ui bridge inbound global", () => {
     expect(scope[UI_BRIDGE_GLOBALS.gameReceive]).toBeUndefined();
   });
 });
+
+describe("ui bridge loopback over a message port (PRD-752)", () => {
+  const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+  it("carries state and intents over an async port when the page asks for ?tnUiLoopback=1", async () => {
+    const scope: Record<string, unknown> = { location: { search: "?tnUiLoopback=1" } };
+    const ui = connectUiBridge({ end: "ui", scope });
+    const game = connectUiBridge({ end: "game", scope });
+    const seenByUi: unknown[] = [];
+    const seenByGame: unknown[] = [];
+    ui.onMessage((message) => seenByUi.push(message));
+    game.onMessage((message) => seenByGame.push(message));
+
+    expect([ui.transport, game.transport]).toEqual(["host", "host"]);
+    expect(game.hasPeer()).toBe(true);
+    game.post({ type: "tn:state", state: { score: 3 } });
+    ui.post({ type: "tn:intent", name: "pause" });
+    // A worker delivers a task later, never inside the post: the loopback must too.
+    expect([seenByUi, seenByGame]).toEqual([[], []]);
+    await tick();
+    expect(seenByUi).toEqual([{ type: "tn:state", state: { score: 3 } }]);
+    expect(seenByGame).toEqual([{ type: "tn:intent", name: "pause" }]);
+
+    ui.close();
+    game.close();
+    (scope.__tnUiLoopback as { close(): void }).close();
+  });
+
+  it("keeps the in-process broker without the flag", () => {
+    const scope: Record<string, unknown> = { location: { search: "" } };
+    expect(connectUiBridge({ end: "ui", scope }).transport).toBe("in-process");
+  });
+});