@vgai/live 0.5.2 → 0.5.3

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

@@ -0,0 +1,75 @@
+/**
+ * The transport seam `GameClient` (`client.ts`) drives (#140). Two
+ * implementations answer the identical contract below:
+ *  - `PageTransport` (`client.ts`) — Playwright's `page.evaluate` against
+ *    `window.__vgai`, for a standalone game page the caller drives itself.
+ *  - `RelayTransport` (`relay-transport.ts`) — the editor dev-server's
+ *    session wire (`POST /__editor/command`, `bridge-call`/
+ *    `bridge-screenshot` ops), driving the SAME live session a human already
+ *    has open, with no new browser/window/vite instance.
+ *
+ * `wait-for.ts`/`events-matcher.ts`/`failure-block.ts`, and every method
+ * body on `GameClient` itself, are written against this interface only —
+ * none of them may know or care which transport is underneath (load-bearing
+ * for a planned default flip to relay-when-a-live-session-exists, and for a
+ * future one-shot REPL client reusing the same relay op). Deliberately NO
+ * `@playwright/test` import here, nor in `relay-transport.ts` — only
+ * `client.ts` is allowed to touch a live `Page` (see its own module doc).
+ */
+/** Result of one generic bridge-method call — thrown page/relay-side errors
+ *  never cross either transport boundary AS themselves (Node only keeps
+ *  `.message` across `page.evaluate`; HTTP/JSON strips everything but what
+ *  the server explicitly serializes), so both transports catch and report
+ *  `code`/`data` explicitly, and `GameClient.unwrap` reconstructs a
+ *  `SessionError` from that. */
+export interface BridgeCallOutcome {
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        code: string | undefined;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface BridgeTransport {
+    /** Sync-style bridge call (state/stateAll/providers/commands/events/
+     *  snapshot/runTicks/input.*) — "sync-style" describes the PAGE side's own
+     *  call, not this method, which is always async across either wire. */
+    call(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome>;
+    /** Async bridge call — `invoke` (debug commands may themselves be async). */
+    callAsync(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome>;
+    /** Whether the surface showing the game is currently hidden from the user
+     *  (`document.hidden` on the page transport) — feeds `HiddenRecoveryDriver`. */
+    isHidden(): Promise<boolean>;
+    /** Bring the surface showing the game to the foreground. */
+    bringToFront(): Promise<void>;
+    /** Capture a screenshot to `path` (PNG). A transport that cannot support
+     *  this should reject with a descriptive error rather than write a blank/
+     *  corrupt file. */
+    screenshot(path: string): Promise<void>;
+    /**
+     * Wave-2 "one dialect, full capability" — runs a UI-automation step
+     * written as a literal `async (page) => {...}` (`GameClient.page()`,
+     * `client.ts`). `src` is `step.toString()`; `step` is the ORIGINAL
+     * function, wrapped so its own parameter type is erased to `unknown` (only
+     * `client.ts` — the one file allowed to touch a real `Page` — ever names
+     * the `Page` type itself).
+     *
+     * The two implementations differ ON PURPOSE, and that difference is the
+     * load-bearing honesty boundary this method exists to name:
+     *  - `PageTransport` (`client.ts`) calls `step` DIRECTLY against the real
+     *    Playwright `Page` — no serialization, so closures over outer Node
+     *    values work here exactly like any ordinary `page.evaluate` callback.
+     *  - `RelayTransport` (`relay-transport.ts`) ships `src` over the wire and
+     *    reconstructs it with `new Function` INSIDE the editor page, against
+     *    an in-page shim (`packages/editor/src/playwright-shim.ts`) — closure
+     *    capture over anything outside the step's own body does NOT survive
+     *    that trip (the same limitation class as Playwright's own `evaluate`
+     *    serialization).
+     *
+     * Because the two transports differ this way, specs meant to pass
+     * unmodified under both hosts must be written as though ALWAYS
+     * serialized — inline every value the step needs.
+     */
+    runPageScript(src: string, step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+}

package/dist/game-client/bridge-transport.js

@@ -0,0 +1,19 @@
+/**
+ * The transport seam `GameClient` (`client.ts`) drives (#140). Two
+ * implementations answer the identical contract below:
+ *  - `PageTransport` (`client.ts`) — Playwright's `page.evaluate` against
+ *    `window.__vgai`, for a standalone game page the caller drives itself.
+ *  - `RelayTransport` (`relay-transport.ts`) — the editor dev-server's
+ *    session wire (`POST /__editor/command`, `bridge-call`/
+ *    `bridge-screenshot` ops), driving the SAME live session a human already
+ *    has open, with no new browser/window/vite instance.
+ *
+ * `wait-for.ts`/`events-matcher.ts`/`failure-block.ts`, and every method
+ * body on `GameClient` itself, are written against this interface only —
+ * none of them may know or care which transport is underneath (load-bearing
+ * for a planned default flip to relay-when-a-live-session-exists, and for a
+ * future one-shot REPL client reusing the same relay op). Deliberately NO
+ * `@playwright/test` import here, nor in `relay-transport.ts` — only
+ * `client.ts` is allowed to touch a live `Page` (see its own module doc).
+ */
+export {};

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

@@ -0,0 +1,293 @@
+/**
+ * The Playwright-page-bound wiring for `game`'s client methods (D17: specs
+ * drive `window.__vgai` via `page.evaluate` — the standalone page has no HTTP
+ * channel). This module is deliberately the ONLY place that touches `Page`;
+ * the budget math (`wait-for.ts`), the events matcher (`events-matcher.ts`),
+ * and the failure-block assembler (`failure-block.ts`) are plain modules
+ * that never import Playwright, per Task 3.2's architecture requirement.
+ */
+import type { Page } from '@playwright/test';
+import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
+import { type FastForwardBudget, type FastForwardOptions } from './fast-forward.js';
+import { type TpsStats } from './perf-sampling.js';
+import type { DebugCommandInfo, DebugSnapshot, ProviderInfo, VirtualActionValue } from './types.js';
+import { type WaitForBudget } from './wait-for.js';
+/**
+ * #140 — the `BridgeTransport` `page.evaluate` implementation. This is the
+ * ONE place a `Page` is ever touched to drive `window.__vgai` (module doc
+ * above); `RelayTransport` (`relay-transport.ts`) is the sibling
+ * implementation for the live editor session, and imports no Playwright at
+ * all. Exported so `fixture.ts` (which already imports `@playwright/test`
+ * for its own `page.goto`/error-listener setup) can construct one.
+ */
+export declare class PageTransport implements BridgeTransport {
+    private readonly page;
+    constructor(page: Page);
+    call(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome>;
+    callAsync(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome>;
+    isHidden(): Promise<boolean>;
+    bringToFront(): Promise<void>;
+    screenshot(path: string): Promise<void>;
+    /** Wave-2: the ONE transport that runs a `game.page()` step against a REAL
+     *  Playwright `Page` — no serialization, so `step`'s own closures work
+     *  here (see `bridge-transport.ts`'s `runPageScript` doc comment for the
+     *  full honesty-boundary contract; `src` is unused on this leg, kept only
+     *  to satisfy the shared interface). */
+    runPageScript(_src: string, step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+}
+export interface GameClientOptions {
+    /** The bridge transport — `new PageTransport(page)` for a standalone page
+     *  (`fixture.ts`), `new RelayTransport({ port })` for `--in-editor`
+     *  (`relay-fixture.ts`). See `bridge-transport.ts`'s module doc: every
+     *  method below reaches `window.__vgai` (or its relay-side equivalent)
+     *  ONLY through this seam. */
+    transport: BridgeTransport;
+    /** Populated by the fixture's `pageerror` listener, installed before goto. */
+    pageErrors: string[];
+    /** Populated by the fixture's `console` listener (type `'error'`), same timing. */
+    consoleErrors: string[];
+    /** First snapshot's `time.tick` — used only for `events.expect`'s
+     *  `withinTicks` timing math (`events-matcher.ts`) and the D5 failure-block
+     *  deltas below; identity fencing itself is `fenceSeq`'s job (run-4
+     *  friction #5 — see that field's doc comment). */
+    fenceTick: number;
+    /** Run-4 friction #5: the fence snapshot's own event ring's last `seq`
+     *  (`0` if the ring was empty at fence time — nothing emitted yet, so
+     *  "since seq 0" is correct). `events.expect` fences on THIS, not
+     *  `fenceTick` — the removed `tick > sinceTick` filter silently dropped any event that
+     *  shares the fence's own tick (e.g. one emitted from a debug-command
+     *  handler, which runs between ticks), which is exactly the bug this field
+     *  closes. See `debug-registry.ts`'s `TickStampedEvent.seq` doc comment
+     *  for the full mechanism. */
+    fenceSeq: number;
+    /** D5: first snapshot's `time.simSeconds` — `events.expect`'s failure block
+     *  computes REAL elapsed sim-time as a delta off this, instead of the
+     *  absolute (since-boot) `simSeconds` the pre-fix code passed. */
+    fenceSimSeconds: number;
+    /** D5: `Date.now()` at the same moment as the fence snapshot — the wall
+     *  side of that same delta, instead of the pre-fix code's hardcoded `0`
+     *  (which fabricated a "sim speed 0.00x — loop stalled" reading on every
+     *  single `events.expect` failure, regardless of how the game was
+     *  actually running). */
+    fenceWallMs: number;
+    artifactsDir?: string | undefined;
+    /** Set by the caller when it reused an already-running game server rather
+     *  than booting a fresh one for this run. Threaded through so `unwrap` can
+     *  append the warm-session staleness hint to a
+     *  `DEBUG_COMMAND_NOT_REGISTERED` failure (see `errors.ts`'s
+     *  `appendWarmSessionHint`). Defaults to `false` so every caller that never
+     *  sets it is unaffected. */
+    warmSession?: boolean;
+    /** `testInfo.title` — names the fixture heartbeat lines `waitFor`/
+     *  `waitSimTime` print during a long poll (see `wait-for.ts`'s module doc).
+     *  Defaults to `'test'` so a caller that never sets it (existing direct
+     *  `GameClient` construction in older tests) still gets a valid, if
+     *  generic, heartbeat line rather than `undefined` in the output. */
+    testTitle?: string;
+}
+export declare class GameInput {
+    private readonly client;
+    constructor(client: GameClient);
+    /**
+     * Holds one action, or SIMULTANEOUSLY holds several — `hold('jump')` and
+     * `hold(['move_right', 'move_forward'])` (the natural way to drive a
+     * diagonal) are both first-class. `action` is deliberately typed as
+     * `string | string[]`, never just `string`: a bare JS array silently
+     * stringifies to a comma-joined name (`['move_right','move_forward']` →
+     * `"move_right,move_forward"`) wherever it crosses a template literal or
+     * the bridge's JSON boundary, which used to surface as a baffling
+     * `unknown action "move_right,move_forward"` — the array was accepted
+     * structurally (nothing rejected it) and then silently mangled instead.
+     * Accepting the array for real, instead of merely rejecting it, is the
+     * useful behavior: every 2D/3D mover needs "hold two directions at once"
+     * as its ordinary case, not an edge case.
+     *
+     * Single action: one `holdFor` bridge call (`runtime/debug-bridge.ts`)
+     * instead of the old set → `waitSimTime`'s 150ms-interval snapshot poll
+     * loop → clear (15+ transport round trips over the editor relay for a
+     * multi-second hold). The wait uses ordinary host-loop ticks while visible.
+     * If the browser has hidden-paused that loop, the bridge drives the held
+     * action through the same game phases with deterministic ticks; this
+     * collapses transport cost without letting a background tab deadlock it.
+     *
+     * A relay call has a bounded async-invoke timeout budget (see
+     * `relay-transport.ts`'s `INVOKE_TIMEOUT_MS`) — a `simSeconds` long enough
+     * to exceed it at worst-case sim speed is NOT silently truncated; the
+     * transport timeout is caught and rethrown with a hint to split the hold
+     * into multiple shorter `hold()` calls instead.
+     *
+     * Multiple actions: `holdFor` is a single-action bridge primitive, so this
+     * presses every action (`setVirtualAction(action, true)`, in order),
+     * waits the shared `simSeconds` once via `waitSimTime`, and releases every
+     * action it managed to press — in a `finally`, so a gated press (a
+     * `delivered: false` result throws `INPUT_GATED` immediately) or a stalled
+     * clock during the wait still leaves no action stuck held.
+     */
+    hold(action: string | string[], budget: {
+        simSeconds: number;
+    }): Promise<void>;
+    /**
+     * Keep one or more honest game actions pressed while `observe` runs, then
+     * release every action in a `finally` block. This is the evidence-oriented
+     * sibling of {@link hold}: `hold()` resolves after release, which is ideal
+     * for asserting distance travelled but cannot capture a moving pose or read
+     * transient "currently sprinting" state. `whileHeld()` makes that interval
+     * explicit without asking tests to hand-roll unsafe set/clear cleanup.
+     *
+     * The callback uses the same `GameClient` instance already in the test, so
+     * it may call `game.waitFor`, `game.state`, `game.screenshot`, or any other
+     * ordinary observation. No state is fabricated and the actions still enter
+     * through `input.setVirtualAction`/the project's real input map.
+     */
+    whileHeld<T>(action: string | string[], observe: () => T | Promise<T>): Promise<T>;
+    /**
+     * One honest one-shot press — pressed, carried through AT LEAST ONE FULL
+     * FIXED TICK, then released, as a single bridge call.
+     *
+     * The contract is deliberately "a tick services it", not "the bridge
+     * accepted it", because the raw primitive underneath (`InputManager.
+     * tapVirtualAction`) only QUEUES: `poll()` promotes the queue to that tick's
+     * just-pressed set, and nothing else ever does. On a visible tab a tick
+     * lands ~16ms later so the difference is invisible; on a HIDDEN tab the host
+     * loop is stopped outright, so a queue-only tap sat unserviced and then died
+     * — silently, having already reported `delivered: true` (measured:
+     * `input.trace: { ticks: [] }`, no event, while `whileHeld` on the same
+     * action worked every time). Routing through the `holdFor` primitive is what
+     * makes the press TICK-ALIGNED by construction: that call owns the wait, and
+     * its hidden-tab leg drives the tick deterministically
+     * (`runtime/debug-bridge.ts`'s `waitForHoldBudget`), so a tap can no longer
+     * fall between ticks on any transport or any tab state.
+     *
+     * A gated action still fails loudly and immediately with `INPUT_GATED`,
+     * exactly as {@link hold} does — same `delivered:false` contract, same
+     * error.
+     */
+    tap(action: string): Promise<void>;
+    /**
+     * Sets one action, or the SAME value on several at once — same
+     * `string | string[]` shape as {@link hold}, and for the same reason: a
+     * bare array used to silently stringify into a single bogus action name
+     * instead of being rejected or honored.
+     */
+    set(action: string | string[], value: VirtualActionValue): Promise<void>;
+}
+export declare class GameEvents {
+    private readonly client;
+    constructor(client: GameClient);
+    expect(names: string[], opts?: {
+        exact?: boolean;
+        withinTicks?: number;
+    }): Promise<void>;
+}
+/**
+ * The `game` fixture value. Every method reaches `window.__vgai` (or its
+ * relay-side equivalent) through `this.#transport` — see `bridge-transport.ts`'s
+ * module doc for the seam, and this file's own module doc for why it, alone,
+ * is allowed to import Playwright (via `PageTransport`, above).
+ */
+export declare class GameClient {
+    #private;
+    readonly input: GameInput;
+    readonly events: GameEvents;
+    readonly fenceTick: number;
+    /** Run-4 friction #5: see `GameClientOptions.fenceSeq`. */
+    readonly fenceSeq: number;
+    /** D5: see `GameClientOptions.fenceSimSeconds`. */
+    readonly fenceSimSeconds: number;
+    /** D5: see `GameClientOptions.fenceWallMs`. */
+    readonly fenceWallMs: number;
+    readonly pageErrors: string[];
+    readonly consoleErrors: string[];
+    /** M13: hidden-tab recovery's own structured notices — kept SEPARATE from
+     *  `consoleErrors` (see `hidden-recovery.ts`'s hook below and
+     *  `failure-block.ts`'s `recoveryNotices` member). */
+    readonly recoveryNotices: string[];
+    /** Where a labelled `screenshot()` lands — project-scoped by `@vgai/live`, cwd-relative otherwise. Public: a caller reading it is asking a fair question, and `screenshot()` returns a path under it anyway. */
+    readonly artifactsDir: string;
+    constructor(opts: GameClientOptions);
+    state(name: string): Promise<unknown>;
+    command(name: string, ...args: unknown[]): Promise<unknown>;
+    providers(): Promise<ProviderInfo[]>;
+    commands(): Promise<DebugCommandInfo[]>;
+    snapshot(sinceSeq?: number): Promise<DebugSnapshot>;
+    /** Fixture-teardown perf read: p50/p95 effective ticks-per-second over all
+     *  the snapshot polls this test performed. */
+    tpsStats(): TpsStats;
+    /** True if the hidden-tab recovery fired (page.bringToFront was called). */
+    hiddenRecoveryTriggered(): boolean;
+    /**
+     * D15/T-D15.4 — synchronously drives `budget` worth of sim time/ticks via
+     * the live `Game`'s `runTicks` (through the debug bridge), instead of
+     * waiting for real wall-clock time to pass. Doctrine (see
+     * `fast-forward.ts`'s module doc, which also documents the two honesty
+     * decisions this wraps): SETUP/STAGING traversal — reaching a known
+     * late-game state fast — not a substitute for real-input proofs, which
+     * still run in real ticks. Returns the final `{time, state, events,
+     * pageErrors}` snapshot (a completely ordinary `snapshot()` read, taken
+     * AFTER the tps baseline reset below, so it never itself corrupts the tps
+     * stats either).
+     */
+    fastForward(budget: FastForwardBudget, opts?: FastForwardOptions): Promise<DebugSnapshot>;
+    waitFor(pred: (s: (name: string) => unknown) => boolean, budget: WaitForBudget): Promise<void>;
+    /** Used by `input.hold` — waits for a sim-time delta to pass with no
+     *  predicate (a predicate that is never true would misreport as a
+     *  waitFor failure, so this is its own tiny loop, not `runWaitFor` with a
+     *  false predicate).
+     *
+     *  D2: this loop has the SAME frozen-clock bug `runWaitFor` had — with no
+     *  predicate at all, a stalled sim clock would poll forever, since
+     *  `current.time.simSeconds` would never advance. Carries the identical
+     *  stall guard (`WAIT_FOR_STALL_POLL_LIMIT` consecutive polls with an
+     *  unchanged tick — see wait-for.ts's doc comment for the rationale),
+     *  throwing the same `WaitForTimeoutError` shape so it renders through the
+     *  same honest failure block as an ordinary `waitFor`/`waitSimTime` budget
+     *  exhaustion. */
+    waitSimTime(budget: {
+        simSeconds: number;
+    }): Promise<void>;
+    /**
+     * Capture the running game to disk and return the ABSOLUTE path written.
+     *
+     * `labelOrPath` is read as a LABEL when it is a bare identifier
+     * (`'waitfor-timeout'`) — numbered into the artifacts directory, the
+     * long-standing spec behaviour — and as a DESTINATION PATH the moment it
+     * carries a separator or a file extension, in which case the bytes land
+     * exactly there (relative to `process.cwd()`). See
+     * `screenshot-target.ts`'s header for the live incident that made this
+     * distinction mandatory: a caller naming a path used to get "success" and
+     * an empty path.
+     */
+    screenshot(labelOrPath: string): Promise<string>;
+    /**
+     * Wave-2 "one dialect, full capability" — runs a UI-automation step
+     * written as a literal Playwright `async (page) => {...}` (interface
+     * doctrine §3.2/§4 rung 4: "the AI should think it is basically just
+     * executing Playwright"). Under `PageTransport` this drives the REAL
+     * `Page` (real closures, real hit-testing); under `RelayTransport` it
+     * posts the step's own `toString()` source to the editor dev server's
+     * `page-script` op, which reconstructs it in-page against
+     * `playwright-shim.ts`'s in-page shim (`isTrusted: false` synthetic
+     * DOM events, no real hit testing). This is the honest input path for a
+     * React-only DOM game; canvas gameplay continues to use `game.input.*`.
+     * Write specs as if ALWAYS serialized — inline every value the step needs,
+     * never close over imported `expect`/helpers/outer variables, and return
+     * observations to assert outside the callback. See `bridge-transport.ts`'s
+     * `runPageScript` doc comment for the full contract this method wraps.
+     */
+    page<T = unknown>(step: (page: Page) => T | Promise<T>): Promise<T>;
+    private toSessionFailure;
+    /** run-3 friction #2 — called at the top of every bridge dispatch, before
+     *  the await, so a burst of short calls (e.g. many `hold()`s) keeps
+     *  printing throttled liveness even while individually near-silent. See
+     *  bridge-heartbeat.ts's module doc for why this needs no sim-tick
+     *  awareness the way `wait-for.ts`'s poll-loop heartbeat does. */
+    private emitBridgeHeartbeatIfDue;
+    /** @internal exposed for GameInput/GameEvents in this module only. */
+    callBridge<T>(method: string, ...callArgs: unknown[]): Promise<T>;
+    /** @internal like `callBridge`, but awaits the page-side call (for async
+     *  bridge methods like `invoke`). */
+    callBridgeAsync<T>(method: string, ...callArgs: unknown[]): Promise<T>;
+    /** @internal void-returning convenience (clearVirtualActions). */
+    callBridgeVoid(method: string, ...callArgs: unknown[]): Promise<void>;
+    private unwrap;
+}