@vgai/live 0.5.2 → 0.5.4

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

@@ -0,0 +1,237 @@
+/**
+ * #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';
+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 {
+    baseUrl;
+    timeoutMs;
+    hiddenDriveLastWallMs = null;
+    hiddenDriveAnnounced = false;
+    forceHiddenDrive = false;
+    hiddenCache = null;
+    instance;
+    constructor(opts) {
+        this.baseUrl = `http://127.0.0.1:${opts.port}`;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.instance = opts.instance;
+    }
+    async postCommand(body, timeoutMs) {
+        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());
+    }
+    /** 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. */
+    toBridgeOutcome(body) {
+        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,
+            },
+        };
+    }
+    async bridgeCall(method, callArgs, timeoutMs) {
+        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.
+     */
+    async preflightHidden() {
+        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. */
+    async isHiddenCached() {
+        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, callArgs) {
+        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, callArgs) {
+        await this.preflightHidden();
+        return this.bridgeCall(method, callArgs, INVOKE_TIMEOUT_MS);
+    }
+    async isHidden() {
+        try {
+            const res = await fetch(`${this.baseUrl}/__editor/state`, {
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            const state = (await res.json());
+            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() {
+        this.forceHiddenDrive = true;
+    }
+    async screenshot(path) {
+        // 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'], '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']?.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, _step) {
+        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)}`,
+                },
+            };
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Where `GameClient.screenshot(x)` actually writes.
+ *
+ * WHY THIS IS ITS OWN MODULE (measured 2026-08-02, live session):
+ * `game.screenshot('.vgai/tmp/dragon/play-live.png')` — driven through
+ * `vgai eval`, the documented general door onto a running game — reported
+ * success and left NOTHING at the path the caller named. The argument was
+ * being read as a LABEL and run through `sanitizeLabel`, so the bytes landed
+ * at `<project>/.vgai/last-run/001--vgai-tmp-dragon-play-live-png.png`.
+ * Both artifacts are still on disk in the reproduction project. A call that
+ * reports success while the file the caller asked for does not exist is
+ * fabricated evidence — the exact failure mode `vgai screenshot` was built to
+ * prevent, reintroduced one layer down.
+ *
+ * The fix is to honour what the caller wrote. A LABEL ("waitfor-timeout") is
+ * a bare identifier: it keeps the numbered-artifact behaviour every run
+ * depends on. A PATH (anything with a separator, or any name carrying a file
+ * extension) is a destination: it is written EXACTLY there, relative paths
+ * resolved against the process cwd — the same rule `vgai screenshot --out`
+ * already documents.
+ */
+/** A caller's argument, classified. */
+export type ScreenshotArgKind = 'path' | 'label';
+/**
+ * PATH when the argument names a location: absolute, containing a `/` or `\`
+ * separator, an explicit `./`-style relative prefix, or carrying a file
+ * extension (`shot.png`). LABEL otherwise — the bare-identifier form specs
+ * pass (`'waitfor-timeout'`, `'events-expect-failure'`).
+ *
+ * The extension rule is what makes `screenshot('frame.png')` land at
+ * `./frame.png` instead of `.../001-frame-png.png`: a caller who typed an
+ * extension asked for a file, not a caption.
+ */
+export declare function classifyScreenshotArg(arg: string): ScreenshotArgKind;
+/** Non-filename characters collapse to `-` for the label form. */
+export declare function sanitizeScreenshotLabel(label: string): string;
+export interface ScreenshotTargetInput {
+    /** The caller's argument — a label or a path (see {@link classifyScreenshotArg}). */
+    readonly arg: string;
+    /** Artifacts directory for the label form. */
+    readonly artifactsDir: string;
+    /** 1-based ordinal for the label form's `NNN-` prefix. */
+    readonly sequence: number;
+    /** Base for resolving a relative path/artifactsDir — the process cwd. */
+    readonly cwd: string;
+}
+export interface ScreenshotTarget {
+    readonly kind: ScreenshotArgKind;
+    /** Absolute destination. */
+    readonly path: string;
+    /** True when the caller's own ordinal was consumed (label form only), so a
+     *  path-form call never perturbs the numbering of the artifacts around it. */
+    readonly consumedSequence: boolean;
+}
+/**
+ * Resolve the absolute file a screenshot call must write. Pure — no I/O, no
+ * `process.cwd()` read — so the contract above is testable without a browser,
+ * a session, or a filesystem.
+ */
+export declare function resolveScreenshotTarget(input: ScreenshotTargetInput): ScreenshotTarget;

package/dist/game-client/screenshot-target.js

@@ -0,0 +1,68 @@
+/**
+ * Where `GameClient.screenshot(x)` actually writes.
+ *
+ * WHY THIS IS ITS OWN MODULE (measured 2026-08-02, live session):
+ * `game.screenshot('.vgai/tmp/dragon/play-live.png')` — driven through
+ * `vgai eval`, the documented general door onto a running game — reported
+ * success and left NOTHING at the path the caller named. The argument was
+ * being read as a LABEL and run through `sanitizeLabel`, so the bytes landed
+ * at `<project>/.vgai/last-run/001--vgai-tmp-dragon-play-live-png.png`.
+ * Both artifacts are still on disk in the reproduction project. A call that
+ * reports success while the file the caller asked for does not exist is
+ * fabricated evidence — the exact failure mode `vgai screenshot` was built to
+ * prevent, reintroduced one layer down.
+ *
+ * The fix is to honour what the caller wrote. A LABEL ("waitfor-timeout") is
+ * a bare identifier: it keeps the numbered-artifact behaviour every run
+ * depends on. A PATH (anything with a separator, or any name carrying a file
+ * extension) is a destination: it is written EXACTLY there, relative paths
+ * resolved against the process cwd — the same rule `vgai screenshot --out`
+ * already documents.
+ */
+import { isAbsolute, resolve } from 'node:path';
+/**
+ * PATH when the argument names a location: absolute, containing a `/` or `\`
+ * separator, an explicit `./`-style relative prefix, or carrying a file
+ * extension (`shot.png`). LABEL otherwise — the bare-identifier form specs
+ * pass (`'waitfor-timeout'`, `'events-expect-failure'`).
+ *
+ * The extension rule is what makes `screenshot('frame.png')` land at
+ * `./frame.png` instead of `.../001-frame-png.png`: a caller who typed an
+ * extension asked for a file, not a caption.
+ */
+export function classifyScreenshotArg(arg) {
+    if (arg === '')
+        return 'label';
+    if (isAbsolute(arg))
+        return 'path';
+    if (arg.includes('/') || arg.includes('\\'))
+        return 'path';
+    if (/\.[a-zA-Z0-9]{1,8}$/.test(arg))
+        return 'path';
+    return 'label';
+}
+/** Non-filename characters collapse to `-` for the label form. */
+export function sanitizeScreenshotLabel(label) {
+    return label.replace(/[^a-zA-Z0-9-_]+/g, '-');
+}
+/**
+ * Resolve the absolute file a screenshot call must write. Pure — no I/O, no
+ * `process.cwd()` read — so the contract above is testable without a browser,
+ * a session, or a filesystem.
+ */
+export function resolveScreenshotTarget(input) {
+    const kind = classifyScreenshotArg(input.arg);
+    if (kind === 'path') {
+        const withExtension = /\.[a-zA-Z0-9]{1,8}$/.test(input.arg) ? input.arg : `${input.arg}.png`;
+        return {
+            kind,
+            path: isAbsolute(withExtension) ? withExtension : resolve(input.cwd, withExtension),
+            consumedSequence: false,
+        };
+    }
+    const fileName = `${String(input.sequence).padStart(3, '0')}-${sanitizeScreenshotLabel(input.arg)}.png`;
+    const dir = isAbsolute(input.artifactsDir)
+        ? input.artifactsDir
+        : resolve(input.cwd, input.artifactsDir);
+    return { kind, path: resolve(dir, fileName), consumedSequence: true };
+}

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

@@ -0,0 +1,7 @@
+/** Byte-capping for the failure block's "last state" member (Task 3.3: never
+ *  elided, byte-capped at 4KB, truncation always marked). */
+export interface CappedJson {
+    text: string;
+    truncated: boolean;
+}
+export declare function capJson(value: unknown, maxBytes?: number): CappedJson;

package/dist/game-client/state-cap.js

@@ -0,0 +1,21 @@
+/** Byte-capping for the failure block's "last state" member (Task 3.3: never
+ *  elided, byte-capped at 4KB, truncation always marked). */
+const TRUNCATION_MARKER = '\n… [truncated to fit the 4KB cap]';
+export function capJson(value, maxBytes = 4096) {
+    const full = JSON.stringify(value, null, 2) ?? 'undefined';
+    if (byteLength(full) <= maxBytes) {
+        return { text: full, truncated: false };
+    }
+    const budget = Math.max(maxBytes - byteLength(TRUNCATION_MARKER), 0);
+    let text = full;
+    // Binary-search-free shrink: strings only grow bytes via multi-byte UTF-8,
+    // so a length-proportional slice converges in a handful of iterations.
+    while (byteLength(text) > budget && text.length > 0) {
+        const ratio = budget / byteLength(text);
+        text = text.slice(0, Math.max(Math.floor(text.length * ratio), 0));
+    }
+    return { text: text + TRUNCATION_MARKER, truncated: true };
+}
+function byteLength(text) {
+    return new TextEncoder().encode(text).length;
+}

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

@@ -0,0 +1,128 @@
+/**
+ * The frozen shape of `window.__vgai`, the in-page debug bridge installed by
+ * the engine (`packages/engine/src/runtime/debug-bridge.ts`, Task 2.1 —
+ * landing concurrently with this package). This module declares that shape
+ * independently; it never imports the engine package, so this package can be
+ * built and tested independently of the bridge's landing.
+ */
+export type ValueTier = 'observable' | 'assisted';
+export interface ProviderInfo {
+    name: string;
+    tier: ValueTier;
+}
+export interface DebugCommandInfo {
+    name: string;
+    description?: string;
+    argsJsonSchema?: unknown;
+    locus: 'client' | 'server';
+}
+/** Run-4 friction #5: `seq` is a registry-lifetime monotonic counter (never
+ *  reset, never shared by two events — unlike `tick`, which a debug-command
+ *  emission and a fenced consumer's snapshot can legitimately collide on).
+ *  Mirrors `@vgai/engine`'s `TickStampedEvent` (`adapter/system-adapter.ts`)
+ *  — this package never imports the engine (see the module doc above), so
+ *  the shape is declared here from the same contract. */
+export interface TickStampedEvent {
+    tick: number;
+    simT: number;
+    event: string;
+    detail?: unknown;
+    seq: number;
+}
+export type VirtualActionValue = boolean | number | {
+    x: number;
+    y: number;
+};
+export interface VirtualActionResult {
+    delivered: boolean;
+    reason?: string;
+}
+export interface DebugBridgeInput {
+    setVirtualAction(action: string, value: VirtualActionValue): VirtualActionResult;
+    tapVirtualAction(action: string): VirtualActionResult;
+    clearVirtualActions(): void;
+    /** D15/T-D15.5 — schedule a virtual actuation for a specific tick, applied
+     *  at the start of that tick's input phase. Declared here (Wave-2
+     *  bridge↔wire coverage-parity gate) for type-shape completeness with
+     *  `runtime/debug-bridge.ts`'s `VgaiDebugInputHandle` — this package still
+     *  exposes no client-side convenience wrapper around it (deliberately
+     *  parked; see `GameInput` in `client.ts`), this is pure type-shape
+     *  mirroring. */
+    scheduleActionAtTick(tick: number, action: string, value: VirtualActionValue): void;
+    /** Wave-2 pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
+     *  `VgaiDebugInputHandle.injectPointerDelta`: accumulates a synthetic
+     *  pointer delta for a named test source (sums within a frame, clears each
+     *  frame). Declared here for type-shape completeness with the bridge, same
+     *  precedent as `scheduleActionAtTick` above — no client-side convenience
+     *  wrapper in `client.ts` (deliberately parked). */
+    injectPointerDelta(sourceId: string, delta: {
+        x: number;
+        y: number;
+    }): void;
+    /** Wave-2 pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
+     *  `VgaiDebugInputHandle.injectPointerPosition`: sets a synthetic absolute
+     *  pointer position for a named test source (last-write-wins, persists
+     *  until changed). Same type-shape-only precedent as `scheduleActionAtTick`. */
+    injectPointerPosition(sourceId: string, value: {
+        x: number;
+        y: number;
+    }): void;
+}
+/** D15/T-D15.4 door (a) — `Game.runTicks`'s options, mirrored from the
+ *  engine's own `runtime/debug-registry.ts` `RunTicksOptions` (this package
+ *  never imports the engine — see the module doc above — so the shape is
+ *  declared here from the build plan's/D15 doc's contract text, same as
+ *  every other bridge member). */
+export interface RunTicksOptions {
+    render?: 'last' | 'all' | 'none';
+}
+/** One coherent read of the whole bridge — `snapshot()` is the fixture's poll
+ *  primitive: every field comes from the same synchronous pass. */
+export interface DebugSnapshot {
+    time: {
+        simSeconds: number;
+        tick: number;
+        /**
+         * Issue #175 — the REAL engine `GameLoop.liveness` behind this session
+         * (mirrors `@vgai/engine`'s `GameLoopLiveness`; this package never
+         * imports the engine — see the module doc above — so the union is
+         * declared here from the same contract). `'hidden-paused'` means the
+         * T2.1 idle throttle has stopped the loop because the tab is
+         * backgrounded: `simSeconds`/`tick` above are frozen, but this is NOT a
+         * crashed/wedged game — it resumes the instant the tab is foregrounded.
+         * `undefined` against an older bridge build that predates this field;
+         * `null` when the live bridge has no loop wired at all (should not
+         * happen against a real `Game`, but never fabricated either way).
+         */
+        loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null;
+    };
+    state: Record<string, unknown>;
+    events: TickStampedEvent[];
+    pageErrors: string[];
+}
+/** `window.__vgai`'s shape (version 1, frozen — see the build plan's ground
+ *  rule 4). */
+export interface VgaiBridgeHandle {
+    version: 1;
+    providers(): ProviderInfo[];
+    state(name: string): unknown;
+    stateAll(): Record<string, unknown>;
+    commands(): DebugCommandInfo[];
+    invoke(name: string, args: unknown[]): Promise<unknown>;
+    /** Run-4 friction #5: `sinceSeq`, when given, fences on
+     *  `TickStampedEvent.seq` (unambiguous — see that field's doc comment). The
+     *  old `sinceTick` fence (`tick > sinceTick`, which dropped any event
+     *  sharing the fence's own tick) was REMOVED. */
+    events(sinceSeq?: number): TickStampedEvent[];
+    input: DebugBridgeInput;
+    snapshot(sinceSeq?: number): DebugSnapshot;
+    /** D15/T-D15.4 — see `RunTicksOptions`'s doc comment above. */
+    runTicks(n: number, opts?: RunTicksOptions): void;
+    /** Collapses `input.setVirtualAction(action, true)` → wait `simSeconds` of
+     *  sim time (host-loop ticks while visible, deterministic same-phase ticks
+     *  while hidden-paused) → `input.clearVirtualActions()` into one call — see
+     *  `runtime/debug-bridge.ts`'s
+     *  `holdFor` doc comment for the full contract (gated-immediately /
+     *  play-stopped-mid-wait shapes). */
+    holdFor(action: string, simSeconds: number, worldId?: string): Promise<VirtualActionResult>;
+}

package/dist/game-client/types.js

@@ -0,0 +1,15 @@
+/**
+ * The frozen shape of `window.__vgai`, the in-page debug bridge installed by
+ * the engine (`packages/engine/src/runtime/debug-bridge.ts`, Task 2.1 —
+ * landing concurrently with this package). This module declares that shape
+ * independently; it never imports the engine package, so this package can be
+ * built and tested independently of the bridge's landing.
+ */
+export {};
+// Deliberately no `declare global { interface Window { __vgai } }` here:
+// the engine's own debug-bridge module (landing concurrently) is the real
+// installer and may declare its own global augmentation for `window.__vgai`.
+// Two independent ambient declarations of the same global member are only
+// safe if structurally identical, and this package must not assume that —
+// every access reaches through an explicit `window as { __vgai?: ... }` cast
+// at the `page.evaluate()` boundary instead (see client.ts).