@vgai/live 0.5.2 → 0.5.4

package/src/game.ts

@@ -1,36 +1,74 @@
 /**
  * `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';
+
+/** 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[]>;
+}
 
 /**
- * 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: number, artifactsDir?: string): GameClient {
+function gameClientFor(port: number, artifactsDir?: string, instance?: string): GameClient {
   return new GameClient({
-    transport: new RelayTransport({ port }),
+    transport: new RelayTransport(instance === undefined ? { port } : { port, instance }),
     pageErrors: [],
     consoleErrors: [],
     fenceTick: 0,
@@ -41,3 +79,45 @@ export function createGameClient(port: number, artifactsDir?: string): GameClien
     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: number, artifactsDir?: string): GameClient {
+  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: number): Promise<string[]> {
+  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()) as { ok?: boolean; instances?: unknown; error?: string };
+  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: number, artifactsDir?: string): LiveGame {
+  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: string): AddressedGameClient =>
+    Object.assign(gameClientFor(port, artifactsDir, id), { id });
+  const instances = async (): Promise<AddressedGameClient[]> =>
+    (await listInstanceIds(port)).map(instance);
+  return Object.assign(base, { instance, instances });
+}

package/src/index.ts

@@ -1,10 +1,9 @@
 /**
- * `@vgai/live` — `{ editor, game, page, tools }` over the session wire
- * (docs/SHARED-SESSION-SPEC.md, Wave 2). Editor control consolidates HERE
- * from the ~19 `vgai` CLI verbs: a plain node/tsx script gets
- * `import { editor, game, page } from '@vgai/live'` instead of shelling out
- * to the CLI — semantics are discoverable from THIS module's types, not from
- * CLI usage text.
+ * `@vgai/live` — `{ editor, game, page, tools }` over the session wire.
+ * Editor control consolidates HERE from the ~19 `vgai` CLI verbs: a plain
+ * node/tsx script gets `import { editor, game, page } from '@vgai/live'`
+ * instead of shelling out to the CLI — semantics are discoverable from THIS
+ * module's types, not from CLI usage text.
  *
  * `@vgai/live` never starts or stops a session — the CLI keeps that
  * (`create`/`edit`/`sessions`/`close`). `connect()` (and the lazy
@@ -30,25 +29,24 @@
  *
  * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
  * PR #166) — write `step` as a literal `async (page) => {...}` and inline
- * every value it needs. KNOWN WIRE LIMITATION: under the relay transport
- * this binds to (the same one `vgai e2e --in-editor` uses), `step` is
- * shipped to the editor dev server as `step.toString()` and reconstructed
- * there — closures over outer variables do NOT survive that trip. See
- * `@vgai/e2e`'s `bridge-transport.ts` (`runPageScript`'s doc comment) and
- * `relay-transport.ts` for the full honesty-boundary contract this wraps.
+ * every value it needs. KNOWN WIRE LIMITATION: under the relay transport this
+ * binds to, `step` is shipped to the editor dev server as `step.toString()`
+ * and reconstructed there — closures over outer variables do NOT survive that
+ * trip. See `game-client/bridge-transport.ts` (`runPageScript`'s doc comment)
+ * and `game-client/relay-transport.ts` for the full honesty-boundary contract
+ * this wraps.
  */
 
 import { join } from 'node:path';
-import type { GameClient } from '@vgai/e2e';
 import { EditorClient } from '@vgai/editor-sdk';
 import { LiveEditor } from './editor.js';
-import { createGameClient } from './game.js';
+import { createLiveGame, type LiveGame } from './game.js';
+import type { GameClient } from './game-client/index.js';
 import { lazyChainProxy } from './lazy-proxy.js';
 import { type ResolvedSession, resolveSession, type SessionResolutionDeps } from './session.js';
 import { createLazySession } from './singleton.js';
 import { LiveTools } from './tools.js';
 
-export type { GameClient } from '@vgai/e2e';
 export type {
   ActiveDocumentCapture,
   EditorClient,
@@ -56,9 +54,10 @@ export type {
   EditorViewDocument,
   PresentedEditorView,
 } from '@vgai/editor-sdk';
-export type { ApplyDiffInput, ApplyDiffResult, PanelName } from './editor.js';
+export type { PanelName } from './editor.js';
 export { inferAssetKind, LiveEditor } from './editor.js';
-export { createGameClient } from './game.js';
+export { createGameClient, createLiveGame, type LiveGame } from './game.js';
+export * from './game-client/index.js';
 export type {
   ProjectSessionHint,
   ResolvedSession,
@@ -73,17 +72,63 @@ export { LiveTools } from './tools.js';
 /** A `game.page(step)`-shaped call — see this module's doc comment for the closure-capture limitation. */
 export type PageStep = GameClient['page'];
 
-export interface LiveSession {
+export interface LiveSession extends LiveBindings {
+  /** The resolved session this is bound to — useful for logging/debugging which port/project a script attached to. */
+  session: ResolvedSession;
+}
+
+/** The callable half of a session: everything `vgai eval` binds except `session` itself. */
+export interface LiveBindings {
   editor: LiveEditor;
-  game: GameClient;
+  /** The game client, plus `instances()`/`instance(id)` for addressing one of
+   *  several mounted instances (multiplayer authoring). A bare `game` call
+   *  targets the sole instance and refuses when several are live. */
+  game: LiveGame;
   /** `GameClient.page` bound to `game` — see this module's own doc comment for the wire limitation. */
   page: PageStep;
   /** Registered project callables: enumerate, inspect, and invoke. */
   tools: LiveTools;
-  /** The resolved session this is bound to — useful for logging/debugging which port/project a script attached to. */
-  session: ResolvedSession;
 }
 
+/**
+ * Construct the binding graph for an editor on `port`. Pure — every object
+ * here is built from a URL/port and contacts nothing until a method is
+ * awaited, which is what lets `unconnectedBindings()` below reuse it.
+ */
+function bindTo(port: number, projectRoot: string): LiveBindings {
+  const client = new EditorClient({ url: `http://127.0.0.1:${port}` });
+  const editor = new LiveEditor(client);
+  const game = createLiveGame(port, join(projectRoot, '.vgai', 'last-run'));
+  const page: PageStep = (step) => game.page(step);
+  const tools = new LiveTools(client);
+  return { editor, game, page, tools };
+}
+
+/**
+ * The SAME `{ editor, game, page, tools }` objects `connect()` returns —
+ * real classes, real instance fields — bound to a port nothing listens on.
+ *
+ * This exists for INTROSPECTION, and specifically for `vgai eval --list`
+ * (`packages/vgai-cli/src/eval-surface.ts`), which must answer "what could I
+ * call?" before `vgai edit` is running. Reading a CLASS instead is what
+ * shipped first, and it silently omitted `game.input` and `game.events`:
+ * those are instance fields the constructor assigns, so they exist on no
+ * prototype and a class walk cannot see them — an agent reading the listing
+ * concluded there was no honest input door. Objects, not classes, is the fix,
+ * and going through `bindTo` is what keeps it honest: the probe is assembled
+ * by the same function `connect()` uses, so a binding added there is listed
+ * here with no second place to remember.
+ *
+ * Awaiting any method on these objects will fail (connection refused). Use
+ * `connect()` for that.
+ */
+export function unconnectedBindings(): LiveBindings {
+  return bindTo(UNCONNECTED_PORT, process.cwd());
+}
+
+/** Port 0 is never a listening editor — an accidental call fails loudly rather than reaching a stranger's server. */
+const UNCONNECTED_PORT = 0;
+
 /**
  * Resolve `projectDir` (default `process.cwd()`) to its live `vgai edit`
  * session and bind `{ editor, game, page }` to it. `deps` is an advanced/
@@ -95,15 +140,7 @@ export async function connect(
   deps?: SessionResolutionDeps,
 ): Promise<LiveSession> {
   const resolved = await resolveSession(projectDir, deps);
-  const client = new EditorClient({ url: `http://localhost:${resolved.port}` });
-  const editor = new LiveEditor(client, resolved.projectRoot);
-  const game = createGameClient(
-    resolved.port,
-    join(resolved.projectRoot, '.vgai', 'e2e', 'last-run'),
-  );
-  const page: PageStep = (step) => game.page(step);
-  const tools = new LiveTools(client);
-  return { editor, game, page, tools, session: resolved };
+  return { ...bindTo(resolved.port, resolved.projectRoot), session: resolved };
 }
 
 // ---------------------------------------------------------------------------
@@ -123,7 +160,7 @@ export function __resetLiveSingletonForTests(): void {
 export const editor: LiveEditor = lazyChainProxy<LiveEditor>(() =>
   lazySession.ensure().then((s) => s.editor),
 );
-export const game: GameClient = lazyChainProxy<GameClient>(() =>
+export const game: LiveGame = lazyChainProxy<LiveGame>(() =>
   lazySession.ensure().then((s) => s.game),
 );
 export const page: PageStep = lazyChainProxy<PageStep>(() =>

package/src/session.ts

@@ -23,7 +23,7 @@
  *  3. Project-root discovery (`findProjectRootFrom` below) — LIFTED (not
  *     imported) from `packages/vgai-cli/src/project-root.ts`. `@vgai/sdk`'s
  *     `resolveEditorSession` takes an already-known `ctx.projectRoot`; it has
- *     no "walk up from an arbitrary cwd to find the nearest vgai.game.json"
+ *     no "walk up from an arbitrary cwd to find the nearest vgai.project.json"
  *     step of its own, which `connect(projectDir?)` needs. `@vgai/cli` is
  *     `"private": true` with no `exports` field to import through (and
  *     depending on it from here would invert the intended CLI -> SDK ->
@@ -58,13 +58,13 @@ import {
 /**
  * Lifted verbatim from `packages/vgai-cli/src/project-root.ts` (see this
  * module's doc comment above for why it's duplicated rather than imported).
- * Nearest ancestor of `dir` (inclusive) containing a `vgai.game.json`, or
+ * Nearest ancestor of `dir` (inclusive) containing a `vgai.project.json`, or
  * `null` if none.
  */
 export function findProjectRootFrom(dir: string): string | null {
   let cur = resolve(dir);
   for (;;) {
-    if (existsSync(join(cur, 'vgai.game.json'))) return cur;
+    if (existsSync(join(cur, 'vgai.project.json'))) return cur;
     const parent = dirname(cur);
     if (parent === cur) return null;
     cur = parent;
@@ -77,7 +77,7 @@ export type SessionListingTransport = Pick<EditorTransport, 'listSessions'>;
 export interface ResolvedSession {
   /** Editor dev-server port the resolved session is listening on. */
   port: number;
-  /** Absolute project root — the nearest ancestor of the requested directory containing `vgai.game.json`. */
+  /** Absolute project root — the nearest ancestor of the requested directory containing `vgai.project.json`. */
   projectRoot: string;
 }
 
@@ -135,7 +135,7 @@ async function verifyProjectSession(
   projectRoot: string,
 ): Promise<boolean> {
   try {
-    const response = await fetch(`http://localhost:${hint.port}/__editor/project`, {
+    const response = await fetch(`http://127.0.0.1:${hint.port}/__editor/project`, {
       signal: AbortSignal.timeout(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
     });
     if (!response.ok) return false;
@@ -154,7 +154,7 @@ async function verifyProjectSession(
  * running `vgai edit` session. Throws a descriptive error (never hangs
  * indefinitely — bounded by `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`, and never
  * silently attaches to an unrelated project's session — see the module doc
- * above) when no vgai.game.json is found, or no live session covers it.
+ * above) when no vgai.project.json is found, or no live session covers it.
  */
 export async function resolveSession(
   projectDir: string = process.cwd(),
@@ -166,7 +166,7 @@ export async function resolveSession(
   const projectRoot = findRoot(projectDir);
   if (projectRoot === null) {
     throw new Error(
-      `@vgai/live: no vgai.game.json found in ${projectDir} or any parent directory — is this a vgai project?`,
+      `@vgai/live: no vgai.project.json found in ${projectDir} or any parent directory — is this a vgai project?`,
     );
   }
 
@@ -195,9 +195,7 @@ export async function resolveSession(
   }
 
   const canon = canonicalPath(projectRoot);
-  const match = sessions.find(
-    (s) => s.kind !== 'e2e' && s.project !== null && canonicalPath(s.project) === canon,
-  );
+  const match = sessions.find((s) => s.project !== null && canonicalPath(s.project) === canon);
   if (!match) {
     const otherCount = sessions.length;
     throw new Error(

package/src/tools.ts

@@ -8,11 +8,16 @@ import type {
 } from '@vgai/editor-sdk';
 
 export class LiveTools {
-  constructor(private readonly client: EditorClient) {}
+  /** `#`-private for the same reason `LiveEditor.#client` is. */
+  readonly #client: EditorClient;
+
+  constructor(client: EditorClient) {
+    this.#client = client;
+  }
 
   /** Enumerate the exact `package.json#vgai.tools` catalog without executing it. */
   async list(): Promise<ProjectToolCatalog> {
-    return this.client.listProjectTools();
+    return this.#client.listProjectTools();
   }
 
   /** Return one tool's discoverable metadata, or `null` when it is not registered. */
@@ -21,12 +26,20 @@ export class LiveTools {
     return catalog.tools.find((tool) => tool.name === name) ?? null;
   }
 
-  /** Invoke the same validated callable used by the editor and CLI. */
-  async call(
+  /**
+   * Invoke the same validated callable used by the editor and CLI.
+   *
+   * `instance` names WHICH mounted instance the tool should drive when several
+   * are live (multiplayer authoring) — it reaches the tool as `ctx.instance`,
+   * and a tool that drives the game (e.g. `project.autoplay`) binds
+   * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
+   * the tool then targets the sole live instance, exactly as before.
+   */
+  async run(
     name: string,
     input: unknown = {},
-    options: { confirm?: boolean } = {},
+    options: { confirm?: boolean; instance?: string } = {},
   ): Promise<ProjectToolOutcome> {
-    return this.client.runProjectTool(name, input, options);
+    return this.#client.runProjectTool(name, input, options);
   }
 }