@vgai/live 0.5.2 → 0.5.3

package/src/game-client/hidden-recovery.ts

@@ -0,0 +1,149 @@
+/**
+ * Hidden-tab recovery — pure decision logic, ported from hollowstone's field
+ * lessons (the engine hard-stops its loop while `document.hidden`, and a
+ * backgrounded tab therefore looks identical to a genuinely stalled
+ * game). No Playwright import here: `client.ts`'s `GameClient.snapshot()` —
+ * the one read every `waitFor`/`waitSimTime` poll already performs — feeds a
+ * `HiddenRecoveryDriver` one tick observation per poll, and only the
+ * caller-supplied hooks (wired up in `client.ts`, the one file allowed to
+ * touch a live `Page`) perform the actual `page.evaluate('document.hidden')`
+ * sample and `page.bringToFront()` call. Unit tests feed the same driver
+ * scripted hooks/observations instead.
+ *
+ * Contract (deliberately narrow): after `HIDDEN_RECOVERY_STALL_POLLS`
+ * consecutive polls with an unmoved sim tick, sample `document.hidden` once
+ * per poll until it reads `true`, then call `bringToFront()` EXACTLY ONCE
+ * (the `recovered` flag latches shut) and keep polling — no wall-clock
+ * timeout is added here or anywhere downstream. If the clock stays frozen
+ * after recovery, the normal `runWaitFor` sim-time budget exhausts and
+ * throws `WaitForTimeoutError` as it always would; that failure block's
+ * ~0x sim-speed ratio is what diagnoses a still-stalled loop, not this
+ * module reacting a second time.
+ */
+
+export const HIDDEN_RECOVERY_STALL_POLLS = 10;
+
+export interface HiddenRecoveryState {
+  /** Consecutive polls (so far) where the sim tick has not advanced. */
+  stalledPolls: number;
+  /** Latches true the moment `bringToFront` has fired once — never resets,
+   *  even if the tick later moves and then stalls again, per "once". */
+  recovered: boolean;
+}
+
+export const initialHiddenRecoveryState: HiddenRecoveryState = {
+  stalledPolls: 0,
+  recovered: false,
+};
+
+export interface PollObservation {
+  /** True when this poll's snapshot tick equals the previous poll's tick. */
+  tickUnchanged: boolean;
+  /** `document.hidden`, sampled by the caller — only meaningful (and only
+   *  ever sampled by real callers) once `shouldSampleHidden` says so;
+   *  `undefined` means "not sampled this poll". */
+  hidden?: boolean | undefined;
+}
+
+export type HiddenRecoveryAction = 'none' | 'bring-to-front';
+
+/** Whether THIS poll's caller should bother sampling `document.hidden` at
+ *  all — an efficiency guard so a healthy, moving game never pays an extra
+ *  `page.evaluate()` per poll. True only once the stall threshold is about
+ *  to be (or has been) reached, the tick is (still) unchanged, and recovery
+ *  hasn't already fired. */
+export function shouldSampleHidden(state: HiddenRecoveryState, tickUnchanged: boolean): boolean {
+  if (state.recovered || !tickUnchanged) return false;
+  return state.stalledPolls + 1 >= HIDDEN_RECOVERY_STALL_POLLS;
+}
+
+/** One pure transition. Called once per `runWaitFor` poll with the previous
+ *  state and this poll's observation; returns the next state plus the
+ *  action the caller should take. */
+export function stepHiddenRecovery(
+  state: HiddenRecoveryState,
+  obs: PollObservation,
+): { state: HiddenRecoveryState; action: HiddenRecoveryAction } {
+  if (!obs.tickUnchanged) {
+    return { state: { stalledPolls: 0, recovered: state.recovered }, action: 'none' };
+  }
+  const stalledPolls = state.stalledPolls + 1;
+  if (state.recovered || obs.hidden !== true) {
+    return { state: { stalledPolls, recovered: state.recovered }, action: 'none' };
+  }
+  if (stalledPolls >= HIDDEN_RECOVERY_STALL_POLLS) {
+    return { state: { stalledPolls, recovered: true }, action: 'bring-to-front' };
+  }
+  return { state: { stalledPolls, recovered: false }, action: 'none' };
+}
+
+/** The page-facing side effects the driver needs, injected so this module
+ *  never imports Playwright (`client.ts` supplies the real ones; tests
+ *  supply scripted fakes). */
+export interface HiddenRecoveryHooks {
+  /** Real implementation: `page.evaluate(() => document.hidden)`. */
+  sampleHidden(): Promise<boolean> | boolean;
+  /** Real implementation: `page.bringToFront()`. */
+  bringToFront(): Promise<void> | void;
+  /** Real implementation: `console.log(line)` + push onto the client's
+   *  console-errors collection so the line also surfaces in an eventual
+   *  failure block's console-errors section. */
+  log(line: string): void;
+}
+
+/** Renders the structured recovery line — one stable, greppable shape. */
+export function hiddenRecoveryLogLine(tick: number): string {
+  return (
+    `vgai: hidden-tab recovery — sim tick frozen at ${tick} for ` +
+    `${HIDDEN_RECOVERY_STALL_POLLS} consecutive polls while document.hidden=true; ` +
+    'calling page.bringToFront() once'
+  );
+}
+
+/**
+ * Stateful wrapper over the pure transition above, fed one tick observation
+ * per poll (`GameClient.snapshot()` calls `observeTick` on every read). All
+ * side effects go through the injected hooks; a hook failure (page already
+ * closed, say) is swallowed — a recovery attempt must never be what fails a
+ * test.
+ */
+export class HiddenRecoveryDriver {
+  private state: HiddenRecoveryState = initialHiddenRecoveryState;
+  private lastTick: number | null = null;
+  private didTrigger = false;
+
+  constructor(private readonly hooks: HiddenRecoveryHooks) {}
+
+  /** True once `bringToFront()` has fired (at most once per driver/test). */
+  wasTriggered(): boolean {
+    return this.didTrigger;
+  }
+
+  async observeTick(tick: number): Promise<void> {
+    const tickUnchanged = this.lastTick !== null && tick === this.lastTick;
+    this.lastTick = tick;
+
+    let hidden: boolean | undefined;
+    if (shouldSampleHidden(this.state, tickUnchanged)) {
+      try {
+        hidden = await this.hooks.sampleHidden();
+      } catch {
+        hidden = undefined;
+      }
+    }
+
+    const { state, action } = stepHiddenRecovery(this.state, { tickUnchanged, hidden });
+    this.state = state;
+
+    if (action === 'bring-to-front') {
+      this.didTrigger = true;
+      this.hooks.log(hiddenRecoveryLogLine(tick));
+      try {
+        await this.hooks.bringToFront();
+      } catch {
+        // Same rule as sampleHidden: never let the recovery attempt itself
+        // throw into a spec — the sim-time budget remains the only failure.
+      }
+    }
+  }
+}

package/src/game-client/index.ts

@@ -0,0 +1,98 @@
+/**
+ * The game-control client `@vgai/live` binds as `game`: a `GameClient` over a
+ * `BridgeTransport`, plus the pure logic it is built from (wait budgets, event
+ * matching, failure blocks, fast-forward planning, hidden-tab recovery, perf
+ * sampling, screenshot-target resolution).
+ *
+ * Two transports answer the same seam (`bridge-transport.ts`): `RelayTransport`
+ * drives a live `vgai edit` session over the editor dev server's wire — the one
+ * `@vgai/live` itself uses — and `PageTransport` drives a Playwright `Page`
+ * directly, for a caller that owns its own browser. Every method body on
+ * `GameClient` is written against the seam, never against either transport.
+ *
+ * This barrel exists so `../index.ts` re-exports one coherent surface instead of
+ * a dozen sibling paths; nothing here imports anything from `../`.
+ */
+
+export type { BridgeHeartbeatState } from './bridge-heartbeat.js';
+export { BRIDGE_HEARTBEAT_INTERVAL_MS, formatBridgeHeartbeatLine } from './bridge-heartbeat.js';
+export type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
+export type { GameClientOptions } from './client.js';
+export { GameClient, GameEvents, GameInput, PageTransport } from './client.js';
+export type { SessionErrorCode } from './errors.js';
+export { SESSION_ERROR_CODES, SessionError, SessionFailure } from './errors.js';
+export type { EventsMatchOptions, EventsMatchResult } from './events-matcher.js';
+export { matchEventsSubsequence } from './events-matcher.js';
+export type {
+  AssembledFailureBlock,
+  FailureBlockContext,
+  SessionFailureData,
+} from './failure-block.js';
+export type {
+  FastForwardBudget,
+  FastForwardClock,
+  FastForwardOptions,
+  FastForwardRenderMode,
+  FastForwardTime,
+} from './fast-forward.js';
+export {
+  DEFAULT_FAST_FORWARD_BATCH_TICKS,
+  DEFAULT_FIXED_DT,
+  planFastForwardBatches,
+  runFastForward,
+  ticksForBudget,
+} from './fast-forward.js';
+export type {
+  HiddenRecoveryAction,
+  HiddenRecoveryHooks,
+  HiddenRecoveryState,
+  PollObservation,
+} from './hidden-recovery.js';
+export {
+  HIDDEN_RECOVERY_STALL_POLLS,
+  HiddenRecoveryDriver,
+  hiddenRecoveryLogLine,
+  initialHiddenRecoveryState,
+  shouldSampleHidden,
+  stepHiddenRecovery,
+} from './hidden-recovery.js';
+export type { TpsStats } from './perf-sampling.js';
+export {
+  computeTicksPerSecond,
+  percentile,
+  simSpeedRatio,
+  summarizeTpsSamples,
+  TpsAccumulator,
+} from './perf-sampling.js';
+export type { RelayTransportOptions } from './relay-transport.js';
+export { RelayTransport } from './relay-transport.js';
+export type {
+  ScreenshotArgKind,
+  ScreenshotTarget,
+  ScreenshotTargetInput,
+} from './screenshot-target.js';
+export {
+  classifyScreenshotArg,
+  resolveScreenshotTarget,
+  sanitizeScreenshotLabel,
+} from './screenshot-target.js';
+export type { CappedJson } from './state-cap.js';
+export { capJson } from './state-cap.js';
+export type {
+  DebugBridgeInput,
+  DebugCommandInfo,
+  DebugSnapshot,
+  ProviderInfo,
+  RunTicksOptions,
+  TickStampedEvent,
+  ValueTier,
+  VgaiBridgeHandle,
+  VirtualActionResult,
+  VirtualActionValue,
+} from './types.js';
+export type { WaitForBudget } from './wait-for.js';
+export {
+  assertValidWaitForBudget,
+  WAIT_FOR_STALL_POLL_LIMIT,
+  WAIT_FOR_TIMEOUT_OPTION_MESSAGE,
+} from './wait-for.js';

package/src/game-client/perf-sampling.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure per-test perf math — no Playwright. Two independent measures:
+ *  1. Sim-speed ratio for the whole test (`simSpeedRatio`) — the same
+ *     sim-seconds/wall-seconds ratio `failure-block.ts` renders on a
+ *     timeout, computed instead between the fixture's fence snapshot and a
+ *     final snapshot taken at teardown, regardless of whether the test
+ *     passed or failed.
+ *  2. Effective ticks-per-second, sampled cheaply off polls `game.waitFor`
+ *     was already doing (no extra `page.evaluate()` round trips): each poll
+ *     contributes one `(tickDelta / wallDeltaMs)` sample, and this module
+ *     summarizes the accumulated samples as p50/p95.
+ */
+
+/** One poll's instantaneous ticks-per-second, or `null` when `wallDeltaMs`
+ *  is non-positive (first poll / a clock with sub-millisecond resolution) —
+ *  callers should simply skip a `null` sample rather than recording it. */
+export function computeTicksPerSecond(tickDelta: number, wallDeltaMs: number): number | null {
+  if (wallDeltaMs <= 0) return null;
+  return (tickDelta / wallDeltaMs) * 1000;
+}
+
+/** Nearest-rank percentile (1-indexed rank `ceil(p/100 * n)`, clamped into
+ *  range) over an ALREADY-SORTED-ASCENDING array. `0` on an empty input. */
+export function percentile(sortedAscending: readonly number[], p: number): number {
+  const n = sortedAscending.length;
+  if (n === 0) return 0;
+  const rank = Math.min(n, Math.max(1, Math.ceil((p / 100) * n)));
+  return sortedAscending[rank - 1] as number;
+}
+
+export interface TpsStats {
+  p50: number;
+  p95: number;
+  sampleCount: number;
+}
+
+/** Summarizes raw ticks-per-second samples (any order) into p50/p95 +
+ *  count. `{ p50: 0, p95: 0, sampleCount: 0 }` when there are no samples
+ *  (a test that never called `game.waitFor` — honestly reported as zero
+ *  samples, never fabricated). */
+export function summarizeTpsSamples(samples: readonly number[]): TpsStats {
+  const sorted = [...samples].sort((a, b) => a - b);
+  return {
+    p50: percentile(sorted, 50),
+    p95: percentile(sorted, 95),
+    sampleCount: sorted.length,
+  };
+}
+
+/** Whole-test sim-speed ratio: sim-seconds elapsed over wall-seconds
+ *  elapsed. `0` when `wallMs` is non-positive (mirrors `failure-block.ts`'s
+ *  own `ratioLine` degrade-to-zero rule for a zero/negative denominator). */
+export function simSpeedRatio(simSecondsDelta: number, wallMs: number): number {
+  return wallMs > 0 ? simSecondsDelta / (wallMs / 1000) : 0;
+}
+
+/**
+ * Accumulates one tick-rate sample per snapshot read. `GameClient.snapshot()`
+ * calls `record(tick, wallNowMs)` on every read it was already doing (waitFor
+ * polls, waitSimTime polls, explicit snapshots) — no extra `page.evaluate()`
+ * round trips. The first observation only seeds the baseline; a NEGATIVE
+ * tick delta (a page reload reset the sim clock) reseeds rather than
+ * recording a nonsense sample; a zero tick delta IS recorded (0 ticks/s is
+ * the honest "loop frozen" signal the summary exists to surface).
+ */
+export class TpsAccumulator {
+  private last: { tick: number; wallMs: number } | null = null;
+  private readonly samples: number[] = [];
+
+  record(tick: number, wallMs: number): void {
+    const last = this.last;
+    this.last = { tick, wallMs };
+    if (last === null) return;
+    const tickDelta = tick - last.tick;
+    if (tickDelta < 0) return;
+    const tps = computeTicksPerSecond(tickDelta, wallMs - last.wallMs);
+    if (tps !== null) this.samples.push(tps);
+  }
+
+  /** D15: forgets the baseline (not the accumulated samples) — the NEXT
+   *  `record()` call becomes a fresh "first observation" (seeds only, no
+   *  sample), exactly like the very first `record()` this accumulator ever
+   *  sees. `client.ts`'s `fastForward` calls this right after a burst of
+   *  `runTicks`, so the burst's enormous tick delta over a near-zero wall
+   *  delta is never diffed into a nonsense tps sample (`fast-forward.ts`'s
+   *  module doc, point 2) — real per-poll sampling simply resumes from here. */
+  resetBaseline(): void {
+    this.last = null;
+  }
+
+  stats(): TpsStats {
+    return summarizeTpsSamples(this.samples);
+  }
+}

package/src/game-client/relay-transport.ts

@@ -0,0 +1,311 @@
+/**
+ * #140 — drives `window.__vgai` through the editor dev-server's SESSION WIRE
+ * (`POST /__editor/command`, the same relay `vgai play`/`vgai select`/every
+ * other `EditorClient` method already uses — see `command-listener.ts`'s
+ * `bridge-call`/`bridge-screenshot` cases, the server-side half) instead of
+ * Playwright's `page.evaluate` (`client.ts`'s `PageTransport`). Used by
+ * `vgai eval`: the script drives the game INSIDE the already-open editor tab
+ * a human is watching, with zero new browser windows and zero extra vite
+ * instances.
+ *
+ * The `bridge-call` op is a session-generic primitive (see
+ * `command-listener.ts`'s `dispatchBridgeMethod` doc comment) — this
+ * transport issues one HTTP round trip per call and carries no state beyond
+ * the port, so it (or a sibling built the same way) is equally usable by a
+ * one-shot CLI/REPL call, not just a whole scripted run.
+ *
+ * Deliberately imports nothing from `@playwright/test` — see
+ * `bridge-transport.ts`'s module doc for why that matters (no browser launch
+ * anywhere in this path).
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
+
+export interface RelayTransportOptions {
+  /** The live editor session's dev-server port (e.g. from
+   *  `findLiveEditorSession`/`vgai edit`). */
+  port: number;
+  /** Per-call fetch timeout, ms — default covers an ordinary sync-style
+   *  bridge call; `callAsync` (debug `invoke`, which may run arbitrary game
+   *  code) gets its own longer budget regardless of this override, see
+   *  `INVOKE_TIMEOUT_MS`. */
+  timeoutMs?: number;
+  /**
+   * WHICH mounted game these calls address, when the editor has more than one.
+   *
+   * Omitted is the single-player case and stays the default: the browser
+   * resolves the sole live instance. With several mounted it REFUSES rather
+   * than guessing (`systemsForInstance`), because the dangerous failure there
+   * is not an error — it is success on the wrong game, with every log line
+   * reading fine.
+   *
+   * Rides on `bridge-call` only. A screenshot captures the page, not an
+   * instance, and `page-script` reaches the page itself.
+   */
+  instance?: string;
+}
+
+/** The `/__editor/command` wire shape for a relayed command — see
+ *  `commandResponseFor` (`packages/editor/server/server-utils.ts`): `data`'s
+ *  fields are spread at the TOP level of the JSON body, not nested — this
+ *  interface reflects that verbatim, it is not a transcription error. */
+interface RelayCommandBody {
+  ok: boolean;
+  error?: string;
+  result?: unknown;
+  code?: string;
+  [key: string]: unknown;
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** `invoke` dispatches to arbitrary game-registered debug commands — give it
+ *  real headroom rather than the ordinary sync-call budget above. */
+const INVOKE_TIMEOUT_MS = 60_000;
+const SCREENSHOT_TIMEOUT_MS = 15_000;
+/** A `page-script` step may itself poll (`locator.waitFor`) — give it the
+ *  same headroom as `invoke` rather than the ordinary sync-call budget. */
+const PAGE_SCRIPT_TIMEOUT_MS = 60_000;
+
+/** How long one `/__editor/state` visibility sample stays good for. Short
+ *  enough that foregrounding the tab mid-run is noticed almost immediately,
+ *  long enough that the per-leg preflight doesn't double a bot's request
+ *  count. */
+const HIDDEN_SAMPLE_TTL_MS = 500;
+
+export class RelayTransport implements BridgeTransport {
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  private hiddenDriveLastWallMs: number | null = null;
+  private hiddenDriveAnnounced = false;
+  private forceHiddenDrive = false;
+  private hiddenCache: { hidden: boolean; atMs: number } | null = null;
+  private readonly instance: string | undefined;
+
+  constructor(opts: RelayTransportOptions) {
+    this.baseUrl = `http://127.0.0.1:${opts.port}`;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.instance = opts.instance;
+  }
+
+  private async postCommand(
+    body: Record<string, unknown>,
+    timeoutMs: number,
+  ): Promise<RelayCommandBody> {
+    const res = await fetch(`${this.baseUrl}/__editor/command`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return (await res.json()) as RelayCommandBody;
+  }
+
+  /** Maps the relay's wire body back onto the transport-neutral
+   *  `BridgeCallOutcome` — `result` on success, `code`/`error`/the rest of
+   *  `data` on failure. This is the exact property the round-trip unit test
+   *  proves: `code`/`data` survive byte-equivalent to `PageTransport`'s own
+   *  `unwrap()` path. */
+  private toBridgeOutcome(body: RelayCommandBody): BridgeCallOutcome {
+    if (body.ok) return { ok: true, result: body.result };
+    const { ok: _ok, error, code, result: _result, ...rest } = body;
+    return {
+      ok: false,
+      error: {
+        code,
+        message: error ?? 'unknown relay error',
+        data: Object.keys(rest).length > 0 ? rest : undefined,
+      },
+    };
+  }
+
+  private async bridgeCall(
+    method: string,
+    callArgs: unknown[],
+    timeoutMs: number,
+  ): Promise<BridgeCallOutcome> {
+    try {
+      // `instance` is OMITTED, not sent as undefined, when unset: the wire
+      // body is JSON, and an explicit `"instance": null` would have to be
+      // distinguished from absence on the far side for no gain.
+      const body = await this.postCommand(
+        {
+          type: 'bridge-call',
+          method,
+          callArgs,
+          ...(this.instance !== undefined ? { instance: this.instance } : {}),
+        },
+        timeoutMs,
+      );
+      return this.toBridgeOutcome(body);
+    } catch (err) {
+      // Never hang, never throw across the transport boundary — a relay
+      // that's unreachable (no editor connected, server gone, timeout) is
+      // reported the same structured way an in-page bridge-not-installed
+      // failure is (see `client.ts`'s `bridgeCallInPage`).
+      return {
+        ok: false,
+        error: {
+          code: 'RELAY_UNREACHABLE',
+          message:
+            `vgai: could not reach the editor dev server relay at ${this.baseUrl} — ` +
+            `${err instanceof Error ? err.message : String(err)}`,
+        },
+      };
+    }
+  }
+
+  /**
+   * The PREFLIGHT every leg shares: sample the tab's visibility (through the
+   * short TTL cache above) and, the first time it reads hidden, say so ONCE on
+   * stdout in a stable, greppable line naming the cause and the fix.
+   *
+   * It runs on every leg, not just `call('snapshot')`, because that is where
+   * the measured gap was: a bot that drives the game with `hold`/`command` and
+   * reads through them — the shape `npm run playtest` actually has — could run
+   * its entire session against a backgrounded tab and never be told, so a
+   * later failure read as a generic relay timeout instead of "your tab is
+   * hidden". Returns whether the tab is hidden so `call` can decide whether to
+   * also drive ticks.
+   */
+  private async preflightHidden(): Promise<boolean> {
+    const hidden = this.forceHiddenDrive || (await this.isHiddenCached());
+    if (hidden && !this.hiddenDriveAnnounced) {
+      this.hiddenDriveAnnounced = true;
+      process.stdout.write(
+        'vgai: the editor tab is HIDDEN — the engine hidden-pauses its loop while the tab ' +
+          'is backgrounded, so this run drives deterministic runTicks through the session relay. ' +
+          'Bring the editor tab to the foreground for real-time play.\n',
+      );
+    }
+    return hidden;
+  }
+
+  /** `isHidden()` is an HTTP round trip; the preflight now runs on every leg,
+   *  so a short TTL keeps that from multiplying a bot's request count while
+   *  still reacting to a tab the human foregrounds mid-run. */
+  private async isHiddenCached(): Promise<boolean> {
+    const now = Date.now();
+    if (this.hiddenCache && now - this.hiddenCache.atMs < HIDDEN_SAMPLE_TTL_MS) {
+      return this.hiddenCache.hidden;
+    }
+    const hidden = await this.isHidden();
+    this.hiddenCache = { hidden, atMs: now };
+    return hidden;
+  }
+
+  async call(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome> {
+    const hidden = await this.preflightHidden();
+    if (method === 'snapshot') {
+      if (hidden) {
+        const now = Date.now();
+        const elapsed =
+          this.hiddenDriveLastWallMs === null ? 1000 / 60 : now - this.hiddenDriveLastWallMs;
+        this.hiddenDriveLastWallMs = now;
+        const ticks = Math.max(1, Math.min(30, Math.round(elapsed / (1000 / 60))));
+        const driven = await this.bridgeCall(
+          'runTicks',
+          [ticks, { render: 'last' }],
+          this.timeoutMs,
+        );
+        if (!driven.ok) return driven;
+      } else {
+        this.hiddenDriveLastWallMs = null;
+        this.forceHiddenDrive = false;
+      }
+    }
+    return this.bridgeCall(method, callArgs, this.timeoutMs);
+  }
+
+  async callAsync(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome> {
+    await this.preflightHidden();
+    return this.bridgeCall(method, callArgs, INVOKE_TIMEOUT_MS);
+  }
+
+  async isHidden(): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.baseUrl}/__editor/state`, {
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+      const state = (await res.json()) as {
+        presence?: { visibility?: string; focused?: boolean } | null;
+      };
+      return state.presence?.visibility === 'hidden';
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * A relay cannot foreground a person's browser tab. If the generic hidden
+   * recovery driver reaches this hook, force the same deterministic stepping
+   * path `call('snapshot')` normally activates from `/__editor/state`.
+   */
+  async bringToFront(): Promise<void> {
+    this.forceHiddenDrive = true;
+  }
+
+  async screenshot(path: string): Promise<void> {
+    // Same preflight as every other leg — a hidden tab's canvas is a provably
+    // stale frame, and `refreshHiddenFrame` is what asks the relay for a
+    // deterministic one-tick refresh instead of a `BRIDGE_SCREENSHOT_STALE`
+    // refusal (`command-listener.ts`'s `handleBridgeScreenshot`).
+    const body = await this.postCommand(
+      {
+        type: 'bridge-screenshot',
+        refreshHiddenFrame: await this.preflightHidden(),
+        // Address THIS transport's instance so a per-seat `game.instance(id)`
+        // screenshot captures that seat's game stack, not always the primary.
+        ...(this.instance !== undefined ? { instance: this.instance } : {}),
+      },
+      SCREENSHOT_TIMEOUT_MS,
+    );
+    if (!body.ok || typeof body['base64'] !== 'string') {
+      throw new Error(
+        `vgai: screenshot unavailable — ${body.error ?? 'no play-mode canvas to capture'}`,
+      );
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, Buffer.from(body['base64'] as string, 'base64'));
+    // `game.screenshot()` hands back a path, so a near-blank frame is
+    // indistinguishable from a good one until somebody opens the file — which
+    // is exactly how two probes cited blank captures as evidence. The page
+    // wrote the sentence; say it where the caller is looking.
+    const warning = (body['flatness'] as { warning?: string } | undefined)?.warning;
+    if (typeof warning === 'string') console.warn(`vgai screenshot: warning — ${warning}`);
+    if (body['hiddenFrame'] === true) {
+      console.warn(
+        `vgai screenshot: ${path} is a HIDDEN FRAME — the editor tab is hidden, so the runtime ` +
+          'rendered one deterministic tick on demand. It is current, not stale; it is not a ' +
+          'frame anyone was watching.',
+      );
+    }
+  }
+
+  /**
+   * Wave-2: ships `src` (`step.toString()`) to the editor dev server's
+   * `page-script` op — a STANDALONE relay command (like `bridge-screenshot`
+   * above), not a `bridge-call` method (see `command-listener.ts`'s
+   * `handlePageScript` doc comment for why). `step` itself is unused on this
+   * leg — closures don't survive the wire, see `bridge-transport.ts`'s
+   * `runPageScript` doc comment — kept only to satisfy the shared interface
+   * `PageTransport` (which DOES call it directly) also implements.
+   */
+  async runPageScript(src: string, _step: (page: unknown) => unknown): Promise<BridgeCallOutcome> {
+    try {
+      const body = await this.postCommand({ type: 'page-script', src }, PAGE_SCRIPT_TIMEOUT_MS);
+      return this.toBridgeOutcome(body);
+    } catch (err) {
+      return {
+        ok: false,
+        error: {
+          code: 'RELAY_UNREACHABLE',
+          message:
+            `vgai: could not reach the editor dev server relay at ${this.baseUrl} — ` +
+            `${err instanceof Error ? err.message : String(err)}`,
+        },
+      };
+    }
+  }
+}