@vgai/engine 0.5.2 → 0.5.3

package/src/runtime/debug-bridge.ts

@@ -1,15 +1,13 @@
 /**
- * The standalone in-page debug bridge (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.4,
- * D17/D18; Task 2.1 of `docs/E2E-TESTING-BUILD-PLAN.md`). Query-gated
- * `window.__vgai`, the same production-protection-lives-in-the-installer
- * pattern `render-control.ts`'s `installRenderControlHarness` established for
- * `?vgai-render=1` (production protection lives HERE, not just at whatever
- * call site invokes this — a caller that calls
- * {@link maybeInstallDebugBridge} unconditionally on every boot still only
- * ever gets a handle when the gate below actually passes).
+ * The standalone in-page debug bridge. Query-gated `window.__vgai`, the same
+ * production-protection-lives-in-the-installer pattern `render-control.ts`'s
+ * `installRenderControlHarness` established for `?vgai-render=1` (production
+ * protection lives HERE, not just at whatever call site invokes this — a
+ * caller that calls {@link maybeInstallDebugBridge} unconditionally on every
+ * boot still only ever gets a handle when the gate below actually passes).
  *
  * D17: this is door (a) of the seam's three doors — the SAME `DebugAdapter`
- * names/JSON the editor relay (door b) and `@vgai/e2e` (door c, which
+ * names/JSON the editor relay (door b) and `@vgai/live` (door c, which
  * drives door (a) itself over Playwright) all read. D18: the bridge installs
  * only when the page opts in (`?vgai-debug=1`) AND is either a dev build
  * (`import.meta.env.DEV`) or the project's manifest explicitly opts a
@@ -40,7 +38,7 @@ export interface DebugBridgeManifest {
  *  import. Every method takes an optional trailing `worldId` (D15/T-D15.5,
  *  the review-objection-2 fix): omitted, it resolves to the SAME default
  *  world the editor relay's `inject-input` case resolves to (one shared
- *  resolution function, `debug-registry.ts`'s `resolveInputWorldId`) — never
+ *  resolution function, `debug-registry.ts`'s `resolveInputRootId`) — never
  *  "whichever world's `InputManager` happened to register last". An
  *  explicit `worldId` reaches that world's `InputManager` specifically. */
 export interface VgaiDebugInputHandle {
@@ -52,15 +50,14 @@ export interface VgaiDebugInputHandle {
   tapVirtualAction(action: string, worldId?: string): { delivered: boolean; reason?: string };
   clearVirtualActions(worldId?: string): void;
   /**
-   * D15/T-D15.5 (`docs/D15-DETERMINISM-DESIGN.md` §2.c): schedule a virtual
-   * actuation for a specific tick — applied at the START of that tick's
-   * input phase, composing with `runTicks` (a schedule for tick 500 fires
-   * exactly once the sim has been driven through tick 500, regardless of
-   * burst size). A digital `true` produces a genuine `isJustPressed` edge
-   * exactly at the target tick. Throws `INPUT_ACTION_NOT_FOUND`/a valueType
-   * mismatch (same as `setVirtualAction`) or `TICK_ALREADY_PASSED`
-   * (`data.currentTick`, the NEXT tick to be serviced) for a tick that
-   * already elapsed.
+   * D15/T-D15.5: schedule a virtual actuation for a specific tick — applied
+   * at the START of that tick's input phase, composing with `runTicks` (a
+   * schedule for tick 500 fires exactly once the sim has been driven
+   * through tick 500, regardless of burst size). A digital `true` produces
+   * a genuine `isJustPressed` edge exactly at the target tick. Throws
+   * `INPUT_ACTION_NOT_FOUND`/a valueType mismatch (same as
+   * `setVirtualAction`) or `TICK_ALREADY_PASSED` (`data.currentTick`, the
+   * NEXT tick to be serviced) for a tick that already elapsed.
    *
    * A scheduled tick whose input phase never runs at all (that world
    * paused/frozen, or skipped by a multi-tick gap, when the target tick
@@ -130,20 +127,20 @@ export interface VgaiDebugHandle {
   invoke(name: string, args: unknown[]): Promise<unknown>;
   events: DebugAdapter['events'];
   input: VgaiDebugInputHandle;
-  /** See `DebugAdapter.events`'s doc comment for `sinceTick`/`sinceSeq`'s
-   *  contract (run-4 friction #5) — `snapshot`'s `events` member is filtered
-   *  the exact same way, just batched with `time`/`state`/`pageErrors` into
-   *  one synchronous read. */
-  snapshot(sinceTick?: number, sinceSeq?: number): VgaiDebugSnapshot;
+  /** See `DebugAdapter.events`'s doc comment for `sinceSeq`'s contract
+   *  (run-4 friction #5) — `snapshot`'s `events` member is filtered the exact
+   *  same way, just batched with `time`/`state`/`pageErrors` into one
+   *  synchronous read. */
+  snapshot(sinceSeq?: number): VgaiDebugSnapshot;
   /**
-   * D15/T-D15.4 door (a) (`docs/D15-DETERMINISM-DESIGN.md` §2.b): synchronously
-   * drive `n` fixed gameplay ticks via the live `Game`'s `GameInternal.runTicks`
-   * (`runtime/game.ts`) — reached through `DebugRegistry.getRunTicksTarget()`,
-   * the SAME target the editor relay's `run-ticks` case (→ `play.runTicks`,
-   * door b) calls, so behavior is byte-identical across every door (D17).
-   * Throws `DEBUG_RUN_TICKS_UNAVAILABLE` if no `Game` has wired a target yet
-   * (no world mounted); throws whatever `runTicks` itself throws otherwise
-   * (e.g. `RUN_TICKS_PAUSED`) — never a silent no-op.
+   * D15/T-D15.4 door (a): synchronously drive `n` fixed gameplay ticks via the
+   * live `Game`'s `GameInternal.runTicks` (`runtime/game.ts`) — reached through
+   * `DebugRegistry.getRunTicksTarget()`, the SAME target the editor relay's
+   * `run-ticks` case (→ `play.runTicks`, door b) calls, so behavior is
+   * byte-identical across every door (D17). Throws `DEBUG_RUN_TICKS_UNAVAILABLE`
+   * if no `Game` has wired a target yet (no world mounted); throws whatever
+   * `runTicks` itself throws otherwise (e.g. `RUN_TICKS_PAUSED`) — never a
+   * silent no-op.
    */
   runTicks(n: number, opts?: RunTicksOptions): void;
   /**
@@ -152,7 +149,7 @@ export interface VgaiDebugHandle {
    * this is the honest human-input-path proof) → `input.clearVirtualActions()`
    * into ONE async bridge call, as a TOP-LEVEL method (not under `input`)
    * because it needs the sim clock, not just the input target. Was 15+
-   * transport round trips over the editor relay (`@vgai/e2e`'s old
+   * transport round trips over the editor relay (`@vgai/live`'s old
    * `GameInput.hold`: set → a 150ms-interval `waitSimTime` snapshot poll loop
    * → clear); now one `page.evaluate`/relay call that runs the wait
    * in-process on the page.
@@ -179,7 +176,7 @@ export interface VgaiDebugHandle {
    * Defect 5 fix — undo everything THIS install did: remove the
    * `error`/`unhandledrejection` window listeners it added, and delete
    * `window.__vgai` so the registry is no longer reachable from the page.
-   * Idempotent (a second call is a harmless no-op). `mountManifestWorlds`
+   * Idempotent (a second call is a harmless no-op). `mountManifestRoots`
    * wires this into its session's `stop()`; a caller mounting more
    * directly (a hand-rolled host) should call it on its own teardown path.
    */
@@ -224,72 +221,128 @@ export interface MaybeInstallDebugBridgeOptions {
 const PAGE_ERROR_CAP = 100;
 
 /** `holdFor`'s in-process poll interval — this loop never leaves the page
- *  (no transport round trip per poll, unlike `@vgai/e2e`'s old
+ *  (no transport round trip per poll, unlike `@vgai/live`'s old
  *  `waitSimTime`), so it can afford to be tighter than that loop's 150ms. */
 const HOLD_FOR_POLL_MS = 50;
 
 /** Consecutive `HOLD_FOR_POLL_MS` polls with the tick unchanged before
  *  `holdFor` gives up waiting and treats the game as stopped — mirrors
- *  `@vgai/e2e`'s `WAIT_FOR_STALL_POLL_LIMIT` reasoning (`wait-for.ts`:
+ *  `@vgai/live`'s `WAIT_FOR_STALL_POLL_LIMIT` reasoning (`wait-for.ts`:
  *  a genuinely frozen sim clock must never poll forever), scaled to this
  *  faster in-process interval so the wall-clock grace period (~5s) lands in
  *  the same neighborhood. */
 const HOLD_FOR_STALL_POLL_LIMIT = 100;
 
-/** Resolves once `simSeconds` of sim time has elapsed since the call (normal
- *  host-loop ticks while visible; deterministic `runTicks` through the same
- *  game phases when the host loop reports `hidden-paused`), or once the tick
- *  has stopped changing for
- *  `HOLD_FOR_STALL_POLL_LIMIT` consecutive polls (`stalled: true` — the loop
- *  driving ticks stopped, e.g. play was stopped/paused). Never rejects.
- *  Exported (not just used by `holdFor` below) so the editor relay's
- *  `command-listener.ts` `holdFor` case can share the EXACT same
- *  poll/stall/hidden-drive logic against its own `DebugAdapter` (reached via
- *  `getActiveSystems().debug` rather than a `DebugRegistry`) — D17:
- *  byte-identical behavior across doors, not two hand-copies that can
- *  silently drift apart. */
-export function waitForHoldBudget(
+/** Ticks driven per synchronous hidden-tab batch. Sized like
+ *  `fast-forward.ts`'s own batching rationale: big enough that per-batch
+ *  bookkeeping is negligible, small enough that one batch of a complex game's
+ *  phases stays a short synchronous burst. */
+const HIDDEN_DRIVE_BATCH_TICKS = 60;
+
+/** Hard ceiling on hidden-drive batches for ONE hold — `HIDDEN_DRIVE_BATCH_TICKS
+ *  * this` ≈ 33 sim-minutes. A bound, not a timeout: it exists so a
+ *  `runTicks` target that advances the tick counter without advancing the sim
+ *  clock can never spin forever, and it is far past any honest hold. */
+const HIDDEN_DRIVE_MAX_BATCHES = 2000;
+
+/** The message a hold gets when the loop is hidden-paused and NOTHING can
+ *  drive it — the one case where the platform genuinely prevents the verb
+ *  from working. Names the cause and the fix rather than expiring into a
+ *  generic stall (which reported the wrong cause: "play stopped during
+ *  hold"). One exported constant so both doors and their tests read the same
+ *  string. */
+export const HOLD_HIDDEN_NO_DRIVER_REASON =
+  'the editor tab is hidden and this session has no way to drive ticks — the engine ' +
+  'hidden-pauses its loop while document.hidden, so zero ticks are happening. Bring the ' +
+  'editor tab to the foreground (or start play, which wires the run-ticks target) and retry.';
+
+/** What `adapter.state('time')` returns for the two fields this loop reads,
+ *  plus the liveness the hidden path branches on. */
+interface HoldClockReading {
+  simSeconds: number;
+  tick: number;
+  loopLiveness?: GameLoopLiveness | null;
+}
+
+/**
+ * Resolves once `simSeconds` of sim time has elapsed since the call, or once
+ * the wait provably cannot make progress. Never rejects. Exported (not just
+ * used by `holdFor` below) so the editor relay's `command-listener.ts`
+ * `holdFor` case can share the EXACT same logic against its own
+ * `DebugAdapter` (reached via `getActiveSystems().debug` rather than a
+ * `DebugRegistry`) — D17: byte-identical behavior across doors, not two
+ * hand-copies that can silently drift apart.
+ *
+ * Two regimes, and the split is the whole point:
+ *
+ * - **Visible**: the host loop is ticking on its own, so this polls it every
+ *   `HOLD_FOR_POLL_MS` and gives up after `HOLD_FOR_STALL_POLL_LIMIT`
+ *   consecutive unchanged-tick polls (`stalled: true` — play stopped/paused).
+ *
+ * - **Hidden-paused**: the host loop has stopped outright (T2.1's idle
+ *   throttle), so sim time only moves if this drives it. It therefore drives
+ *   the WHOLE remaining budget in synchronous batches, yielding a MICROTASK
+ *   between them — never a timer. That distinction is load-bearing, not
+ *   stylistic: a hidden tab clamps `setTimeout` to ~1s (and to ~1/minute under
+ *   Chrome's intensive throttling after 5 minutes hidden), so the previous
+ *   "drive 3 ticks, then `setTimeout(poll, 50)`" shape ran the sim at ~3
+ *   ticks per SECOND. A 1.2s hold needed ~24 clamped turns — ~24s of wall
+ *   clock against the editor relay's 5s per-command budget, which is exactly
+ *   how a hold that passes on a foregrounded tab died with a generic
+ *   "editor connected but did not respond" on a backgrounded one. Microtasks
+ *   are not throttled, so the hidden path now costs sim-work time and nothing
+ *   else.
+ *
+ * The regime is re-read every iteration, so a tab foregrounded (or hidden)
+ * mid-hold crosses over without restarting the budget.
+ *
+ * `hiddenWithoutDriver: true` is the one honest refusal: hidden-paused with
+ * no `driveHiddenTicks` hook means nothing in this process can advance the
+ * clock, so it reports that IMMEDIATELY (see
+ * {@link HOLD_HIDDEN_NO_DRIVER_REASON}) instead of burning the stall guard
+ * and then blaming a stopped game.
+ */
+export async function waitForHoldBudget(
   adapter: DebugAdapter,
   simSeconds: number,
   driveHiddenTicks?: (n: number) => void,
-): Promise<{ stalled: boolean }> {
-  return new Promise((resolve) => {
-    const start = adapter.state('time') as {
-      simSeconds: number;
-      tick: number;
-      loopLiveness?: GameLoopLiveness | null;
-    };
-    let lastTick = start.tick;
-    let stalledPolls = 0;
-    const poll = () => {
-      const current = adapter.state('time') as {
-        simSeconds: number;
-        tick: number;
-        loopLiveness?: GameLoopLiveness | null;
-      };
-      if (current.simSeconds - start.simSeconds >= simSeconds) {
-        resolve({ stalled: false });
-        return;
-      }
-      if (current.loopLiveness === 'hidden-paused' && driveHiddenTicks) {
-        // One poll represents HOLD_FOR_POLL_MS of requested simulation
-        // progress. Keep this deterministic instead of translating scheduler
-        // jitter through a wall-clock read into a different tick count.
-        const ticks = Math.max(1, Math.round(HOLD_FOR_POLL_MS / (1000 / 60)));
-        driveHiddenTicks(ticks);
-        setTimeout(poll, HOLD_FOR_POLL_MS);
-        return;
-      }
-      stalledPolls = current.tick === lastTick ? stalledPolls + 1 : 0;
-      lastTick = current.tick;
-      if (stalledPolls >= HOLD_FOR_STALL_POLL_LIMIT) {
-        resolve({ stalled: true });
-        return;
+): Promise<{ stalled: boolean; hiddenWithoutDriver?: boolean }> {
+  const readTime = () => adapter.state('time') as HoldClockReading;
+  const start = readTime();
+  let lastTick = start.tick;
+  let stalledPolls = 0;
+  let hiddenBatches = 0;
+
+  for (;;) {
+    const current = readTime();
+    if (current.simSeconds - start.simSeconds >= simSeconds) return { stalled: false };
+
+    if (current.loopLiveness === 'hidden-paused') {
+      if (!driveHiddenTicks) return { stalled: true, hiddenWithoutDriver: true };
+      if (hiddenBatches >= HIDDEN_DRIVE_MAX_BATCHES) return { stalled: true };
+      hiddenBatches += 1;
+      driveHiddenTicks(HIDDEN_DRIVE_BATCH_TICKS);
+      const after = readTime();
+      // A batch that moved neither the tick counter nor the sim clock means
+      // the drive is a no-op (paused game, torn-down runtime) — the same
+      // "nothing is advancing" verdict the visible path's stall guard
+      // reaches, just observable in one batch instead of a hundred polls.
+      if (after.tick === current.tick && after.simSeconds === current.simSeconds) {
+        return { stalled: true };
       }
-      setTimeout(poll, HOLD_FOR_POLL_MS);
-    };
-    setTimeout(poll, HOLD_FOR_POLL_MS);
-  });
+      lastTick = after.tick;
+      stalledPolls = 0;
+      // Yield so the page can service other work between batches, WITHOUT
+      // handing control to a clock a hidden tab is allowed to starve.
+      await Promise.resolve();
+      continue;
+    }
+
+    stalledPolls = current.tick === lastTick ? stalledPolls + 1 : 0;
+    lastTick = current.tick;
+    if (stalledPolls >= HOLD_FOR_STALL_POLL_LIMIT) return { stalled: true };
+    await new Promise<void>((resolve) => setTimeout(resolve, HOLD_FOR_POLL_MS));
+  }
 }
 
 function hasRealWindow(): boolean {
@@ -337,7 +390,7 @@ function buildDebugHandle(opts: {
     if (!target) {
       throw new DebugError(
         'DEBUG_INPUT_UNAVAILABLE',
-        `debug bridge: ${method}() has no virtual-input target wired — no default threejs ` +
+        `debug bridge: ${method}() has no virtual-input target wired — no default three ` +
           "world has mounted yet, or this project's mount path never wired one",
       );
     }
@@ -391,7 +444,7 @@ function buildDebugHandle(opts: {
       injectPointerPosition: (sourceId, value, worldId) =>
         requireInputTarget('injectPointerPosition', worldId).injectPointerPosition(sourceId, value),
     },
-    snapshot(sinceTick, sinceSeq) {
+    snapshot(sinceSeq) {
       // One synchronous pass — see VgaiDebugSnapshot's doc comment.
       return {
         time: adapter.state('time') as {
@@ -400,7 +453,7 @@ function buildDebugHandle(opts: {
           loopLiveness: GameLoopLiveness | null;
         },
         state: adapter.stateAll(),
-        events: adapter.events(sinceTick, sinceSeq),
+        events: adapter.events(sinceSeq),
         pageErrors: pageErrors.slice(),
       };
     },
@@ -428,15 +481,17 @@ function buildDebugHandle(opts: {
           : { delivered: false };
       }
       const runTicksTarget = registry.getRunTicksTarget();
-      const { stalled } = await waitForHoldBudget(
+      const { stalled, hiddenWithoutDriver } = await waitForHoldBudget(
         adapter,
         simSeconds,
         runTicksTarget ? (n) => runTicksTarget.runTicks(n, { render: 'last' }) : undefined,
       );
       target.clearVirtualActions();
-      return stalled
-        ? { delivered: false, reason: 'play stopped during hold' }
-        : { delivered: true };
+      if (!stalled) return { delivered: true };
+      return {
+        delivered: false,
+        reason: hiddenWithoutDriver ? HOLD_HIDDEN_NO_DRIVER_REASON : 'play stopped during hold',
+      };
     },
     uninstall() {
       opts.window.removeEventListener?.('error', onWindowError);