@vgai/live 0.5.2 → 0.5.4

package/dist/game-client/fast-forward.js

@@ -0,0 +1,122 @@
+/**
+ * Pure `game.fastForward` batching/accounting math — no Playwright (same
+ * "pure module, Playwright-free" split `wait-for.ts` established, so this
+ * unit-tests headlessly). `client.ts`'s `GameClient.fastForward` is the
+ * thin Playwright-bound wrapper around `runFastForward` below, exactly the
+ * way `GameClient.waitFor` wraps `runWaitFor`.
+ *
+ * The shape: `game.fastForward({simSeconds}|{simTicks})` synchronously
+ * drives the live `Game`'s `runTicks` (through the debug bridge, door (a))
+ * instead of relying on real wall-clock time to pass. Doctrine:
+ * fastForward is for SETUP/STAGING traversal —
+ * reaching a known late-game state fast — not a replacement for real-input
+ * proofs, which still run in real ticks; a scripted/scheduled input sequence
+ * driven THROUGH a fastForward burst is still an honest proof of "what the sim
+ * consumed" (the post-gate recording framing) — fastForward changes
+ * how fast ticks are produced, never what a tick consumes.
+ *
+ * Two honesty decisions this module encodes, both because burst ticks are NOT
+ * ordinary wall-clock-paced simulation and must never be reported as if they
+ * were (the "never fabricate" rule threaded through `perf-sampling.ts`/
+ * `failure-block.ts`):
+ *
+ *  1. **Batching, not one giant `runTicks` call.** A single call driving (say)
+ *     an hour of sim time would (a) block the page's JS thread for the ENTIRE
+ *     burst with zero observable progress, and (b) starve anything watching
+ *     this run's stdout for liveness for however long the burst takes — a
+ *     false "wedged" verdict on a run that was making fine (just silent)
+ *     progress. Batching into `DEFAULT_FAST_FORWARD_BATCH_TICKS`-sized chunks
+ *     with one heartbeat per chunk (`client.ts` prints it) keeps output flowing
+ *     without giving up the speedup — each batch is still driven synchronously
+ *     in-page; only the ROUND TRIP is chunked.
+ *  2. **Burst ticks never feed the ordinary tps stats.** `perf-sampling.ts`'s
+ *     `TpsAccumulator` measures REAL wall-clock throughput between ordinary
+ *     `snapshot()` polls — its whole purpose is "is the game's frame loop
+ *     keeping up in real time." A burst of, say, 1800 ticks completed in
+ *     ~50ms would produce a `~36000 ticks/s` sample that means nothing about
+ *     the game's real per-frame cost, and would silently corrupt the p50/p95
+ *     a genuine stall would otherwise surface in. `client.ts`'s `fastForward`
+ *     therefore drives every batch through a RAW bridge call (bypassing
+ *     `GameClient.snapshot()`'s automatic `TpsAccumulator.record`) and resets
+ *     the accumulator's baseline once the burst completes, so the very next
+ *     ordinary poll starts a fresh "first observation" instead of diffing
+ *     across the burst discontinuity. The whole-TEST `simSpeedRatio` (fixture
+ *     teardown, `perf-sampling.ts`) is NOT protected this way, deliberately:
+ *     it is an honest end-to-end ratio (fence snapshot -> final snapshot),
+ *     not a sampled rate, and showing "this test ran at 400x" when it
+ *     genuinely did IS the correct, undistorted signal. `waitFor` budgets are
+ *     themselves unaffected by any of this — they are still sim-time
+ *     budgets; a `fastForward` immediately before one just leaves less real
+ *     ground for it to cover (sim-time got CHEAPER, not redefined).
+ */
+/** One fixed timestep, matching every real host's loop construction
+ *  (`createGameLoop`'s own `fixedTimestep ?? 1/60` default: "fixedDt = the
+ *  host loop's fixed timestep (1/60)"). Used ONLY as a fallback when a
+ *  `simSeconds` budget needs converting to a tick count before the game has
+ *  ticked even once (nothing observed yet to measure the real fixedDt from) —
+ *  see `ticksForBudget`. */
+export const DEFAULT_FIXED_DT = 1 / 60;
+/** 5 sim-seconds' worth of ticks at the default 60Hz rate — small enough that
+ *  even a complex game's batch finishes well inside a second of real time
+ *  (keeping heartbeats frequent), large enough that round-trip overhead stays
+ *  negligible next to the speedup (module doc, point 1). */
+export const DEFAULT_FAST_FORWARD_BATCH_TICKS = 300;
+/** Converts a `simSeconds` budget into an exact tick count using the game's
+ *  OWN observed `simSeconds`/`tick` ratio — not a hardcoded constant, since a
+ *  project may run a non-default fixed timestep (see `simulate-cinematic`'s
+ *  `vgai-simulate-fixed-dt` precedent); measuring beats assuming. Falls back
+ *  to `DEFAULT_FIXED_DT` only when `observed.tick` is still `0` (nothing to
+ *  measure from yet — a fresh page that hasn't ticked once). A `simTicks`
+ *  budget passes straight through, unaffected by any of this. */
+export function ticksForBudget(budget, observed) {
+    if ('simTicks' in budget) {
+        if (!Number.isInteger(budget.simTicks) || budget.simTicks < 0) {
+            throw new RangeError(`game.fastForward: simTicks must be a non-negative integer, got ${budget.simTicks}`);
+        }
+        return budget.simTicks;
+    }
+    if (!Number.isFinite(budget.simSeconds) || budget.simSeconds < 0) {
+        throw new RangeError(`game.fastForward: simSeconds must be >= 0, got ${budget.simSeconds}`);
+    }
+    const fixedDt = observed.tick > 0 ? observed.simSeconds / observed.tick : DEFAULT_FIXED_DT;
+    return Math.ceil(budget.simSeconds / fixedDt);
+}
+/** Pure batch-size planner: splits `totalTicks` into chunks of at most
+ *  `batchTicks`, the LAST of which may be smaller (never any other position —
+ *  the driver marks exactly the last chunk "final" and applies the caller's
+ *  requested render mode only to it). Empty for `totalTicks <= 0`. */
+export function planFastForwardBatches(totalTicks, batchTicks) {
+    if (totalTicks <= 0)
+        return [];
+    const batches = [];
+    let remaining = totalTicks;
+    while (remaining > 0) {
+        const chunk = Math.min(batchTicks, remaining);
+        batches.push(chunk);
+        remaining -= chunk;
+    }
+    return batches;
+}
+/**
+ * Drives a `fastForward` call against `clock`: converts `budget` to an exact
+ * tick count (`ticksForBudget`), batches it (`planFastForwardBatches`), runs
+ * each batch through `runTicksBatch` (forcing `render: 'none'` on every batch
+ * but the last, which gets `opts.render ?? 'last'`), heartbeats once per
+ * batch, and returns the final observed `{tick, simSeconds}`. See the module
+ * doc for why batching and the render-mode split exist.
+ */
+export async function runFastForward(budget, opts, clock) {
+    const observed = await clock.readTime();
+    const totalTicks = ticksForBudget(budget, observed);
+    const batches = planFastForwardBatches(totalTicks, opts.batchTicks ?? DEFAULT_FAST_FORWARD_BATCH_TICKS);
+    const finalRender = opts.render ?? 'last';
+    let ticksDone = 0;
+    for (let i = 0; i < batches.length; i++) {
+        const size = batches[i];
+        const isFinalBatch = i === batches.length - 1;
+        await clock.runTicksBatch(size, isFinalBatch ? finalRender : 'none');
+        ticksDone += size;
+        clock.heartbeat({ ticksDone, ticksTotal: totalTicks });
+    }
+    return clock.readTime();
+}

package/dist/game-client/hidden-recovery.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 declare 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 declare const initialHiddenRecoveryState: HiddenRecoveryState;
+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 declare function shouldSampleHidden(state: HiddenRecoveryState, tickUnchanged: boolean): boolean;
+/** 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 declare function stepHiddenRecovery(state: HiddenRecoveryState, obs: PollObservation): {
+    state: HiddenRecoveryState;
+    action: HiddenRecoveryAction;
+};
+/** 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 declare function hiddenRecoveryLogLine(tick: number): string;
+/**
+ * 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 declare class HiddenRecoveryDriver {
+    private readonly hooks;
+    private state;
+    private lastTick;
+    private didTrigger;
+    constructor(hooks: HiddenRecoveryHooks);
+    /** True once `bringToFront()` has fired (at most once per driver/test). */
+    wasTriggered(): boolean;
+    observeTick(tick: number): Promise<void>;
+}

package/dist/game-client/hidden-recovery.js

@@ -0,0 +1,105 @@
+/**
+ * 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 const initialHiddenRecoveryState = {
+    stalledPolls: 0,
+    recovered: false,
+};
+/** 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, tickUnchanged) {
+    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, obs) {
+    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' };
+}
+/** Renders the structured recovery line — one stable, greppable shape. */
+export function hiddenRecoveryLogLine(tick) {
+    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 {
+    hooks;
+    state = initialHiddenRecoveryState;
+    lastTick = null;
+    didTrigger = false;
+    constructor(hooks) {
+        this.hooks = hooks;
+    }
+    /** True once `bringToFront()` has fired (at most once per driver/test). */
+    wasTriggered() {
+        return this.didTrigger;
+    }
+    async observeTick(tick) {
+        const tickUnchanged = this.lastTick !== null && tick === this.lastTick;
+        this.lastTick = tick;
+        let hidden;
+        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/dist/game-client/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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/dist/game-client/index.js

@@ -0,0 +1,26 @@
+/**
+ * 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 { BRIDGE_HEARTBEAT_INTERVAL_MS, formatBridgeHeartbeatLine } from './bridge-heartbeat.js';
+export { GameClient, GameEvents, GameInput, PageTransport } from './client.js';
+export { SESSION_ERROR_CODES, SessionError, SessionFailure } from './errors.js';
+export { matchEventsSubsequence } from './events-matcher.js';
+export { DEFAULT_FAST_FORWARD_BATCH_TICKS, DEFAULT_FIXED_DT, planFastForwardBatches, runFastForward, ticksForBudget, } from './fast-forward.js';
+export { HIDDEN_RECOVERY_STALL_POLLS, HiddenRecoveryDriver, hiddenRecoveryLogLine, initialHiddenRecoveryState, shouldSampleHidden, stepHiddenRecovery, } from './hidden-recovery.js';
+export { computeTicksPerSecond, percentile, simSpeedRatio, summarizeTpsSamples, TpsAccumulator, } from './perf-sampling.js';
+export { RelayTransport } from './relay-transport.js';
+export { classifyScreenshotArg, resolveScreenshotTarget, sanitizeScreenshotLabel, } from './screenshot-target.js';
+export { capJson } from './state-cap.js';
+export { assertValidWaitForBudget, WAIT_FOR_STALL_POLL_LIMIT, WAIT_FOR_TIMEOUT_OPTION_MESSAGE, } from './wait-for.js';

package/dist/game-client/perf-sampling.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 declare function computeTicksPerSecond(tickDelta: number, wallDeltaMs: number): number | null;
+/** 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 declare function percentile(sortedAscending: readonly number[], p: number): 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 declare function summarizeTpsSamples(samples: readonly number[]): TpsStats;
+/** 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 declare function simSpeedRatio(simSecondsDelta: number, wallMs: number): number;
+/**
+ * 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 declare class TpsAccumulator {
+    private last;
+    private readonly samples;
+    record(tick: number, wallMs: number): void;
+    /** 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;
+    stats(): TpsStats;
+}

package/dist/game-client/perf-sampling.js

@@ -0,0 +1,85 @@
+/**
+ * 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, wallDeltaMs) {
+    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, p) {
+    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];
+}
+/** 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) {
+    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, wallMs) {
+    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 {
+    last = null;
+    samples = [];
+    record(tick, wallMs) {
+        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() {
+        this.last = null;
+    }
+    stats() {
+        return summarizeTpsSamples(this.samples);
+    }
+}

package/dist/game-client/relay-transport.d.ts

@@ -0,0 +1,100 @@
+/**
+ * #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 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;
+}
+export declare class RelayTransport implements BridgeTransport {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private hiddenDriveLastWallMs;
+    private hiddenDriveAnnounced;
+    private forceHiddenDrive;
+    private hiddenCache;
+    private readonly instance;
+    constructor(opts: RelayTransportOptions);
+    private postCommand;
+    /** 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;
+    private bridgeCall;
+    /**
+     * 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 preflightHidden;
+    /** `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 isHiddenCached;
+    call(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome>;
+    callAsync(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome>;
+    isHidden(): Promise<boolean>;
+    /**
+     * 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`.
+     */
+    bringToFront(): Promise<void>;
+    screenshot(path: string): Promise<void>;
+    /**
+     * 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.
+     */
+    runPageScript(src: string, _step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+}