@vgai/live 0.4.0 → 0.4.1

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -30,9 +30,9 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.4.0",
-    "@vgai/probe": "0.4.0",
-    "@vgai/sdk": "0.4.0"
+    "@vgai/editor-sdk": "0.4.1",
+    "@vgai/probe": "0.4.1",
+    "@vgai/sdk": "0.4.1"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.58.2 <2"

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * `@vgai/live` — `{ editor, game, page }` over the session wire
+ * `@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
@@ -45,6 +45,7 @@ import { createGameClient } from './game.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 { EditorClient } from '@vgai/editor-sdk';
 export type { GameClient } from '@vgai/probe';
@@ -59,6 +60,7 @@ export type {
 export { findProjectRootFrom, resolveSession } from './session.js';
 export type { LazySession } from './singleton.js';
 export { createLazySession } from './singleton.js';
+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'];
@@ -68,6 +70,8 @@ export interface LiveSession {
   game: GameClient;
   /** `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;
 }
@@ -87,7 +91,8 @@ export async function connect(
   const editor = new LiveEditor(client, resolved.projectRoot);
   const game = createGameClient(resolved.port);
   const page: PageStep = (step) => game.page(step);
-  return { editor, game, page, session: resolved };
+  const tools = new LiveTools(client);
+  return { editor, game, page, tools, session: resolved };
 }
 
 // ---------------------------------------------------------------------------
@@ -113,3 +118,6 @@ export const game: GameClient = lazyChainProxy<GameClient>(() =>
 export const page: PageStep = lazyChainProxy<PageStep>(() =>
   lazySession.ensure().then((s) => s.page),
 );
+export const tools: LiveTools = lazyChainProxy<LiveTools>(() =>
+  lazySession.ensure().then((s) => s.tools),
+);

package/src/tools.ts

@@ -0,0 +1,32 @@
+/** Registered project tools over the current shared editor session. */
+
+import type {
+  EditorClient,
+  ProjectToolCatalog,
+  ProjectToolCatalogEntry,
+  ProjectToolOutcome,
+} from '@vgai/editor-sdk';
+
+export class LiveTools {
+  constructor(private readonly client: EditorClient) {}
+
+  /** Enumerate the exact `package.json#vgai.tools` catalog without executing it. */
+  async list(): Promise<ProjectToolCatalog> {
+    return this.client.listProjectTools();
+  }
+
+  /** Return one tool's discoverable metadata, or `null` when it is not registered. */
+  async describe(name: string): Promise<ProjectToolCatalogEntry | null> {
+    const catalog = await this.list();
+    return catalog.tools.find((tool) => tool.name === name) ?? null;
+  }
+
+  /** Invoke the same validated callable used by the editor and CLI. */
+  async call(
+    name: string,
+    input: unknown = {},
+    options: { confirm?: boolean } = {},
+  ): Promise<ProjectToolOutcome> {
+    return this.client.runProjectTool(name, input, options);
+  }
+}

package/dist/editor.d.ts

@@ -1,100 +0,0 @@
-/**
- * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (SHARED-SESSION-SPEC.md, Wave 2). Methods are named after the
- * ACTION, not the CLI flag spelling (e.g. `select('all')` rather than a
- * separate `selectAll`, `showPanel('viewport-game')` rather than
- * `vgai show viewport game`'s two-token shape) — see each method's own doc
- * comment for the exact CLI verb / `EditorClient` call it mirrors.
- *
- * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module
- * never hand-rolls a `fetch` to `/__editor/command` itself. The ONE
- * exception is `applyDiff`, which is FILE mode (writes the scene file
- * directly), not a live wire command — see its own doc comment.
- */
-import type { AssetKind, AssetPreviewCapture, AssetPreviewOptions, EditorClient, EditorState, ShadingMode, ViewPreset, ViewportCapture } from '@vgai/editor-sdk';
-/** `vgai show <...>`'s four sub-verbs folded into one action name — see `showPanel`. */
-export type PanelName = 'viewport-scene' | 'viewport-game' | 'inspector' | 'console' | 'build';
-/** Mirrors `@vgai/sdk`'s `project.scene.apply` operation input — the same shape `vgai apply-diff` builds from its `<scene> <patch>` file arguments. `patch` is a `SceneDiff` JSON object (validated by the operation's own Zod schema — a malformed patch throws, never silently no-ops). */
-export interface ApplyDiffInput {
-    /** Project-relative path to the `.vscn.json` scene file to modify. */
-    scenePath: string;
-    /** A `SceneDiff`-shaped patch object. */
-    patch: unknown;
-    /** Validate + report only — never write to disk. Default `false`. */
-    dryRun?: boolean;
-    /** Refuse a stale write when the file's content hash no longer matches (optimistic concurrency) — omit to skip the check. */
-    baseHash?: string;
-}
-/** The `project.scene.apply` operation's result shape. */
-export interface ApplyDiffResult {
-    dryRun: boolean;
-    written: boolean;
-    filesChanged: string[];
-    before: {
-        scene: unknown;
-    };
-    after: {
-        scene: unknown;
-    };
-}
-/**
- * Lightweight extension-based `AssetKind` guess for `openAsset`'s optional
- * `kind` argument. Deliberately independent of (not shared with) the
- * editor's own `AssetBrowser.tsx#getAssetKind` — that function is a private,
- * React-component-local helper of a package `@vgai/live` has no dependency
- * on. Callers with an unusual extension can always pass `kind` explicitly.
- */
-export declare function inferAssetKind(path: string): AssetKind;
-export declare class LiveEditor {
-    private readonly client;
-    /** Absolute project root this session is bound to — used only by `applyDiff` (FILE mode; every other method goes over the wire and never needs it). */
-    private readonly projectRoot;
-    constructor(client: EditorClient, 
-    /** Absolute project root this session is bound to — used only by `applyDiff` (FILE mode; every other method goes over the wire and never needs it). */
-    projectRoot: string);
-    /**
-     * No `path` -> the currently open scene's save path (`status().savePath`).
-     * `path` given -> opens it (`EditorClient.openScene` — the same wire call
-     * `vgai scene <path>` sends), and the given path is returned back.
-     */
-    scene(path?: string): Promise<string | null>;
-    /**
-     * FILE mode — writes the scene file directly. NOT a live wire command:
-     * there is no live-editor wire op for this yet (`vgai apply-diff`'s own
-     * module doc names the identical gap: "LIVE MODE — NOT BUILT ... route the
-     * patch through a RUNNING editor"). Reuses the exact same engine
-     * machinery `vgai apply-diff` uses, through `@vgai/sdk`'s
-     * `project.scene.apply` operation (the operation-registry's own
-     * projection of that logic) — never hand-rolled here.
-     */
-    applyDiff(input: ApplyDiffInput): Promise<ApplyDiffResult>;
-    play(opts?: {
-        seed?: number;
-    }): Promise<void>;
-    stop(): Promise<void>;
-    pause(): Promise<void>;
-    resume(): Promise<void>;
-    /** Advance `n` frames (default 1) — `EditorClient.step()` sent `n` times, mirroring `vgai step` run repeatedly. */
-    step(n?: number): Promise<void>;
-    /** `'all'` -> `EditorClient.selectAll()` (mirrors `vgai select --all`); otherwise `EditorClient.select(id)` (mirrors `vgai select <entityId>`). */
-    select(id: string | 'all'): Promise<void>;
-    /** Mirrors `vgai deselect`. */
-    deselect(): Promise<void>;
-    /** No `id` -> focus the current selection (mirrors bare `vgai focus`); `id` given -> focus that entity. */
-    focus(id?: string): Promise<void>;
-    view(preset: ViewPreset): Promise<void>;
-    /** `vgai show <viewport <scene|game>|inspector|console|build>`'s four sub-verbs, folded into one action name. */
-    showPanel(name: PanelName): Promise<void>;
-    /** `kind` inferred from `path`'s extension when omitted (`inferAssetKind`) — pass it explicitly to override. */
-    openAsset(path: string, kind?: AssetKind): Promise<void>;
-    /** Captures the editor's native Asset Lab four-view preview for `path` (a project-relative asset path). */
-    assetPreview(path: string, options?: AssetPreviewOptions): Promise<AssetPreviewCapture>;
-    grid(on: boolean): Promise<void>;
-    helpers(on: boolean): Promise<void>;
-    stats(on: boolean): Promise<void>;
-    shading(mode: ShadingMode): Promise<void>;
-    /** Mirrors `vgai status` — the full live editor state as JSON. */
-    status(): Promise<EditorState>;
-    /** A live viewport PNG (`EditorClient.captureViewport`) — no direct CLI verb exists; this is the closest wire read. */
-    screenshot(size?: number): Promise<ViewportCapture>;
-}

package/dist/editor.js

@@ -1,175 +0,0 @@
-/**
- * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (SHARED-SESSION-SPEC.md, Wave 2). Methods are named after the
- * ACTION, not the CLI flag spelling (e.g. `select('all')` rather than a
- * separate `selectAll`, `showPanel('viewport-game')` rather than
- * `vgai show viewport game`'s two-token shape) — see each method's own doc
- * comment for the exact CLI verb / `EditorClient` call it mirrors.
- *
- * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module
- * never hand-rolls a `fetch` to `/__editor/command` itself. The ONE
- * exception is `applyDiff`, which is FILE mode (writes the scene file
- * directly), not a live wire command — see its own doc comment.
- */
-import { operations } from '@vgai/sdk';
-const EXTENSION_KIND = {
-    '.glb': 'model',
-    '.gltf': 'model',
-    '.png': 'image',
-    '.jpg': 'image',
-    '.jpeg': 'image',
-    '.webp': 'image',
-    '.gif': 'image',
-    '.mp3': 'audio',
-    '.ogg': 'audio',
-    '.wav': 'audio',
-    '.flac': 'audio',
-};
-/**
- * Lightweight extension-based `AssetKind` guess for `openAsset`'s optional
- * `kind` argument. Deliberately independent of (not shared with) the
- * editor's own `AssetBrowser.tsx#getAssetKind` — that function is a private,
- * React-component-local helper of a package `@vgai/live` has no dependency
- * on. Callers with an unusual extension can always pass `kind` explicitly.
- */
-export function inferAssetKind(path) {
-    if (path.endsWith('.vscn.json'))
-        return 'scene';
-    if (path.endsWith('.prefab.json'))
-        return 'prefab';
-    if (path.endsWith('.mat.json'))
-        return 'material';
-    const dot = path.lastIndexOf('.');
-    const ext = dot >= 0 ? path.slice(dot).toLowerCase() : '';
-    return EXTENSION_KIND[ext] ?? 'json';
-}
-export class LiveEditor {
-    client;
-    projectRoot;
-    constructor(client, 
-    /** Absolute project root this session is bound to — used only by `applyDiff` (FILE mode; every other method goes over the wire and never needs it). */
-    projectRoot) {
-        this.client = client;
-        this.projectRoot = projectRoot;
-    }
-    /**
-     * No `path` -> the currently open scene's save path (`status().savePath`).
-     * `path` given -> opens it (`EditorClient.openScene` — the same wire call
-     * `vgai scene <path>` sends), and the given path is returned back.
-     */
-    async scene(path) {
-        if (path !== undefined) {
-            await this.client.openScene(path);
-            return path;
-        }
-        const state = await this.client.getState();
-        return state.savePath;
-    }
-    /**
-     * FILE mode — writes the scene file directly. NOT a live wire command:
-     * there is no live-editor wire op for this yet (`vgai apply-diff`'s own
-     * module doc names the identical gap: "LIVE MODE — NOT BUILT ... route the
-     * patch through a RUNNING editor"). Reuses the exact same engine
-     * machinery `vgai apply-diff` uses, through `@vgai/sdk`'s
-     * `project.scene.apply` operation (the operation-registry's own
-     * projection of that logic) — never hand-rolled here.
-     */
-    async applyDiff(input) {
-        const outcome = await operations.dispatch('project.scene.apply', input, {
-            projectRoot: this.projectRoot,
-        });
-        if (!outcome.ok) {
-            throw new Error(`@vgai/live: applyDiff failed [${outcome.error.code}]: ${outcome.error.message}`);
-        }
-        return outcome.data;
-    }
-    async play(opts) {
-        await this.client.play(opts);
-    }
-    async stop() {
-        await this.client.stop();
-    }
-    async pause() {
-        await this.client.pause();
-    }
-    async resume() {
-        await this.client.resume();
-    }
-    /** Advance `n` frames (default 1) — `EditorClient.step()` sent `n` times, mirroring `vgai step` run repeatedly. */
-    async step(n = 1) {
-        for (let i = 0; i < n; i++) {
-            await this.client.step();
-        }
-    }
-    /** `'all'` -> `EditorClient.selectAll()` (mirrors `vgai select --all`); otherwise `EditorClient.select(id)` (mirrors `vgai select <entityId>`). */
-    async select(id) {
-        if (id === 'all') {
-            await this.client.selectAll();
-            return;
-        }
-        await this.client.select(id);
-    }
-    /** Mirrors `vgai deselect`. */
-    async deselect() {
-        await this.client.select(null);
-    }
-    /** No `id` -> focus the current selection (mirrors bare `vgai focus`); `id` given -> focus that entity. */
-    async focus(id) {
-        if (id !== undefined) {
-            await this.client.focusEntity(id);
-            return;
-        }
-        await this.client.focusSelection();
-    }
-    async view(preset) {
-        await this.client.viewPreset(preset);
-    }
-    /** `vgai show <viewport <scene|game>|inspector|console|build>`'s four sub-verbs, folded into one action name. */
-    async showPanel(name) {
-        switch (name) {
-            case 'viewport-scene':
-                await this.client.showViewport('scene');
-                return;
-            case 'viewport-game':
-                await this.client.showViewport('game');
-                return;
-            case 'inspector':
-                await this.client.showInspector();
-                return;
-            case 'console':
-                await this.client.toggleConsole();
-                return;
-            case 'build':
-                await this.client.showBuild();
-                return;
-        }
-    }
-    /** `kind` inferred from `path`'s extension when omitted (`inferAssetKind`) — pass it explicitly to override. */
-    async openAsset(path, kind) {
-        await this.client.openAsset(path, kind ?? inferAssetKind(path));
-    }
-    /** Captures the editor's native Asset Lab four-view preview for `path` (a project-relative asset path). */
-    async assetPreview(path, options) {
-        return this.client.captureAssetPreview({ assetPath: path }, options);
-    }
-    async grid(on) {
-        await this.client.setGrid(on);
-    }
-    async helpers(on) {
-        await this.client.setHelpers(on);
-    }
-    async stats(on) {
-        await this.client.setStats(on);
-    }
-    async shading(mode) {
-        await this.client.setShadingMode(mode);
-    }
-    /** Mirrors `vgai status` — the full live editor state as JSON. */
-    async status() {
-        return this.client.getState();
-    }
-    /** A live viewport PNG (`EditorClient.captureViewport`) — no direct CLI verb exists; this is the closest wire read. */
-    async screenshot(size) {
-        return this.client.captureViewport(size);
-    }
-}

package/dist/game.d.ts

@@ -1,29 +0,0 @@
-/**
- * `game` — the game-control half of `@vgai/live`'s `{ editor, game, page }`.
- * A `GameClient` (`@vgai/probe`) 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/probe';
-/**
- * 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/probe`'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).
- */
-export declare function createGameClient(port: number): GameClient;

package/dist/game.js

@@ -1,40 +0,0 @@
-/**
- * `game` — the game-control half of `@vgai/live`'s `{ editor, game, page }`.
- * A `GameClient` (`@vgai/probe`) 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, RelayTransport } from '@vgai/probe';
-/**
- * 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/probe`'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).
- */
-export function createGameClient(port) {
-    return new GameClient({
-        transport: new RelayTransport({ port }),
-        pageErrors: [],
-        consoleErrors: [],
-        fenceTick: 0,
-        fenceSeq: 0,
-        fenceSimSeconds: 0,
-        fenceWallMs: Date.now(),
-        warmSession: false,
-    });
-}

package/dist/index.d.ts

@@ -1,73 +0,0 @@
-/**
- * `@vgai/live` — `{ editor, game, page }` 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` never starts or stops a session — the CLI keeps that
- * (`create`/`edit`/`sessions`/`close`). `connect()` (and the lazy
- * `editor`/`game`/`page` singletons below) only ATTACH to a session already
- * started by `vgai edit`; if none is running for the resolved project, every
- * one of them rejects with a clear "run `vgai edit` first" error (see
- * `session.ts`'s `resolveSession`) rather than launching anything.
- *
- * Two ways to use this:
- *
- *   // A: explicit connect() — resolve once, reuse the bound session object.
- *   import { connect } from '@vgai/live';
- *   const { editor, game, page } = await connect();          // cwd's project
- *   const { editor, game, page } = await connect('../other-game');
- *   await editor.play();
- *   await game.waitFor((s) => s('score') >= 10, { simSeconds: 5 });
- *
- *   // B: lazy top-level singletons — auto-connect (against cwd) on first
- *   //    use, memoized after that. No explicit connect() call needed.
- *   import { editor, game, page } from '@vgai/live';
- *   await editor.grid(true);
- *   await game.input.tap('jump');
- *
- * `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 probe --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/probe`'s `bridge-transport.ts` (`runPageScript`'s doc comment) and
- * `relay-transport.ts` for the full honesty-boundary contract this wraps.
- */
-import type { GameClient } from '@vgai/probe';
-import { LiveEditor } from './editor.js';
-import { type ResolvedSession, type SessionResolutionDeps } from './session.js';
-export type { EditorClient } from '@vgai/editor-sdk';
-export type { GameClient } from '@vgai/probe';
-export type { ApplyDiffInput, ApplyDiffResult, PanelName } from './editor.js';
-export { inferAssetKind, LiveEditor } from './editor.js';
-export { createGameClient } from './game.js';
-export type { ResolvedSession, SessionListingTransport, SessionResolutionDeps, } from './session.js';
-export { findProjectRootFrom, resolveSession } from './session.js';
-export type { LazySession } from './singleton.js';
-export { createLazySession } from './singleton.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 {
-    editor: LiveEditor;
-    game: GameClient;
-    /** `GameClient.page` bound to `game` — see this module's own doc comment for the wire limitation. */
-    page: PageStep;
-    /** The resolved session this is bound to — useful for logging/debugging which port/project a script attached to. */
-    session: ResolvedSession;
-}
-/**
- * Resolve `projectDir` (default `process.cwd()`) to its live `vgai edit`
- * session and bind `{ editor, game, page }` to it. `deps` is an advanced/
- * test-only escape hatch (see `session.ts`'s `SessionResolutionDeps`) — real
- * callers never need it.
- */
-export declare function connect(projectDir?: string, deps?: SessionResolutionDeps): Promise<LiveSession>;
-/** Test-only reset of the lazy top-level singletons' memo — NOT part of the documented public surface (real callers never need to reconnect mid-process). */
-export declare function __resetLiveSingletonForTests(): void;
-export declare const editor: LiveEditor;
-export declare const game: GameClient;
-export declare const page: PageStep;

package/dist/index.js

@@ -1,77 +0,0 @@
-/**
- * `@vgai/live` — `{ editor, game, page }` 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` never starts or stops a session — the CLI keeps that
- * (`create`/`edit`/`sessions`/`close`). `connect()` (and the lazy
- * `editor`/`game`/`page` singletons below) only ATTACH to a session already
- * started by `vgai edit`; if none is running for the resolved project, every
- * one of them rejects with a clear "run `vgai edit` first" error (see
- * `session.ts`'s `resolveSession`) rather than launching anything.
- *
- * Two ways to use this:
- *
- *   // A: explicit connect() — resolve once, reuse the bound session object.
- *   import { connect } from '@vgai/live';
- *   const { editor, game, page } = await connect();          // cwd's project
- *   const { editor, game, page } = await connect('../other-game');
- *   await editor.play();
- *   await game.waitFor((s) => s('score') >= 10, { simSeconds: 5 });
- *
- *   // B: lazy top-level singletons — auto-connect (against cwd) on first
- *   //    use, memoized after that. No explicit connect() call needed.
- *   import { editor, game, page } from '@vgai/live';
- *   await editor.grid(true);
- *   await game.input.tap('jump');
- *
- * `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 probe --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/probe`'s `bridge-transport.ts` (`runPageScript`'s doc comment) and
- * `relay-transport.ts` for the full honesty-boundary contract this wraps.
- */
-import { EditorClient } from '@vgai/editor-sdk';
-import { LiveEditor } from './editor.js';
-import { createGameClient } from './game.js';
-import { lazyChainProxy } from './lazy-proxy.js';
-import { resolveSession } from './session.js';
-import { createLazySession } from './singleton.js';
-export { inferAssetKind, LiveEditor } from './editor.js';
-export { createGameClient } from './game.js';
-export { findProjectRootFrom, resolveSession } from './session.js';
-export { createLazySession } from './singleton.js';
-/**
- * Resolve `projectDir` (default `process.cwd()`) to its live `vgai edit`
- * session and bind `{ editor, game, page }` to it. `deps` is an advanced/
- * test-only escape hatch (see `session.ts`'s `SessionResolutionDeps`) — real
- * callers never need it.
- */
-export async function connect(projectDir, deps) {
-    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);
-    const page = (step) => game.page(step);
-    return { editor, game, page, session: resolved };
-}
-// ---------------------------------------------------------------------------
-// Lazy top-level singletons (usage form B above) — thin proxies over an
-// internal memoized connect() against cwd. First access triggers connect();
-// every access after that (across editor/game/page, and across however many
-// calls) reuses the SAME resolved session.
-// ---------------------------------------------------------------------------
-const lazySession = createLazySession(() => connect());
-/** Test-only reset of the lazy top-level singletons' memo — NOT part of the documented public surface (real callers never need to reconnect mid-process). */
-export function __resetLiveSingletonForTests() {
-    lazySession.reset();
-}
-export const editor = lazyChainProxy(() => lazySession.ensure().then((s) => s.editor));
-export const game = lazyChainProxy(() => lazySession.ensure().then((s) => s.game));
-export const page = lazyChainProxy(() => lazySession.ensure().then((s) => s.page));

package/dist/lazy-proxy.d.ts

@@ -1,26 +0,0 @@
-/**
- * `lazyChainProxy` — turns an async "resolve the real object" function into
- * a synchronously-importable stand-in that supports the SAME call shape as
- * the real thing, including nested member access (`game.input.hold(...)`,
- * `game.events.expect(...)`), by recording the property-access PATH and only
- * resolving + walking it down at the point of an actual function CALL.
- *
- * This is what makes `index.ts`'s top-level `export const editor = ...` /
- * `game` / `page` work as plain values a script can `import { editor, game,
- * page } from '@vgai/live'` and call immediately — each call transparently
- * awaits the memoized `connect()` first.
- *
- * Limitation (by design, documented on `index.ts`'s exports too): only
- * FUNCTION-shaped access resolves through this proxy — `game.input.hold(x)`
- * works, but reading a plain data property (e.g. `game.fenceTick`) would
- * return another inert proxy, not the real number, since there is no
- * function CALL to trigger resolution. Every documented `editor`/`game`/
- * `page` member is a method, so this never bites the documented surface.
- */
-/**
- * `resolveRoot` is called (and its result awaited) on every terminal
- * function call reached through the returned proxy — callers typically wire
- * it to a memoized `connect()` (see `index.ts`), so repeated calls across
- * many proxy invocations still resolve only once.
- */
-export declare function lazyChainProxy<T>(resolveRoot: () => Promise<unknown>, path?: PropertyKey[]): T;

package/dist/lazy-proxy.js

@@ -1,62 +0,0 @@
-/**
- * `lazyChainProxy` — turns an async "resolve the real object" function into
- * a synchronously-importable stand-in that supports the SAME call shape as
- * the real thing, including nested member access (`game.input.hold(...)`,
- * `game.events.expect(...)`), by recording the property-access PATH and only
- * resolving + walking it down at the point of an actual function CALL.
- *
- * This is what makes `index.ts`'s top-level `export const editor = ...` /
- * `game` / `page` work as plain values a script can `import { editor, game,
- * page } from '@vgai/live'` and call immediately — each call transparently
- * awaits the memoized `connect()` first.
- *
- * Limitation (by design, documented on `index.ts`'s exports too): only
- * FUNCTION-shaped access resolves through this proxy — `game.input.hold(x)`
- * works, but reading a plain data property (e.g. `game.fenceTick`) would
- * return another inert proxy, not the real number, since there is no
- * function CALL to trigger resolution. Every documented `editor`/`game`/
- * `page` member is a method, so this never bites the documented surface.
- */
-function isFunction(value) {
-    return typeof value === 'function';
-}
-function walk(root, path) {
-    if (path.length === 0)
-        return { thisArg: undefined, fn: root };
-    let obj = root;
-    for (let i = 0; i < path.length - 1; i++) {
-        const key = path[i];
-        obj = obj[key];
-    }
-    const lastKey = path[path.length - 1];
-    return { thisArg: obj, fn: obj[lastKey] };
-}
-/**
- * `resolveRoot` is called (and its result awaited) on every terminal
- * function call reached through the returned proxy — callers typically wire
- * it to a memoized `connect()` (see `index.ts`), so repeated calls across
- * many proxy invocations still resolve only once.
- */
-export function lazyChainProxy(resolveRoot, path = []) {
-    const callableTarget = (() => { });
-    return new Proxy(callableTarget, {
-        get(_target, prop) {
-            // Never look thenable — `await`ing a proxy (accidentally, or via a
-            // generic helper checking `typeof x.then`) must not trigger resolution
-            // or hang; there is no promise here, only a call-shaped stand-in.
-            if (prop === 'then' || prop === 'catch' || prop === 'finally')
-                return undefined;
-            return lazyChainProxy(resolveRoot, [...path, prop]);
-        },
-        apply(_target, _thisArg, args) {
-            return resolveRoot().then((root) => {
-                const { thisArg, fn } = walk(root, path);
-                if (!isFunction(fn)) {
-                    const label = path.length > 0 ? path.map(String).join('.') : '(the connected value)';
-                    throw new TypeError(`@vgai/live: ${label} is not a function on the connected session.`);
-                }
-                return fn.apply(thisArg, args);
-            });
-        },
-    });
-}

package/dist/session.d.ts

@@ -1,72 +0,0 @@
-/**
- * Session resolution for `connect()` (`index.ts`) — turns a project
- * directory into `{ port, projectRoot }` for an ALREADY-RUNNING `vgai edit`
- * session. `@vgai/live` never starts or stops a session (see the module doc
- * on `index.ts`); this only finds one.
- *
- * Two pieces, from two different sources:
- *
- *  1. Live-session DISCOVERY + PROBING (`HttpEditorTransport.listSessions`,
- *     `withTimeout`, `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`) — reused
- *     directly from `@vgai/sdk`'s `editor/transport.ts` (B3,
- *     `resolveEditorSession`'s own sibling machinery). That module is a
- *     real, tested, PUBLICLY EXPORTED part of `@vgai/sdk` — reading
- *     `~/.vgai/editor-sessions.json`, PID-liveness-filtering it, and
- *     verifying each survivor with a live `GET /__editor/project` probe is
- *     exactly the hard, easy-to-get-subtly-wrong part worth reusing rather
- *     than re-deriving.
- *
- *  2. 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"
- *     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 ->
- *     engine direction anyway — see `@vgai/sdk`'s own architecture note),
- *     so this ~10-line pure function is duplicated verbatim instead. Keep in
- *     sync if that logic ever changes.
- *
- * DELIBERATE DIVERGENCE from `resolveEditorSession` itself: that function's
- * documented precedence (see its own doc comment) falls back to "the
- * lowest-numbered port among ALL live sessions" when `ctx.projectRoot` is
- * given but matches none of them — a reasonable default for a single-agent,
- * usually-one-session tool context. `@vgai/live` explicitly does NOT reuse
- * that fallback: CLAUDE.md's editor-first workflow is emphatic that a
- * project must never be silently retargeted to a DIFFERENT project's editor
- * session (a real hazard in a multi-project/fleet setup — several unrelated
- * `vgai edit` sessions can easily be running at once). `resolveSession`
- * below matches the CLI's own stricter `getClient()` behavior instead: only
- * a session whose OWN project matches `projectRoot` is ever returned: no
- * match means a clear, actionable error, never a guess.
- */
-import { type EditorTransport } from '@vgai/sdk';
-/**
- * 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
- * `null` if none.
- */
-export declare function findProjectRootFrom(dir: string): string | null;
-/** The minimal slice of `EditorTransport` `resolveSession` actually needs — narrower than the full interface so a test double only has to implement one method. */
-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`. */
-    projectRoot: string;
-}
-export interface SessionResolutionDeps {
-    /** Session listing + liveness verification — defaults to a real `HttpEditorTransport` (`@vgai/sdk`). Overridable for tests. */
-    transport?: SessionListingTransport;
-    /** Project-root discovery — defaults to the real fs walk (`findProjectRootFrom` above). Overridable for tests. */
-    findProjectRootFrom?: (dir: string) => string | null;
-}
-/**
- * Resolve `projectDir` (default `process.cwd()`) to the port of its already-
- * 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.
- */
-export declare function resolveSession(projectDir?: string, deps?: SessionResolutionDeps): Promise<ResolvedSession>;

package/dist/session.js

@@ -1,97 +0,0 @@
-/**
- * Session resolution for `connect()` (`index.ts`) — turns a project
- * directory into `{ port, projectRoot }` for an ALREADY-RUNNING `vgai edit`
- * session. `@vgai/live` never starts or stops a session (see the module doc
- * on `index.ts`); this only finds one.
- *
- * Two pieces, from two different sources:
- *
- *  1. Live-session DISCOVERY + PROBING (`HttpEditorTransport.listSessions`,
- *     `withTimeout`, `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`) — reused
- *     directly from `@vgai/sdk`'s `editor/transport.ts` (B3,
- *     `resolveEditorSession`'s own sibling machinery). That module is a
- *     real, tested, PUBLICLY EXPORTED part of `@vgai/sdk` — reading
- *     `~/.vgai/editor-sessions.json`, PID-liveness-filtering it, and
- *     verifying each survivor with a live `GET /__editor/project` probe is
- *     exactly the hard, easy-to-get-subtly-wrong part worth reusing rather
- *     than re-deriving.
- *
- *  2. 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"
- *     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 ->
- *     engine direction anyway — see `@vgai/sdk`'s own architecture note),
- *     so this ~10-line pure function is duplicated verbatim instead. Keep in
- *     sync if that logic ever changes.
- *
- * DELIBERATE DIVERGENCE from `resolveEditorSession` itself: that function's
- * documented precedence (see its own doc comment) falls back to "the
- * lowest-numbered port among ALL live sessions" when `ctx.projectRoot` is
- * given but matches none of them — a reasonable default for a single-agent,
- * usually-one-session tool context. `@vgai/live` explicitly does NOT reuse
- * that fallback: CLAUDE.md's editor-first workflow is emphatic that a
- * project must never be silently retargeted to a DIFFERENT project's editor
- * session (a real hazard in a multi-project/fleet setup — several unrelated
- * `vgai edit` sessions can easily be running at once). `resolveSession`
- * below matches the CLI's own stricter `getClient()` behavior instead: only
- * a session whose OWN project matches `projectRoot` is ever returned: no
- * match means a clear, actionable error, never a guess.
- */
-import { existsSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, HttpEditorTransport, withTimeout, } from '@vgai/sdk';
-/**
- * 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
- * `null` if none.
- */
-export function findProjectRootFrom(dir) {
-    let cur = resolve(dir);
-    for (;;) {
-        if (existsSync(join(cur, 'vgai.game.json')))
-            return cur;
-        const parent = dirname(cur);
-        if (parent === cur)
-            return null;
-        cur = parent;
-    }
-}
-/**
- * Resolve `projectDir` (default `process.cwd()`) to the port of its already-
- * 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.
- */
-export async function resolveSession(projectDir = process.cwd(), deps = {}) {
-    const findRoot = deps.findProjectRootFrom ?? findProjectRootFrom;
-    const transport = deps.transport ?? new HttpEditorTransport();
-    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?`);
-    }
-    let sessions;
-    try {
-        sessions = await withTimeout(transport.listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS), EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, 'editor session discovery');
-    }
-    catch {
-        sessions = [];
-    }
-    const canon = resolve(projectRoot);
-    const match = sessions.find((s) => s.project !== null && resolve(s.project) === canon);
-    if (!match) {
-        const otherCount = sessions.length;
-        throw new Error(`@vgai/live: no live editor session found for ${projectRoot}. @vgai/live only attaches to ` +
-            'an already-running session — it never starts one — so run `vgai edit` in that project ' +
-            'first, then retry.' +
-            (otherCount > 0
-                ? ` (${otherCount} other live session(s) found, but none open this project — @vgai/live ` +
-                    'never silently attaches to a different project.)'
-                : ''));
-    }
-    return { port: match.port, projectRoot };
-}

package/dist/singleton.d.ts

@@ -1,18 +0,0 @@
-/**
- * A tiny memoized-async-factory primitive — the machinery behind
- * `index.ts`'s lazy top-level `editor`/`game`/`page` singletons. Pulled into
- * its own module (rather than inlined) so it's independently unit-testable
- * with a fake factory, with no need to exercise a real `connect()` (session
- * discovery, network) just to prove "two accesses, one connect".
- *
- * Caches the in-flight PROMISE, not just the resolved value — two callers
- * racing `ensure()` before the first resolves still share the SAME
- * connection attempt, not two independent ones.
- */
-export interface LazySession<T> {
-    /** Returns the memoized promise, creating it via `factory()` on first call. */
-    ensure(): Promise<T>;
-    /** Clears the memo — the NEXT `ensure()` calls `factory()` again. Exposed for tests (and for a caller that deliberately wants to reconnect); not needed in ordinary use. */
-    reset(): void;
-}
-export declare function createLazySession<T>(factory: () => Promise<T>): LazySession<T>;

package/dist/singleton.js

@@ -1,12 +0,0 @@
-export function createLazySession(factory) {
-    let promise = null;
-    return {
-        ensure() {
-            promise ??= factory();
-            return promise;
-        },
-        reset() {
-            promise = null;
-        },
-    };
-}