@vgai/live 0.5.2 → 0.5.4

package/src/editor.ts

@@ -1,15 +1,14 @@
 /**
  * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (SHARED-SESSION-SPEC.md, Wave 2). Methods are named after the
+ * page }` (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
+ * separate `selectAll`, `showPanel('viewport-play')` rather than
+ * `vgai show viewport play`'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.
+ * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module never
+ * hand-rolls a `fetch` to `/__editor/command` itself. (WO-8 removed the one
+ * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
  */
 
 import type {
@@ -17,39 +16,19 @@ import type {
   AssetKind,
   AssetPreviewCapture,
   AssetPreviewOptions,
+  AssetPreviewSource,
   EditorClient,
   EditorState,
   EditorView,
+  InspectedInspection,
   PresentedEditorView,
   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 };
-}
+export type PanelName = 'viewport-edit' | 'viewport-play' | 'inspector' | 'console' | 'build';
 
 const EXTENSION_KIND: Record<string, AssetKind> = {
   '.glb': 'model',
@@ -59,6 +38,7 @@ const EXTENSION_KIND: Record<string, AssetKind> = {
   '.jpeg': 'image',
   '.webp': 'image',
   '.gif': 'image',
+  '.svg': 'image',
   '.mp3': 'audio',
   '.ogg': 'audio',
   '.wav': 'audio',
@@ -73,7 +53,10 @@ const EXTENSION_KIND: Record<string, AssetKind> = {
  * on. Callers with an unusual extension can always pass `kind` explicitly.
  */
 export function inferAssetKind(path: string): AssetKind {
-  if (path.endsWith('.vscn.json')) return 'scene';
+  // WO-8: `.vscn.json` mapped to 'scene' here. That format is deleted, and
+  // `.prefab.json` is likewise retired (PRs #578/#581/#589) but the `'prefab'`
+  // AssetKind itself still exists in `@vgai/editor-sdk`, so the mapping is left
+  // for that retirement's own follow-up rather than half-removed here.
   if (path.endsWith('.prefab.json')) return 'prefab';
   if (path.endsWith('.mat.json')) return 'material';
   const dot = path.lastIndexOf('.');
@@ -82,23 +65,26 @@ export function inferAssetKind(path: string): AssetKind {
 }
 
 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,
-  ) {}
+  /** `#`-private, not `private`: `vgai eval --list` enumerates this object's
+   *  real runtime members, and TypeScript's erased `private` would leave the
+   *  raw `EditorClient` advertised beside them. See `./game-client/`'s
+   *  `client.ts` (GameClient's field block) for the full reasoning. */
+  readonly #client: EditorClient;
+
+  constructor(client: EditorClient) {
+    this.#client = client;
+  }
 
   /**
-   * 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.
+   * The active authoring adapter's persistence destination — where a save would
+   * land (`status().savePath`).
+   *
+   * WO-8: this also took a `path` and OPENED that scene through
+   * `EditorClient.openScene` -> the `open-scene` relay verb. That verb now rejects
+   * (the `.vscn.json` format is deleted), so only the read remains.
    */
-  async scene(path?: string): Promise<string | null> {
-    if (path !== undefined) {
-      await this.client.openScene(path);
-      return path;
-    }
-    const state = await this.client.getState();
+  async scene(): Promise<string | null> {
+    const state = await this.#client.getState();
     return state.savePath;
   }
 
@@ -108,144 +94,204 @@ export class LiveEditor {
    * workspace or document payload.
    */
   async present(view: EditorView): Promise<PresentedEditorView> {
-    return this.client.present(view);
+    return this.#client.present(view);
   }
 
   /** The human editor's actual active document, selection, camera and utility. */
   async currentView(): Promise<EditorView> {
-    return this.client.currentView();
+    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);
+    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
-   * 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` lived here. It dispatched `project.scene.apply`, one of the
+   * twelve `.vscn` document tools deleted with the format, so there is nothing
+   * left for it to call. `ApplyDiffInput` / `ApplyDiffResult` went with it, and
+   * so did `projectRoot` — this was the ONE method that used it (every other
+   * method goes over the wire).
    */
-  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);
+    await this.#client.play(opts);
   }
 
   async stop(): Promise<void> {
-    await this.client.stop();
+    await this.#client.stop();
   }
 
   async pause(): Promise<void> {
-    await this.client.pause();
+    await this.#client.pause();
   }
 
   async resume(): Promise<void> {
-    await this.client.resume();
+    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();
+      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();
+      await this.#client.selectAll();
       return;
     }
-    await this.client.select(id);
+    await this.#client.select(id);
   }
 
   /** Mirrors `vgai deselect`. */
   async deselect(): Promise<void> {
-    await this.client.select(null);
+    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);
+      await this.#client.focusEntity(id);
       return;
     }
-    await this.client.focusSelection();
+    await this.#client.focusSelection();
+  }
+
+  /**
+   * Frame the edit viewport camera on one entity. Same framing as
+   * `focus(id)`, but an entity id the scene does not know THROWS, naming the
+   * id — where `focus` quietly does nothing. Reach for this whenever the next
+   * step reads the viewport (`screenshot()`, an
+   * `assetPreview(..., { stage: 'scene' })`): a framing that silently missed
+   * would otherwise be indistinguishable from one that worked.
+   */
+  async frame(entityId: string): Promise<void> {
+    await this.#client.frameEntity(entityId);
   }
 
   async view(preset: ViewPreset): Promise<void> {
-    await this.client.viewPreset(preset);
+    await this.#client.viewPreset(preset);
+  }
+
+  /**
+   * Show several instances of the running game split-screen — the whole point
+   * of multiplayer authoring: `await editor.instances(2)` puts a second view
+   * beside the first, watchable by a human, each drivable by its own bot
+   * (`game.instance(id)` / `tools.run(name, params, { instance })`). Pass a
+   * TOTAL count (default "Player 1"/"Player 2"/… labels) or explicit names
+   * (`editor.instances(['Alice', 'Bob'])`, index 0 = primary). A count of `1`
+   * (or a single name) collapses back to a single view. Requires a live play
+   * session.
+   */
+  async instances(countOrNames: number | string[]): Promise<void> {
+    await this.#client.setInstanceCount(countOrNames);
   }
 
-  /** `vgai show <viewport <scene|game>|inspector|console|build>`'s four sub-verbs, folded into one action name. */
+  /** `vgai show <viewport <edit|play>|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');
+      case 'viewport-edit':
+        await this.#client.showViewport('edit');
         return;
-      case 'viewport-game':
-        await this.client.showViewport('game');
+      case 'viewport-play':
+        await this.#client.showViewport('play');
         return;
       case 'inspector':
-        await this.client.showInspector();
+        await this.#client.showInspector();
         return;
       case 'console':
-        await this.client.toggleConsole();
+        await this.#client.toggleConsole();
         return;
       case 'build':
-        await this.client.showBuild();
+        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));
+    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);
+  /**
+   * Captures the editor's native four-view preview. A bare string is a
+   * project-relative asset path (the common case); an explicit source object
+   * targets a path, a LIVE SCENE ENTITY (`assetPreview({ entityId }, …)`) —
+   * which is what makes `options.stage: 'scene'`, the entity photographed
+   * where it stands under the scene's own lighting, reachable from here — or
+   * RAW GLB BYTES (`assetPreview({ glbBase64 }, …)`), for a model that exists
+   * only in the calling Node process's memory and has never been written to
+   * disk. `stage` defaults to `'lab'`, the neutral Asset Lab staging this has
+   * always produced, and the bytes form is lab-only.
+   */
+  async assetPreview(
+    source: string | AssetPreviewSource,
+    options?: AssetPreviewOptions,
+  ): Promise<AssetPreviewCapture> {
+    return this.#client.captureAssetPreview(
+      typeof source === 'string' ? { assetPath: source } : source,
+      options,
+    );
   }
 
   async grid(on: boolean): Promise<void> {
-    await this.client.setGrid(on);
+    await this.#client.setGrid(on);
   }
 
   async helpers(on: boolean): Promise<void> {
-    await this.client.setHelpers(on);
+    await this.#client.setHelpers(on);
   }
 
   async stats(on: boolean): Promise<void> {
-    await this.client.setStats(on);
+    await this.#client.setStats(on);
   }
 
   async shading(mode: ShadingMode): Promise<void> {
-    await this.client.setShadingMode(mode);
+    await this.#client.setShadingMode(mode);
+  }
+
+  /**
+   * READ the inspector, as data — the serialized inspection subject
+   * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
+   * "The Inspection Model"). This is the Figma-Inspect analog: whatever a
+   * human would see in the inspector right now — the subject's identity, its
+   * verbs, and every identified section in display order, with a `fields`
+   * section's CURRENT VALUES at their scriptable `path`s.
+   *
+   * Reach for it whenever the next step depends on what an object actually
+   * IS: `await editor.select(id)` then `await editor.inspect()` answers "what
+   * properties does this thing have, and what are they set to" in one call,
+   * against the same model the panel renders — no scene-graph reads, no
+   * guessing at property names.
+   *
+   * When the inspector is showing NOTHING — nothing selected on a surface
+   * with no empty-state subject of its own, which is most of them — the answer
+   * is `{none: true}`, so "the human sees no inspector" and "the read failed"
+   * are never the same value. A surface whose empty space IS a real thing (an
+   * open Asset Lab document) still answers with that subject, and never with
+   * another surface's.
+   *
+   * A `custom` section body is a named opaque: the editor renders it with
+   * React, so the wire reports its identity rather than pretending to describe
+   * its rendering — plus, when the section can say what it DISPLAYS, a `data`
+   * payload in its own vocabulary (`transform` carries
+   * `{position, rotation, scale}`, rotation in Euler XYZ degrees).
+   */
+  async inspect(): Promise<InspectedInspection> {
+    return this.#client.inspect();
   }
 
   /** Mirrors `vgai status` — the full live editor state as JSON. */
   async status(): Promise<EditorState> {
-    return this.client.getState();
+    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);
+    return this.#client.captureViewport(size);
   }
 }

package/src/game-client/bridge-heartbeat.ts

@@ -0,0 +1,61 @@
+/**
+ * run-3 dogfood friction #2 — a legitimately-progressing script built from
+ * many short `game.input.hold()` calls looked WEDGED to anything watching its
+ * stdout for liveness, even though it was making real progress. Root cause: `GameInput.hold` (client.ts) collapsed
+ * what used to be a `waitSimTime` POLL loop into a single bridge call per
+ * hold (see its own doc comment — deliberately, to cut transport round
+ * trips), so a spec built from many holds and little else can go silent on
+ * stdout between them for minutes at a time.
+ *
+ * `wait-for.ts`'s `maybeHeartbeat` already solves the analogous problem for
+ * the `waitFor`/`waitSimTime` POLL loop, but it is deliberately SIM-TICK
+ * aware (a frozen sim clock must stay heartbeat-silent so that loop's own
+ * ~30s stall guard, `WAIT_FOR_STALL_POLL_LIMIT`, can still diagnose a
+ * genuinely-stuck game rather than a heartbeat papering over it). This is
+ * the companion for `GameClient`'s generic bridge dispatch
+ * (`callBridge`/`callBridgeAsync`), which has no poll loop and no sim tick
+ * to check at all: "wire activity" here just means a bridge call was
+ * actually DISPATCHED — sequential awaits mean a new dispatch can only
+ * happen once the previous one resolved, so a genuinely wedged page (bridge
+ * calls that never resolve at all) still goes — and stays — silent. The
+ * throttle exists only to bound
+ * stdout volume during a burst of fast calls, not to filter out "fake"
+ * activity.
+ */
+
+export const BRIDGE_HEARTBEAT_INTERVAL_MS = 30_000;
+
+/** Mutable-by-replacement bookkeeping a caller threads through successive
+ *  `maybeBridgeHeartbeat` calls — mirrors `wait-for.ts`'s `HeartbeatState`
+ *  shape/style, minus the tick field (no sim-progress condition here). */
+export interface BridgeHeartbeatState {
+  lastEmitWallMs: number;
+}
+
+/** The liveness line this prints to stdout — greppable, and prefixed
+ *  distinctly from `wait-for.ts`'s `vgai-heartbeat` so the two liveness
+ *  sources are distinguishable in a run's log. */
+export function formatBridgeHeartbeatLine(testTitle: string, method: string): string {
+  return `vgai-bridge-heartbeat ${testTitle} method=${method}`;
+}
+
+/**
+ * Pure decision, called once per bridge dispatch: should a heartbeat print
+ * now, and what's the updated bookkeeping? Returns the SAME `state` object
+ * (referentially) when nothing should emit, so a caller can cheaply no-op.
+ */
+export function maybeBridgeHeartbeat(opts: {
+  nowMs: number;
+  method: string;
+  testTitle: string;
+  state: BridgeHeartbeatState;
+}): { line: string | null; state: BridgeHeartbeatState } {
+  const wallElapsed = opts.nowMs - opts.state.lastEmitWallMs;
+  if (wallElapsed >= BRIDGE_HEARTBEAT_INTERVAL_MS) {
+    return {
+      line: formatBridgeHeartbeatLine(opts.testTitle, opts.method),
+      state: { lastEmitWallMs: opts.nowMs },
+    };
+  }
+  return { line: null, state: opts.state };
+}

package/src/game-client/bridge-transport.ts

@@ -0,0 +1,73 @@
+/**
+ * The transport seam `GameClient` (`client.ts`) drives (#140). Two
+ * implementations answer the identical contract below:
+ *  - `PageTransport` (`client.ts`) — Playwright's `page.evaluate` against
+ *    `window.__vgai`, for a standalone game page the caller drives itself.
+ *  - `RelayTransport` (`relay-transport.ts`) — the editor dev-server's
+ *    session wire (`POST /__editor/command`, `bridge-call`/
+ *    `bridge-screenshot` ops), driving the SAME live session a human already
+ *    has open, with no new browser/window/vite instance.
+ *
+ * `wait-for.ts`/`events-matcher.ts`/`failure-block.ts`, and every method
+ * body on `GameClient` itself, are written against this interface only —
+ * none of them may know or care which transport is underneath (load-bearing
+ * for a planned default flip to relay-when-a-live-session-exists, and for a
+ * future one-shot REPL client reusing the same relay op). Deliberately NO
+ * `@playwright/test` import here, nor in `relay-transport.ts` — only
+ * `client.ts` is allowed to touch a live `Page` (see its own module doc).
+ */
+
+/** Result of one generic bridge-method call — thrown page/relay-side errors
+ *  never cross either transport boundary AS themselves (Node only keeps
+ *  `.message` across `page.evaluate`; HTTP/JSON strips everything but what
+ *  the server explicitly serializes), so both transports catch and report
+ *  `code`/`data` explicitly, and `GameClient.unwrap` reconstructs a
+ *  `SessionError` from that. */
+export interface BridgeCallOutcome {
+  ok: boolean;
+  result?: unknown;
+  error?: { code: string | undefined; message: string; data?: unknown };
+}
+
+export interface BridgeTransport {
+  /** Sync-style bridge call (state/stateAll/providers/commands/events/
+   *  snapshot/runTicks/input.*) — "sync-style" describes the PAGE side's own
+   *  call, not this method, which is always async across either wire. */
+  call(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome>;
+  /** Async bridge call — `invoke` (debug commands may themselves be async). */
+  callAsync(method: string, callArgs: unknown[]): Promise<BridgeCallOutcome>;
+  /** Whether the surface showing the game is currently hidden from the user
+   *  (`document.hidden` on the page transport) — feeds `HiddenRecoveryDriver`. */
+  isHidden(): Promise<boolean>;
+  /** Bring the surface showing the game to the foreground. */
+  bringToFront(): Promise<void>;
+  /** Capture a screenshot to `path` (PNG). A transport that cannot support
+   *  this should reject with a descriptive error rather than write a blank/
+   *  corrupt file. */
+  screenshot(path: string): Promise<void>;
+  /**
+   * Wave-2 "one dialect, full capability" — runs a UI-automation step
+   * written as a literal `async (page) => {...}` (`GameClient.page()`,
+   * `client.ts`). `src` is `step.toString()`; `step` is the ORIGINAL
+   * function, wrapped so its own parameter type is erased to `unknown` (only
+   * `client.ts` — the one file allowed to touch a real `Page` — ever names
+   * the `Page` type itself).
+   *
+   * The two implementations differ ON PURPOSE, and that difference is the
+   * load-bearing honesty boundary this method exists to name:
+   *  - `PageTransport` (`client.ts`) calls `step` DIRECTLY against the real
+   *    Playwright `Page` — no serialization, so closures over outer Node
+   *    values work here exactly like any ordinary `page.evaluate` callback.
+   *  - `RelayTransport` (`relay-transport.ts`) ships `src` over the wire and
+   *    reconstructs it with `new Function` INSIDE the editor page, against
+   *    an in-page shim (`packages/editor/src/playwright-shim.ts`) — closure
+   *    capture over anything outside the step's own body does NOT survive
+   *    that trip (the same limitation class as Playwright's own `evaluate`
+   *    serialization).
+   *
+   * Because the two transports differ this way, specs meant to pass
+   * unmodified under both hosts must be written as though ALWAYS
+   * serialized — inline every value the step needs.
+   */
+  runPageScript(src: string, step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+}