@vgai/live 0.4.0-canary.20260715.0

package/dist/session.js

@@ -0,0 +1,97 @@
+/**
+ * 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

@@ -0,0 +1,18 @@
+/**
+ * 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

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@vgai/live",
+  "author": "Volter AI, Inc.",
+  "license": "Apache-2.0",
+  "version": "0.4.0-canary.20260715.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/vgai-engine.git",
+    "directory": "packages/vgai-live"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@vgai/editor-sdk": "0.4.0-canary.20260715.0",
+    "@vgai/probe": "0.4.0-canary.20260715.0",
+    "@vgai/sdk": "0.4.0-canary.20260715.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.58.2 <2"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^25.3.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/editor.ts

@@ -0,0 +1,229 @@
+/**
+ * `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';
+import { operations } from '@vgai/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 };
+}
+
+const EXTENSION_KIND: Record<string, AssetKind> = {
+  '.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: string): AssetKind {
+  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 {
+  constructor(
+    private readonly 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). */
+    private readonly 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.
+   */
+  async scene(path?: string): Promise<string | null> {
+    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: ApplyDiffInput): Promise<ApplyDiffResult> {
+    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 as ApplyDiffResult;
+  }
+
+  async play(opts?: { seed?: number }): Promise<void> {
+    await this.client.play(opts);
+  }
+
+  async stop(): Promise<void> {
+    await this.client.stop();
+  }
+
+  async pause(): Promise<void> {
+    await this.client.pause();
+  }
+
+  async resume(): Promise<void> {
+    await this.client.resume();
+  }
+
+  /** Advance `n` frames (default 1) — `EditorClient.step()` sent `n` times, mirroring `vgai step` run repeatedly. */
+  async step(n = 1): Promise<void> {
+    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: string | 'all'): Promise<void> {
+    if (id === 'all') {
+      await this.client.selectAll();
+      return;
+    }
+    await this.client.select(id);
+  }
+
+  /** Mirrors `vgai deselect`. */
+  async deselect(): Promise<void> {
+    await this.client.select(null);
+  }
+
+  /** No `id` -> focus the current selection (mirrors bare `vgai focus`); `id` given -> focus that entity. */
+  async focus(id?: string): Promise<void> {
+    if (id !== undefined) {
+      await this.client.focusEntity(id);
+      return;
+    }
+    await this.client.focusSelection();
+  }
+
+  async view(preset: ViewPreset): Promise<void> {
+    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: PanelName): Promise<void> {
+    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: string, kind?: AssetKind): Promise<void> {
+    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: string, options?: AssetPreviewOptions): Promise<AssetPreviewCapture> {
+    return this.client.captureAssetPreview({ assetPath: path }, options);
+  }
+
+  async grid(on: boolean): Promise<void> {
+    await this.client.setGrid(on);
+  }
+
+  async helpers(on: boolean): Promise<void> {
+    await this.client.setHelpers(on);
+  }
+
+  async stats(on: boolean): Promise<void> {
+    await this.client.setStats(on);
+  }
+
+  async shading(mode: ShadingMode): Promise<void> {
+    await this.client.setShadingMode(mode);
+  }
+
+  /** Mirrors `vgai status` — the full live editor state as JSON. */
+  async status(): Promise<EditorState> {
+    return this.client.getState();
+  }
+
+  /** A live viewport PNG (`EditorClient.captureViewport`) — no direct CLI verb exists; this is the closest wire read. */
+  async screenshot(size?: number): Promise<ViewportCapture> {
+    return this.client.captureViewport(size);
+  }
+}

package/src/game.ts

@@ -0,0 +1,42 @@
+/**
+ * `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: number): GameClient {
+  return new GameClient({
+    transport: new RelayTransport({ port }),
+    pageErrors: [],
+    consoleErrors: [],
+    fenceTick: 0,
+    fenceSeq: 0,
+    fenceSimSeconds: 0,
+    fenceWallMs: Date.now(),
+    warmSession: false,
+  });
+}

package/src/index.ts

@@ -0,0 +1,115 @@
+/**
+ * `@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 type { GameClient } from '@vgai/probe';
+import { LiveEditor } from './editor.js';
+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';
+
+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 async function connect(
+  projectDir?: string,
+  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);
+  const page: PageStep = (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(): void {
+  lazySession.reset();
+}
+
+export const editor: LiveEditor = lazyChainProxy<LiveEditor>(() =>
+  lazySession.ensure().then((s) => s.editor),
+);
+export const game: GameClient = lazyChainProxy<GameClient>(() =>
+  lazySession.ensure().then((s) => s.game),
+);
+export const page: PageStep = lazyChainProxy<PageStep>(() =>
+  lazySession.ensure().then((s) => s.page),
+);

package/src/lazy-proxy.ts

@@ -0,0 +1,68 @@
+/**
+ * `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.
+ */
+
+type AnyFn = (...args: unknown[]) => unknown;
+
+function isFunction(value: unknown): value is AnyFn {
+  return typeof value === 'function';
+}
+
+function walk(root: unknown, path: PropertyKey[]): { thisArg: unknown; fn: unknown } {
+  if (path.length === 0) return { thisArg: undefined, fn: root };
+  let obj: Record<PropertyKey, unknown> = root as Record<PropertyKey, unknown>;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i] as PropertyKey;
+    obj = obj[key] as Record<PropertyKey, unknown>;
+  }
+  const lastKey = path[path.length - 1] as PropertyKey;
+  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<T>(
+  resolveRoot: () => Promise<unknown>,
+  path: PropertyKey[] = [],
+): T {
+  const callableTarget = (() => {}) as unknown as object;
+  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);
+      });
+    },
+  }) as T;
+}