@vgai/live 0.5.2 → 0.5.4

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

@@ -0,0 +1,155 @@
+/**
+ * Pure `game.waitFor` budget math — no Playwright, no browser. Polls a
+ * caller-supplied snapshot source and evaluates a predicate against ONE
+ * batched read per iteration (AC-B1.2: a predicate reading two providers
+ * mutated between polls never sees a mixed frame). Kept separate from
+ * `client.ts`'s Playwright wiring so it unit-tests headlessly (Task 3.2's
+ * architecture requirement).
+ */
+import type { DebugSnapshot } from './types.js';
+export type WaitForBudget = {
+    simSeconds: number;
+} | {
+    simTicks: number;
+};
+/** Byte-exact per Task 3.2 item: `waitFor`'s options type has no `timeout`
+ *  key; this is the runtime guard for the mistake weaker models make anyway. */
+export declare const WAIT_FOR_TIMEOUT_OPTION_MESSAGE = "waitFor takes { simSeconds } \u2014 budgets are sim-time (the game may run at 0.3x wall speed under SwiftShader); there is no wall-clock timeout here";
+/**
+ * The teaching message for a budget passed POSITIONALLY —
+ * `game.waitSimTime(0.5)` instead of `game.waitSimTime({ simSeconds: 0.5 })`.
+ *
+ * That call used to be accepted in silence and was measured (blind build
+ * probe, 2026-08-06) doing the worst possible thing: `0.5` has no
+ * `simSeconds`, so the loop compares an elapsed delta against `undefined`,
+ * which is false forever. Against a HIDDEN tab — where the client drives
+ * deterministic ticks itself, so the frozen-clock stall guard never fires —
+ * the call simply never returns. Nothing is printed, nothing errors, and the
+ * caller is left with a wait that has nothing to do with their game.
+ *
+ * `describeBudgetArgument` names what actually arrived, because the whole
+ * failure is that the argument LOOKS reasonable.
+ */
+export declare function positionalBudgetMessage(method: string, budget: unknown): string;
+/** Throws (not merely a type error) if `budget` is not an options object at
+ *  all, is missing both recognized keys, or carries a `timeout` key. Called
+ *  before any polling starts. `method` names the call in the message, because
+ *  this guard now fronts several of them (`waitFor`, `waitSimTime`,
+ *  `fastForward`, `input.hold`) and an error naming the wrong one sends the
+ *  reader to the wrong line.
+ *  M8: throws the package's own `SessionError` carrying the frozen
+ *  `WAIT_FOR_INVALID_BUDGET` code (not a bare `Error`) — every failure this
+ *  package throws must carry a machine-readable code (see errors.ts's module
+ *  doc); a bare `Error` here was the one place that rule was broken. */
+export declare function assertValidWaitForBudget(budget: unknown, method?: string): asserts budget is WaitForBudget;
+/** Sim-time delta the budget measures, `current` relative to `start`. */
+export declare function budgetElapsed(budget: WaitForBudget, start: DebugSnapshot, current: DebugSnapshot): number;
+export declare function budgetTarget(budget: WaitForBudget): number;
+export declare function budgetUnitLabel(budget: WaitForBudget): 'sim-seconds' | 'sim-ticks';
+/** Binds a snapshot to the synchronous `s(name)` reader predicates use, and
+ *  (optionally) records which provider names the predicate actually read —
+ *  the failure block's "assisted-tier consumed" header flag needs this. */
+export declare function makeStateReader(snapshot: DebugSnapshot, touched?: Set<string>): (name: string) => unknown;
+/** Everything the failure-block assembler needs about a timed-out waitFor.
+ *  Deliberately does not know about providers/screenshots/console errors —
+ *  those are gathered by the caller (client.ts) after catching this. */
+export interface WaitForTimeoutInfo {
+    budget: WaitForBudget;
+    startSnapshot: DebugSnapshot;
+    lastSnapshot: DebugSnapshot;
+    wallElapsedMs: number;
+    predicateSource: string;
+    touchedProviders: string[];
+}
+export declare class WaitForTimeoutError extends Error {
+    readonly info: WaitForTimeoutInfo;
+    constructor(info: WaitForTimeoutInfo);
+}
+/** The clock/snapshot source `runWaitFor` polls against. Real usage (from
+ *  `client.ts`) supplies a real `sleep`/`now` and a `snapshot()` that calls
+ *  through to the page's bridge; tests supply scripted fakes. */
+export interface WaitForClock {
+    snapshot(): Promise<DebugSnapshot> | DebugSnapshot;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    pollIntervalMs?: number;
+    /**
+     * Test-only safety valve bounding the number of polls, so a scripted
+     * "stalled" fake source terminates deterministically in unit tests.
+     * Real callers MUST leave this undefined: production `waitFor` has no
+     * internal wall-clock bound by design (the build plan forbids a
+     * wall-clock timeout PARAMETER) — a genuinely stalled game is instead
+     * caught by the outer harness (Playwright's own per-test timeout, or the
+     * caller's own outer budget), not by this
+     * module.
+     */
+    maxPolls?: number | undefined;
+    /** Real callers: `console.log`. Tests: a capturing fake, so heartbeat
+     *  assertions never depend on stdout spies. Defaults to a no-op so a
+     *  clock fixture that doesn't care about heartbeats needn't supply one. */
+    log?: (line: string) => void;
+}
+export declare const HEARTBEAT_INTERVAL_MS = 60000;
+/** Mutable-by-replacement heartbeat bookkeeping a caller threads through
+ *  successive `maybeHeartbeat` calls — never mutated in place, so a test can
+ *  freely compare successive states. */
+export interface HeartbeatState {
+    lastEmitWallMs: number;
+    lastEmitTick: number;
+}
+/** The liveness line this prints to stdout — greppable, and
+ *  stable so a human tailing a long run can `grep vgai-heartbeat`. */
+export declare function formatHeartbeatLine(testTitle: string, simSeconds: number, tick: number): string;
+/**
+ * Pure decision, called once per poll: should a heartbeat print now, and
+ * what's the updated bookkeeping? See the module-doc invariant above — both
+ * the wall-silence budget AND tick advancement (since the last EMITTED
+ * heartbeat, not the last poll) must hold. Returns the SAME `state` object
+ * (referentially) when nothing should emit, so a caller can cheaply no-op.
+ */
+export declare function maybeHeartbeat(opts: {
+    nowMs: number;
+    tick: number;
+    simSeconds: number;
+    testTitle: string;
+    state: HeartbeatState;
+}): {
+    line: string | null;
+    state: HeartbeatState;
+};
+/**
+ * D2: a real internal stall guard, always active (unlike `maxPolls` above,
+ * which is a test-only seam real callers must leave unset). The bug this
+ * fixes: `budgetElapsed` (above) is computed from `current.time.simSeconds`/
+ * `.tick` — if the game's sim clock freezes entirely (the loop itself is
+ * stalled, not merely backgrounded), those fields never change, so
+ * `budgetElapsed` stays at 0 FOREVER and the budget itself can never
+ * exhaust — contradicting hidden-recovery.ts's own doc comment, which
+ * assumes `runWaitFor`'s sim-time budget is what eventually diagnoses a
+ * still-stalled loop after `HiddenRecoveryDriver` has had its one
+ * `bringToFront()` chance.
+ *
+ * 200 consecutive polls with an utterly unchanged tick, at the default
+ * 150ms poll interval, is ~30s of real wall time — comfortably (20x) past
+ * `HIDDEN_RECOVERY_STALL_POLLS`'s ~1.5s window (hidden-recovery.ts), so a
+ * merely-backgrounded tab has already had its recovery chance well before
+ * this guard would ever fire. If the tick is STILL frozen after that much
+ * wall time, the game loop itself is stalled (not the tab), and this guard
+ * throws the same `WaitForTimeoutError` an ordinary budget exhaustion would
+ * — the failure block renders honestly, with its ~0x sim-speed ratio and
+ * "if ~0x, the loop is stalled" hint (failure-block.ts), rather than the
+ * caller hanging forever.
+ */
+export declare const WAIT_FOR_STALL_POLL_LIMIT = 200;
+/**
+ * Polls `clock.snapshot()` until `pred` is true or `budget` is exhausted.
+ * Each iteration reads exactly one snapshot (AC-B1.2). On exhaustion throws
+ * `WaitForTimeoutError` carrying everything `client.ts` needs to assemble
+ * the full failure block.
+ *
+ * `testTitle` (defaults to `'test'` for callers that don't have one — every
+ * REAL caller, `client.ts`'s `waitFor`, always supplies the real Playwright
+ * test title) names the fixture heartbeat lines this loop emits — see the
+ * module doc above `maybeHeartbeat` for the emission invariant.
+ */
+export declare function runWaitFor(pred: (s: (name: string) => unknown) => boolean, budget: WaitForBudget, clock: WaitForClock, testTitle?: string): Promise<DebugSnapshot>;

package/dist/game-client/wait-for.js

@@ -0,0 +1,229 @@
+/**
+ * Pure `game.waitFor` budget math — no Playwright, no browser. Polls a
+ * caller-supplied snapshot source and evaluates a predicate against ONE
+ * batched read per iteration (AC-B1.2: a predicate reading two providers
+ * mutated between polls never sees a mixed frame). Kept separate from
+ * `client.ts`'s Playwright wiring so it unit-tests headlessly (Task 3.2's
+ * architecture requirement).
+ */
+import { SESSION_ERROR_CODES, SessionError } from './errors.js';
+/** Byte-exact per Task 3.2 item: `waitFor`'s options type has no `timeout`
+ *  key; this is the runtime guard for the mistake weaker models make anyway. */
+export const WAIT_FOR_TIMEOUT_OPTION_MESSAGE = 'waitFor takes { simSeconds } — budgets are sim-time (the game may run at 0.3x wall speed under SwiftShader); there is no wall-clock timeout here';
+/**
+ * The teaching message for a budget passed POSITIONALLY —
+ * `game.waitSimTime(0.5)` instead of `game.waitSimTime({ simSeconds: 0.5 })`.
+ *
+ * That call used to be accepted in silence and was measured (blind build
+ * probe, 2026-08-06) doing the worst possible thing: `0.5` has no
+ * `simSeconds`, so the loop compares an elapsed delta against `undefined`,
+ * which is false forever. Against a HIDDEN tab — where the client drives
+ * deterministic ticks itself, so the frozen-clock stall guard never fires —
+ * the call simply never returns. Nothing is printed, nothing errors, and the
+ * caller is left with a wait that has nothing to do with their game.
+ *
+ * `describeBudgetArgument` names what actually arrived, because the whole
+ * failure is that the argument LOOKS reasonable.
+ */
+export function positionalBudgetMessage(method, budget) {
+    return (`game.${method} takes an OPTIONS OBJECT and got ${describeBudgetArgument(budget)} — ` +
+        'a positional budget is not read at all, so the wait never completes on its own. ' +
+        `Write it as: game.${method}({ simSeconds: 0.5 })  (or { simTicks: 30 }). ` +
+        'Every binding and call in scope: vgai eval --list');
+}
+/** What actually arrived, for `positionalBudgetMessage` — a short, honest
+ *  rendering rather than `[object Object]`/`undefined` ambiguity. */
+function describeBudgetArgument(budget) {
+    if (budget === null)
+        return 'null';
+    if (budget === undefined)
+        return 'no argument';
+    if (Array.isArray(budget))
+        return `an array (${JSON.stringify(budget)})`;
+    return `the ${typeof budget} ${JSON.stringify(budget) ?? String(budget)}`;
+}
+/** Throws (not merely a type error) if `budget` is not an options object at
+ *  all, is missing both recognized keys, or carries a `timeout` key. Called
+ *  before any polling starts. `method` names the call in the message, because
+ *  this guard now fronts several of them (`waitFor`, `waitSimTime`,
+ *  `fastForward`, `input.hold`) and an error naming the wrong one sends the
+ *  reader to the wrong line.
+ *  M8: throws the package's own `SessionError` carrying the frozen
+ *  `WAIT_FOR_INVALID_BUDGET` code (not a bare `Error`) — every failure this
+ *  package throws must carry a machine-readable code (see errors.ts's module
+ *  doc); a bare `Error` here was the one place that rule was broken. */
+export function assertValidWaitForBudget(budget, method = 'waitFor') {
+    const isObject = !!budget && typeof budget === 'object';
+    if (!isObject) {
+        throw new SessionError(SESSION_ERROR_CODES.WAIT_FOR_INVALID_BUDGET, positionalBudgetMessage(method, budget));
+    }
+    if ('timeout' in budget) {
+        throw new SessionError(SESSION_ERROR_CODES.WAIT_FOR_INVALID_BUDGET, WAIT_FOR_TIMEOUT_OPTION_MESSAGE);
+    }
+    const hasSimSeconds = 'simSeconds' in budget;
+    const hasSimTicks = 'simTicks' in budget;
+    if (!hasSimSeconds && !hasSimTicks) {
+        throw new SessionError(SESSION_ERROR_CODES.WAIT_FOR_INVALID_BUDGET, WAIT_FOR_TIMEOUT_OPTION_MESSAGE);
+    }
+}
+/** Sim-time delta the budget measures, `current` relative to `start`. */
+export function budgetElapsed(budget, start, current) {
+    return 'simSeconds' in budget
+        ? current.time.simSeconds - start.time.simSeconds
+        : current.time.tick - start.time.tick;
+}
+export function budgetTarget(budget) {
+    return 'simSeconds' in budget ? budget.simSeconds : budget.simTicks;
+}
+export function budgetUnitLabel(budget) {
+    return 'simSeconds' in budget ? 'sim-seconds' : 'sim-ticks';
+}
+/** Binds a snapshot to the synchronous `s(name)` reader predicates use, and
+ *  (optionally) records which provider names the predicate actually read —
+ *  the failure block's "assisted-tier consumed" header flag needs this. */
+export function makeStateReader(snapshot, touched) {
+    return (name) => {
+        touched?.add(name);
+        return snapshot.state[name];
+    };
+}
+export class WaitForTimeoutError extends Error {
+    info;
+    constructor(info) {
+        super(`game.waitFor timed out: budget ${budgetTarget(info.budget)} ${budgetUnitLabel(info.budget)}`);
+        this.name = 'WaitForTimeoutError';
+        this.info = info;
+    }
+}
+// ---------------------------------------------------------------------------
+// Fixture heartbeat (Wave-6 findings ledger: "Watchdog sim-awareness / fixture
+// heartbeat for long silent tests" — Session C hit exit-5 on the runner's
+// 2x90s stdout-liveness watchdog during a legitimately silent 5-minute test).
+//
+// A caller watching stdout for liveness already treats ANY
+// child stdout as liveness — it has no idea what a line MEANS, only that one
+// arrived. This is the fixture-side half: while `waitFor`/`waitSimTime` is
+// polling, print one line every ~60s of WALL silence so a genuinely
+// advancing test can never false-wedge regardless of duration, no matter how
+// long a single `simSeconds` budget runs.
+//
+// INVARIANT (tested below and in fixture.test.ts): a heartbeat requires BOTH
+// (a) >= HEARTBEAT_INTERVAL_MS of wall time since the last heartbeat, AND
+// (b) the tick has ADVANCED since the last heartbeat (not merely since the
+// last poll). Without (b), the poll loop itself — which keeps running
+// against a frozen page, that being the whole reason `WAIT_FOR_STALL_POLL_
+// LIMIT` above exists as a SEPARATE guard — would emit a heartbeat every 60s
+// regardless of whether the game is actually alive, defeating the point: a
+// frozen sim clock must go heartbeat-silent so the outer watchdog can still
+// diagnose it as wedged. Advancing ticks -> heartbeats keep the run alive
+// indefinitely; frozen ticks -> no heartbeats, and the existing stall guard
+// (or the outer harness watchdog) still fires.
+// ---------------------------------------------------------------------------
+export const HEARTBEAT_INTERVAL_MS = 60_000;
+/** The liveness line this prints to stdout — greppable, and
+ *  stable so a human tailing a long run can `grep vgai-heartbeat`. */
+export function formatHeartbeatLine(testTitle, simSeconds, tick) {
+    return `vgai-heartbeat ${testTitle} simSeconds=${simSeconds} tick=${tick}`;
+}
+/**
+ * Pure decision, called once per poll: should a heartbeat print now, and
+ * what's the updated bookkeeping? See the module-doc invariant above — both
+ * the wall-silence budget AND tick advancement (since the last EMITTED
+ * heartbeat, not the last poll) must hold. Returns the SAME `state` object
+ * (referentially) when nothing should emit, so a caller can cheaply no-op.
+ */
+export function maybeHeartbeat(opts) {
+    const wallElapsed = opts.nowMs - opts.state.lastEmitWallMs;
+    const tickAdvancedSinceLastEmit = opts.tick !== opts.state.lastEmitTick;
+    if (wallElapsed >= HEARTBEAT_INTERVAL_MS && tickAdvancedSinceLastEmit) {
+        return {
+            line: formatHeartbeatLine(opts.testTitle, opts.simSeconds, opts.tick),
+            state: { lastEmitWallMs: opts.nowMs, lastEmitTick: opts.tick },
+        };
+    }
+    return { line: null, state: opts.state };
+}
+/**
+ * D2: a real internal stall guard, always active (unlike `maxPolls` above,
+ * which is a test-only seam real callers must leave unset). The bug this
+ * fixes: `budgetElapsed` (above) is computed from `current.time.simSeconds`/
+ * `.tick` — if the game's sim clock freezes entirely (the loop itself is
+ * stalled, not merely backgrounded), those fields never change, so
+ * `budgetElapsed` stays at 0 FOREVER and the budget itself can never
+ * exhaust — contradicting hidden-recovery.ts's own doc comment, which
+ * assumes `runWaitFor`'s sim-time budget is what eventually diagnoses a
+ * still-stalled loop after `HiddenRecoveryDriver` has had its one
+ * `bringToFront()` chance.
+ *
+ * 200 consecutive polls with an utterly unchanged tick, at the default
+ * 150ms poll interval, is ~30s of real wall time — comfortably (20x) past
+ * `HIDDEN_RECOVERY_STALL_POLLS`'s ~1.5s window (hidden-recovery.ts), so a
+ * merely-backgrounded tab has already had its recovery chance well before
+ * this guard would ever fire. If the tick is STILL frozen after that much
+ * wall time, the game loop itself is stalled (not the tab), and this guard
+ * throws the same `WaitForTimeoutError` an ordinary budget exhaustion would
+ * — the failure block renders honestly, with its ~0x sim-speed ratio and
+ * "if ~0x, the loop is stalled" hint (failure-block.ts), rather than the
+ * caller hanging forever.
+ */
+export const WAIT_FOR_STALL_POLL_LIMIT = 200;
+/**
+ * Polls `clock.snapshot()` until `pred` is true or `budget` is exhausted.
+ * Each iteration reads exactly one snapshot (AC-B1.2). On exhaustion throws
+ * `WaitForTimeoutError` carrying everything `client.ts` needs to assemble
+ * the full failure block.
+ *
+ * `testTitle` (defaults to `'test'` for callers that don't have one — every
+ * REAL caller, `client.ts`'s `waitFor`, always supplies the real Playwright
+ * test title) names the fixture heartbeat lines this loop emits — see the
+ * module doc above `maybeHeartbeat` for the emission invariant.
+ */
+export async function runWaitFor(pred, budget, clock, testTitle = 'test') {
+    assertValidWaitForBudget(budget);
+    const pollIntervalMs = clock.pollIntervalMs ?? 150;
+    const log = clock.log ?? (() => { });
+    const startWall = clock.now();
+    const start = await clock.snapshot();
+    let current = start;
+    const touched = new Set();
+    let polls = 0;
+    // D2: consecutive polls (so far) whose tick exactly matches the poll
+    // before it — independent of the budget's own elapsed math, which is what
+    // lets this catch a frozen clock the budget itself would never exhaust.
+    let stalledTickPolls = 0;
+    let heartbeat = { lastEmitWallMs: startWall, lastEmitTick: start.time.tick };
+    for (;;) {
+        const reader = makeStateReader(current, touched);
+        if (pred(reader))
+            return current;
+        polls += 1;
+        const elapsed = budgetElapsed(budget, start, current);
+        const target = budgetTarget(budget);
+        const outOfPolls = clock.maxPolls !== undefined && polls >= clock.maxPolls;
+        const stalled = stalledTickPolls >= WAIT_FOR_STALL_POLL_LIMIT;
+        if (elapsed >= target || outOfPolls || stalled) {
+            throw new WaitForTimeoutError({
+                budget,
+                startSnapshot: start,
+                lastSnapshot: current,
+                wallElapsedMs: clock.now() - startWall,
+                predicateSource: pred.toString(),
+                touchedProviders: [...touched],
+            });
+        }
+        await clock.sleep(pollIntervalMs);
+        const next = await clock.snapshot();
+        stalledTickPolls = next.time.tick === current.time.tick ? stalledTickPolls + 1 : 0;
+        current = next;
+        const heartbeatResult = maybeHeartbeat({
+            nowMs: clock.now(),
+            tick: next.time.tick,
+            simSeconds: next.time.simSeconds,
+            testTitle,
+            state: heartbeat,
+        });
+        heartbeat = heartbeatResult.state;
+        if (heartbeatResult.line)
+            log(heartbeatResult.line);
+    }
+}

package/dist/game.d.ts

@@ -1,29 +1,58 @@
 /**
  * `game` — the game-control half of `@vgai/live`'s `{ editor, game, page }`.
- * A `GameClient` (`@vgai/e2e`) bound to a `RelayTransport` on the resolved
+ * A `GameClient` (`./game-client/`) bound to a `RelayTransport` on the resolved
  * session's port — the SAME session-wire relay (`POST /__editor/command`,
  * `bridge-call`/`bridge-screenshot`/`page-script`) every `EditorClient`
  * method already uses. Never forked: this module only WIRES `GameClient` up,
  * it does not reimplement any of its methods (`state`/`waitFor`/`events`/
  * `input.hold`/`input.tap`/`screenshot`/`command`/`page` — whatever
  * `GameClient` exposes is exposed here, unchanged).
- */
-import { GameClient } from '@vgai/e2e';
-/**
- * Builds a `GameClient` over a `RelayTransport({ port })`.
  *
- * Fence values (`fenceTick`/`fenceSeq`/`fenceSimSeconds`/`fenceWallMs`) are
- * placeholders — tick 0, seq 0, sim-seconds 0, "now" — rather than a real
- * play-mode-start snapshot. `@vgai/e2e`'s own relay fixture
- * (`relay-fixture.ts`'s `waitForRelayBridge`) waits for a FRESH play-mode
- * boot before constructing its `game` client, because a test always starts
- * from a known instant. A `connect()`ed live session has no such instant —
- * it may attach to an ALREADY-RUNNING game session — so there is no single
- * "test start" to fence from. Practical effect: `game.events.expect(...)`
- * sees the WHOLE event history since play mode started (not a per-call
- * window); every other method (`state`/`waitFor`/`input`/`command`/
- * `screenshot`) is unaffected by the fence. `pageErrors`/`consoleErrors` are
- * always empty — relay mode has no separate page handle to listen on (the
- * same documented gap `relay-fixture.ts` carries).
+ * When the editor has MORE THAN ONE instance mounted (multiplayer authoring —
+ * see the engine's play-mode `mountAdditionalInstance`), `game` alone REFUSES
+ * to guess which one a call addresses. `game.instances()` / `game.instance(id)`
+ * are the way past that: each returns a `GameClient` whose relay carries a
+ * specific mount id (`RelayTransport({ instance })`), so one script can drive
+ * several instances — two seats of a match, or one scene under two seeds —
+ * without ambiguity.
  */
+import { GameClient } from './game-client/index.js';
+/** A `GameClient` addressing ONE mounted instance, tagged with the mount `id`
+ *  it drives. `id` is the whole point of the handle to a CALLER: it is what
+ *  `tools.run(name, args, { instance: handle.id })` passes to scope a
+ *  node-hosted tool (e.g. `project.autoplay`) to this seat — the two-seat
+ *  multiplayer verification pattern. Without it the caller has a client it can
+ *  drive but no id to hand a tool, so the seat-scoped path silently degrades to
+ *  the sole-instance one. */
+export type AddressedGameClient = GameClient & {
+    readonly id: string;
+};
+/** `game` plus the instance-addressing surface (see this module's doc). The
+ *  base `GameClient` methods are unchanged; a bare call still targets the sole
+ *  instance and refuses when several are live. */
+export interface LiveGame extends GameClient {
+    /**
+     * A handle addressing ONE mounted instance by its mount id — a `GameClient`
+     * whose every relay call carries `instance: id`, and which exposes that `id`
+     * back (`handle.id === id`). Synchronous: it builds a client, it does not
+     * contact the editor. (Through the bare top-level `game` singleton it
+     * resolves a session first and so returns a promise — the same proxy
+     * limitation the singleton documents; the `connect()`/`vgai eval` form is
+     * synchronous.)
+     */
+    instance(id: string): AddressedGameClient;
+    /**
+     * Handles for every instance currently mounted, in mount order — each tagged
+     * with its own `id`. One round trip (`list-instances`) to enumerate, then one
+     * addressed `GameClient` per id. `[]` when nothing is mounted (not playing) —
+     * the honest answer.
+     */
+    instances(): Promise<AddressedGameClient[]>;
+}
+/** The unaddressed `game` client — targets the sole live instance and refuses
+ *  when several are mounted. Kept as a named export for callers/tests that
+ *  want just the base client. */
 export declare function createGameClient(port: number, artifactsDir?: string): GameClient;
+/** Build the `LiveGame` — the base `game` client plus its instance-addressing
+ *  surface. */
+export declare function createLiveGame(port: number, artifactsDir?: string): LiveGame;

package/dist/game.js

@@ -1,34 +1,40 @@
 /**
  * `game` — the game-control half of `@vgai/live`'s `{ editor, game, page }`.
- * A `GameClient` (`@vgai/e2e`) bound to a `RelayTransport` on the resolved
+ * A `GameClient` (`./game-client/`) bound to a `RelayTransport` on the resolved
  * session's port — the SAME session-wire relay (`POST /__editor/command`,
  * `bridge-call`/`bridge-screenshot`/`page-script`) every `EditorClient`
  * method already uses. Never forked: this module only WIRES `GameClient` up,
  * it does not reimplement any of its methods (`state`/`waitFor`/`events`/
  * `input.hold`/`input.tap`/`screenshot`/`command`/`page` — whatever
  * `GameClient` exposes is exposed here, unchanged).
+ *
+ * When the editor has MORE THAN ONE instance mounted (multiplayer authoring —
+ * see the engine's play-mode `mountAdditionalInstance`), `game` alone REFUSES
+ * to guess which one a call addresses. `game.instances()` / `game.instance(id)`
+ * are the way past that: each returns a `GameClient` whose relay carries a
+ * specific mount id (`RelayTransport({ instance })`), so one script can drive
+ * several instances — two seats of a match, or one scene under two seeds —
+ * without ambiguity.
  */
-import { GameClient, RelayTransport } from '@vgai/e2e';
+import { GameClient, RelayTransport } from './game-client/index.js';
 /**
- * Builds a `GameClient` over a `RelayTransport({ port })`.
+ * Build a `GameClient` on `port`, optionally addressing one mounted instance.
  *
  * Fence values (`fenceTick`/`fenceSeq`/`fenceSimSeconds`/`fenceWallMs`) are
  * placeholders — tick 0, seq 0, sim-seconds 0, "now" — rather than a real
- * play-mode-start snapshot. `@vgai/e2e`'s own relay fixture
- * (`relay-fixture.ts`'s `waitForRelayBridge`) waits for a FRESH play-mode
- * boot before constructing its `game` client, because a test always starts
- * from a known instant. A `connect()`ed live session has no such instant —
- * it may attach to an ALREADY-RUNNING game session — so there is no single
- * "test start" to fence from. Practical effect: `game.events.expect(...)`
- * sees the WHOLE event history since play mode started (not a per-call
- * window); every other method (`state`/`waitFor`/`input`/`command`/
- * `screenshot`) is unaffected by the fence. `pageErrors`/`consoleErrors` are
- * always empty — relay mode has no separate page handle to listen on (the
- * same documented gap `relay-fixture.ts` carries).
+ * play-mode-start snapshot. A caller that owns its own browser can fence off
+ * a FRESH play-mode boot, because it starts from a known instant. A
+ * `connect()`ed live session has no such instant — it may attach to an
+ * ALREADY-RUNNING game session — so there is no single "run start" to fence
+ * from. Practical effect: `game.events.expect(...)` sees the WHOLE event
+ * history since play mode started (not a per-call window); every other method
+ * (`state`/`waitFor`/`input`/`command`/`screenshot`) is unaffected by the
+ * fence. `pageErrors`/`consoleErrors` are always empty — relay mode has no
+ * separate page handle to listen on.
  */
-export function createGameClient(port, artifactsDir) {
+function gameClientFor(port, artifactsDir, instance) {
     return new GameClient({
-        transport: new RelayTransport({ port }),
+        transport: new RelayTransport(instance === undefined ? { port } : { port, instance }),
         pageErrors: [],
         consoleErrors: [],
         fenceTick: 0,
@@ -39,3 +45,40 @@ export function createGameClient(port, artifactsDir) {
         artifactsDir,
     });
 }
+/** The unaddressed `game` client — targets the sole live instance and refuses
+ *  when several are mounted. Kept as a named export for callers/tests that
+ *  want just the base client. */
+export function createGameClient(port, artifactsDir) {
+    return gameClientFor(port, artifactsDir);
+}
+/** Query the editor's live instance ids over the session wire.
+ *
+ *  `list-instances` is a session-level command (`command-listener.ts`), NOT a
+ *  `bridge-call` method: it answers "which instances exist", and the
+ *  bridge-call path RESOLVES an instance (refusing when several are live), so
+ *  routing this through it would hit the exact ambiguity it throws on. The
+ *  response spreads `data` at the top level, so the ids arrive as
+ *  `body.instances`. */
+async function listInstanceIds(port) {
+    const res = await fetch(`http://127.0.0.1:${port}/__editor/command`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ type: 'list-instances' }),
+    });
+    const body = (await res.json());
+    if (!body.ok || !Array.isArray(body.instances)) {
+        throw new Error(`@vgai/live: list-instances failed — ${body.error ?? 'no instances in reply'}`);
+    }
+    return body.instances.map(String);
+}
+/** Build the `LiveGame` — the base `game` client plus its instance-addressing
+ *  surface. */
+export function createLiveGame(port, artifactsDir) {
+    const base = gameClientFor(port, artifactsDir);
+    // Tag each addressed handle with the mount id it drives, so a caller can pass
+    // `handle.id` to `tools.run(..., { instance })`. The id is already known here
+    // (it is what parameterizes the relay); attaching it just hands it back.
+    const instance = (id) => Object.assign(gameClientFor(port, artifactsDir, id), { id });
+    const instances = async () => (await listInstanceIds(port)).map(instance);
+    return Object.assign(base, { instance, instances });
+}