@vgai/live 0.4.1 → 0.5.0-canary.20260719.0

package/package.json

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

package/src/editor.ts

@@ -13,11 +13,14 @@
  */
 
 import type {
+  ActiveDocumentCapture,
   AssetKind,
   AssetPreviewCapture,
   AssetPreviewOptions,
   EditorClient,
   EditorState,
+  EditorView,
+  PresentedEditorView,
   ShadingMode,
   ViewPreset,
   ViewportCapture,
@@ -99,6 +102,25 @@ export class LiveEditor {
     return state.savePath;
   }
 
+  /**
+   * Make the connected human editor show the same subject/view as the agent.
+   * The returned URL is a compact, shareable projection — not a serialized
+   * workspace or document payload.
+   */
+  async present(view: EditorView): Promise<PresentedEditorView> {
+    return this.client.present(view);
+  }
+
+  /** The human editor's actual active document, selection, camera and utility. */
+  async currentView(): Promise<EditorView> {
+    return this.client.currentView();
+  }
+
+  /** Capture the same center document the human is currently looking at. */
+  async captureActiveDocument(size?: number): Promise<ActiveDocumentCapture> {
+    return this.client.captureActiveDocument(size);
+  }
+
   /**
    * 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

package/src/game.ts

@@ -1,6 +1,6 @@
 /**
  * `game` — the game-control half of `@vgai/live`'s `{ editor, game, page }`.
- * A `GameClient` (`@vgai/probe`) bound to a `RelayTransport` on the resolved
+ * A `GameClient` (`@vgai/e2e`) 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,
@@ -9,14 +9,14 @@
  * `GameClient` exposes is exposed here, unchanged).
  */
 
-import { GameClient, RelayTransport } from '@vgai/probe';
+import { GameClient, RelayTransport } 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/probe`'s own relay fixture
+ * 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 —
@@ -28,7 +28,7 @@ import { GameClient, RelayTransport } from '@vgai/probe';
  * 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 {
+export function createGameClient(port: number, artifactsDir?: string): GameClient {
   return new GameClient({
     transport: new RelayTransport({ port }),
     pageErrors: [],
@@ -38,5 +38,6 @@ export function createGameClient(port: number): GameClient {
     fenceSimSeconds: 0,
     fenceWallMs: Date.now(),
     warmSession: false,
+    artifactsDir,
   });
 }

package/src/index.ts

@@ -31,15 +31,16 @@
  * `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
+ * 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/probe`'s `bridge-transport.ts` (`runPageScript`'s doc comment) and
+ * `@vgai/e2e`'s `bridge-transport.ts` (`runPageScript`'s doc comment) and
  * `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 type { GameClient } from '@vgai/probe';
 import { LiveEditor } from './editor.js';
 import { createGameClient } from './game.js';
 import { lazyChainProxy } from './lazy-proxy.js';
@@ -47,12 +48,19 @@ import { type ResolvedSession, resolveSession, type SessionResolutionDeps } from
 import { createLazySession } from './singleton.js';
 import { LiveTools } from './tools.js';
 
-export type { EditorClient } from '@vgai/editor-sdk';
-export type { GameClient } from '@vgai/probe';
+export type { GameClient } from '@vgai/e2e';
+export type {
+  ActiveDocumentCapture,
+  EditorClient,
+  EditorView,
+  EditorViewDocument,
+  PresentedEditorView,
+} from '@vgai/editor-sdk';
 export type { ApplyDiffInput, ApplyDiffResult, PanelName } from './editor.js';
 export { inferAssetKind, LiveEditor } from './editor.js';
 export { createGameClient } from './game.js';
 export type {
+  ProjectSessionHint,
   ResolvedSession,
   SessionListingTransport,
   SessionResolutionDeps,
@@ -89,7 +97,10 @@ export async function connect(
   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 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 };

package/src/session.ts

@@ -4,9 +4,13 @@
  * 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:
+ * Three pieces, from two different sources:
  *
- *  1. Live-session DISCOVERY + PROBING (`HttpEditorTransport.listSessions`,
+ *  1. Exact-project discovery through `.vgai/session.json`, written by the
+ *     editor inside the project and verified against `/__editor/project`.
+ *     This is the fast path and cannot be delayed by unrelated sessions.
+ *
+ *  2. Global 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
@@ -16,7 +20,7 @@
  *     exactly the hard, easy-to-get-subtly-wrong part worth reusing rather
  *     than re-deriving.
  *
- *  2. Project-root discovery (`findProjectRootFrom` below) — LIFTED (not
+ *  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"
@@ -41,7 +45,7 @@
  * match means a clear, actionable error, never a guess.
  */
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import {
   EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
@@ -82,6 +86,67 @@ export interface SessionResolutionDeps {
   transport?: SessionListingTransport;
   /** Project-root discovery — defaults to the real fs walk (`findProjectRootFrom` above). Overridable for tests. */
   findProjectRootFrom?: (dir: string) => string | null;
+  /** Project-local session hint reader. Defaults to `.vgai/session.json`. */
+  readProjectSession?: (projectRoot: string) => ProjectSessionHint | null;
+  /** Exact-session verifier. Defaults to GET /__editor/project + canonical project matching. */
+  verifyProjectSession?: (hint: ProjectSessionHint, projectRoot: string) => Promise<boolean>;
+}
+
+export interface ProjectSessionHint {
+  port: number;
+  pid: number;
+  url: string;
+  startedAt: string;
+}
+
+function canonicalPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+function readProjectSession(projectRoot: string): ProjectSessionHint | null {
+  try {
+    const value: unknown = JSON.parse(
+      readFileSync(join(projectRoot, '.vgai', 'session.json'), 'utf8'),
+    );
+    if (typeof value !== 'object' || value === null) return null;
+    const hint = value as Record<string, unknown>;
+    if (
+      typeof hint['port'] !== 'number' ||
+      !Number.isInteger(hint['port']) ||
+      hint['port'] <= 0 ||
+      typeof hint['pid'] !== 'number' ||
+      typeof hint['url'] !== 'string' ||
+      typeof hint['startedAt'] !== 'string'
+    ) {
+      return null;
+    }
+    return hint as unknown as ProjectSessionHint;
+  } catch {
+    return null;
+  }
+}
+
+async function verifyProjectSession(
+  hint: ProjectSessionHint,
+  projectRoot: string,
+): Promise<boolean> {
+  try {
+    const response = await fetch(`http://localhost:${hint.port}/__editor/project`, {
+      signal: AbortSignal.timeout(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
+    });
+    if (!response.ok) return false;
+    const body = (await response.json()) as { project?: { path?: string } | null };
+    const servedProject = body.project?.path;
+    return (
+      servedProject !== undefined && canonicalPath(servedProject) === canonicalPath(projectRoot)
+    );
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -105,6 +170,19 @@ export async function resolveSession(
     );
   }
 
+  // The editor writes this exact-project hint at boot and removes it on
+  // shutdown. Prefer it over a global all-session scan: it is both faster and
+  // immune to an unrelated slow/dead registry entry consuming the discovery
+  // deadline. The live probe remains authoritative, so a stale file cannot
+  // attach us to the wrong project or port.
+  const localHint = (deps.readProjectSession ?? readProjectSession)(projectRoot);
+  if (
+    localHint &&
+    (await (deps.verifyProjectSession ?? verifyProjectSession)(localHint, projectRoot))
+  ) {
+    return { port: localHint.port, projectRoot };
+  }
+
   let sessions: EditorSessionInfo[];
   try {
     sessions = await withTimeout(
@@ -116,8 +194,8 @@ export async function resolveSession(
     sessions = [];
   }
 
-  const canon = resolve(projectRoot);
-  const match = sessions.find((s) => s.project !== null && resolve(s.project) === canon);
+  const canon = canonicalPath(projectRoot);
+  const match = sessions.find((s) => s.project !== null && canonicalPath(s.project) === canon);
   if (!match) {
     const otherCount = sessions.length;
     throw new Error(