@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/command-listener.ts

@@ -6,7 +6,17 @@
  * This module translates them into store method calls.
  */
 
+import { waitForHoldBudget } from '@engine/runtime/debug-bridge';
 import { parseSceneFile, SceneParseError } from '@engine/scene/parse';
+import {
+  type AssetPreviewBackground,
+  captureModelAssetPreview,
+  captureObjectAssetPreview,
+} from './asset-preview';
+import { getActiveSystems } from './authoring/active-systems';
+import { isAssetDocumentId, openAssetDocument } from './components/asset-documents';
+import { openBuildProfilesDocument } from './components/build-documents';
+import { capturePlayComposite } from './composite-screenshot';
 import { connectEvents, reportCommandResult, reportEditorState } from './editor-api';
 import { editorConsole } from './editor-console';
 import { getEditorMode } from './editor-mode';
@@ -14,10 +24,21 @@ import type { AssetKind, EditorStore, HelperVisibility } from './editor-store';
 import {
   enterPlayMode,
   exitPlayMode,
+  getGameContainer,
+  getPlayCanvas,
+  getPlayRuntimeAccess,
+  getPlayStartedAt,
+  isPlayModeActive,
   pausePlayMode,
   resumePlayMode,
   stepPlayMode,
 } from './play-mode';
+import { createPageShim, PageShimUnsupportedError } from './playwright-shim';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  closeWorkspaceDocument,
+} from './workspace-document-registry';
 
 export interface EditorCommand {
   type: string;
@@ -25,10 +46,14 @@ export interface EditorCommand {
   [key: string]: unknown;
 }
 
+/** Keep in sync with `../server/server-utils.ts`'s `CommandResult` — this is
+ *  the browser half of the same wire shape. `data` is the payload leg for
+ *  commands that answer with data (`capture-viewport`'s base64 PNG, the
+ *  Wave 5 debug-seam reads); on failures it carries structured markers
+ *  (`{ code: ... }`) the SDK matches on, never message prose. */
 export interface CommandResult {
   ok: boolean;
   error?: string;
-  /** Optional payload for commands that answer with data (e.g. `capture-viewport`'s base64 PNG). */
   data?: Record<string, unknown>;
 }
 
@@ -50,13 +75,56 @@ function collectCamera(store: EditorStore):
   };
 }
 
+/** #145 — what the human's tab is actually showing right now: page
+ *  visibility + window focus. `null` outside a real browser (the relay's
+ *  node-side tests). The agent reads this to know whether the user is
+ *  LOOKING at the shared session before deciding how to narrate/verify;
+ *  `connectCommandListener` re-reports state on visibilitychange/focus/blur
+ *  so the server's `/__editor/state` snapshot stays current between
+ *  commands. */
+function collectPresence(): { visibility: DocumentVisibilityState; focused: boolean } | null {
+  if (typeof document === 'undefined') return null;
+  return { visibility: document.visibilityState, focused: document.hasFocus() };
+}
+
 export function collectState(store: EditorStore): Record<string, unknown> {
   return {
     playState: store.playState,
+    presence: collectPresence(),
+    // Target-blaster friction #3 (#146 ledger): the play-verify loop's error
+    // channel — the same current-run-fenced uncaught-error list the relay
+    // snapshot carries (see collectPageErrors), so `vgai status` answers
+    // "did anything go wrong since play started" without a second command.
+    // [] while stopped or when nothing threw.
+    pageErrors: collectPageErrors(),
+    // Wave 5: the live loop's time-scale, so `play.status` reports the real
+    // applied value after a `set-time-scale` instead of an honest-gap null.
+    timeScale: getPlayRuntimeAccess()?.loop.timeScale ?? null,
+    // Issue #175 — the REAL loop liveness (`GameLoop.liveness`), NOT `store.
+    // playState` above: `playState` is editor UI state that stays 'playing'
+    // even while the T2.1 idle throttle has hidden-paused the loop (a hidden
+    // tab stops ticking outright, deliberately — see game-loop.ts). Reading
+    // only `playState` is exactly the gap that let a frozen game report as
+    // healthy (measured: playState "playing", sim speed 0.00x over 32.9s
+    // wall). `null` outside play mode — there is no loop to report on.
+    loopLiveness: getPlayRuntimeAccess()?.loop.liveness ?? null,
+    // D15/T-D15.6: the live session's ctx.random root seed (real — reflects
+    // the boot seed or the last successful play.seed.set), and whether the
+    // running project declares determinism.seededRandom at all. Both null/
+    // false when no first-party Game is running.
+    seed: getPlayRuntimeAccess()?.random?.seed ?? null,
+    deterministic: getPlayRuntimeAccess()?.determinismDeclared ?? false,
     selectedEntityId: store.selectedEntityId,
     selectedEntityIds: [...store.selectedEntityIds],
     activeViewportTab: store.activeViewportTab,
-    activeTabKey: store.activeTabKey,
+    // W2: asset viewers are center workspace documents now; this facet keeps
+    // its legacy meaning for control-API consumers — the active ASSET
+    // document's key, or '__inspector__' (the right rail always shows the
+    // Inspector since W2).
+    activeTabKey: (() => {
+      const activeId = activeWorkspaceDocumentId();
+      return activeId && isAssetDocumentId(activeId) ? activeId : '__inspector__';
+    })(),
     showGrid: store.showGrid,
     showHelpers: store.showHelpers,
     showStats: store.showStats,
@@ -67,6 +135,8 @@ export function collectState(store: EditorStore): Record<string, unknown> {
     snapEnabled: store.snapEnabled,
     entityCount: store.allEntities().length,
     savePath: store.savePath,
+    // SDK clients need the same persistence truth the editor UI exposes.
+    saveState: store.saveState,
     // Camera facet (B3-followup): real pose when a viewport is bound, absent
     // otherwise — never a fabricated value (see EditorStore.cameraPose).
     camera: collectCamera(store),
@@ -79,6 +149,475 @@ export function collectState(store: EditorStore): Record<string, unknown> {
   };
 }
 
+/** Surface a thrown engine error carrying a machine-readable `code`
+ *  (`DebugError`, `InputActionError` — duck-typed, so no engine-module
+ *  identity coupling) as a structured relay failure: `data.code` plus the
+ *  error's own data (registered-name lists, zod issues). The SDK maps these
+ *  to operation error codes — never by parsing message prose. */
+function structuredErrorResult(err: unknown): CommandResult {
+  const message = err instanceof Error ? err.message : String(err);
+  const e = err as { code?: unknown; data?: unknown };
+  if (typeof e?.code === 'string') {
+    const extra = typeof e.data === 'object' && e.data !== null ? e.data : {};
+    return { ok: false, error: message, data: { ...extra, code: e.code } };
+  }
+  return { ok: false, error: message };
+}
+
+const notPlayingResult = (): CommandResult => ({
+  ok: false,
+  error: 'not in play mode — start play before using the debug seam',
+});
+
+/** Duck-typed structured error (see `structuredErrorResult` above) — a plain
+ *  `Error` carrying a machine-readable `code` (and optional `data`), the same
+ *  shape `DebugError`/`InputActionError` already throw. Used by
+ *  `dispatchBridgeMethod` below for its OWN precondition failures (no debug
+ *  adapter installed, no InputManager wired) so they survive
+ *  `structuredErrorResult` exactly like an engine-thrown error would. */
+function bridgeError(code: string, message: string, data?: Record<string, unknown>): Error {
+  const err = new Error(message) as Error & { code: string; data?: unknown };
+  err.code = code;
+  if (data) err.data = data;
+  return err;
+}
+
+/**
+ * #140 — the generic session-wire dispatch table: the SAME method-name
+ * surface `window.__vgai` exposes (`@engine/runtime/debug-bridge`'s
+ * `VgaiDebugHandle` — `state`/`stateAll`/`providers`/`commands`/`events`/
+ * `snapshot`/`invoke`/`runTicks`/`input.*`), built from the SAME
+ * registry-backed accessors this file's own `list-gameplay-state`/
+ * `inject-input`/`run-ticks` cases already use. This is what makes the
+ * `bridge-call` relay op (below) a session-generic primitive rather than a
+ * probe-specific one — any client of the live session (the `@vgai/probe`
+ * `RelayTransport`, a future one-shot `vgai game state/call/hold` REPL) can
+ * issue `{method, callArgs}` against it with no dependency on a probe run's
+ * own lifecycle/env, and get byte-identical dispatch to the page-transport's
+ * `page.evaluate(bridgeCallInPage)` (D17) — without requiring the editor tab
+ * to be loaded with `?vgai-debug=1` (that gate exists for the bridge's own
+ * production exposure; this relay is already local-loopback-only — see
+ * `editor-server.ts`'s CSRF/origin guard).
+ */
+/** #146 — uncaught page errors from the CURRENT play run, for the relay
+ *  `snapshot`. Reads the editor console's 'runtime'-source error entries
+ *  (fed by ViewportPanel's window error/unhandledrejection capture — the
+ *  same events, same message format as `window.__vgai`'s own pageErrors
+ *  ring buffer), fenced to entries logged at/after play start. Same 100-cap
+ *  as the bridge (`PAGE_ERROR_CAP`), keeping the most recent. */
+function collectPageErrors(): string[] {
+  const startedAt = getPlayStartedAt();
+  if (startedAt === null) return [];
+  return editorConsole
+    .getEntries()
+    .filter((e) => e.level === 'error' && e.source === 'runtime' && e.timestamp >= startedAt)
+    .slice(-100)
+    .map((e) => (e.count > 1 ? `${e.message} (×${e.count})` : e.message));
+}
+
+async function dispatchBridgeMethod(method: string, callArgs: unknown[]): Promise<unknown> {
+  const debug = getActiveSystems().debug;
+  const requireDebug = () => {
+    if (!debug) {
+      throw bridgeError(
+        'DEBUG_ADAPTER_UNAVAILABLE',
+        `session wire: "${method}" — this game exposes no debug adapter`,
+      );
+    }
+    return debug;
+  };
+  switch (method) {
+    case 'state':
+      return requireDebug().state(callArgs[0] as string);
+    case 'stateAll':
+      return requireDebug().stateAll();
+    case 'providers':
+      return requireDebug().providers();
+    case 'commands':
+      return requireDebug().commands();
+    case 'events':
+      return requireDebug().events(
+        callArgs[0] as number | undefined,
+        callArgs[1] as number | undefined,
+      );
+    case 'snapshot': {
+      const adapter = requireDebug();
+      return {
+        time: adapter.state('time') as { simSeconds: number; tick: number },
+        state: adapter.stateAll(),
+        // Run-4 friction #5 — same `sinceTick`/`sinceSeq` contract as the
+        // in-page bridge's `snapshot()` (`runtime/debug-bridge.ts`): both
+        // doors must fence identically, or a probe running `--in-editor`
+        // (this door) vs. standalone (that door) could disagree about which
+        // events are "new".
+        events: adapter.events(
+          callArgs[0] as number | undefined,
+          callArgs[1] as number | undefined,
+        ),
+        // #146 (closes the #140 honest-empty gap): the editor page already
+        // funnels window error/unhandledrejection into the editor console as
+        // level 'error' / source 'runtime' (ViewportPanel's error-capture
+        // block) — the SAME events and message format `window.__vgai`'s own
+        // handle buffers. Fenced to the current play run via
+        // getPlayStartedAt() so a probe never reads a previous run's stale
+        // failures, capped at 100 for parity with the bridge's ring buffer.
+        pageErrors: collectPageErrors(),
+      };
+    }
+    case 'invoke': {
+      const name = callArgs[0] as string;
+      const invokeArgs = (callArgs[1] as unknown[]) ?? [];
+      return requireDebug().invoke(name, invokeArgs);
+    }
+    case 'runTicks': {
+      const runtime = getPlayRuntimeAccess();
+      if (!runtime?.runTicks) {
+        throw bridgeError(
+          'RUN_TICKS_UNAVAILABLE',
+          'this play session has no first-party Game to run ticks on',
+        );
+      }
+      const n = callArgs[0] as number;
+      const opts = callArgs[1] as { render?: 'last' | 'all' | 'none' } | undefined;
+      runtime.runTicks(n, opts);
+      return undefined;
+    }
+    case 'input.setVirtualAction':
+    case 'input.tapVirtualAction':
+    case 'input.clearVirtualActions':
+    // Wave-2 bridge↔wire coverage-parity gate (`bridge-wire-parity.test.ts`)
+    // closed this trio's gap: `startRecording`/`stopRecording`/`isRecording`
+    // exist on the page bridge's `VgaiDebugInputHandle` (`runtime/
+    // debug-bridge.ts`) but had no relay case at all — an agent driving the
+    // input-trace recorder over the session wire (RelayTransport) instead of
+    // `?vgai-debug=1` simply had no door to it. Same single optional
+    // trailing `worldId` shape as `clearVirtualActions`.
+    case 'input.startRecording':
+    case 'input.stopRecording':
+    case 'input.isRecording': {
+      const runtime = getPlayRuntimeAccess();
+      // D15/T-D15.5 (rebase composition with #140): this wire is a THIRD
+      // door to the virtual-input target — it must resolve through the SAME
+      // `DebugRegistry.getVirtualInputTarget(worldId?)` the page bridge
+      // (`window.__vgai.input.*`) and the `inject-input` relay case use, so
+      // no two doors can ever disagree about which world an unqualified
+      // actuation targets. Each method takes the page bridge's own optional
+      // trailing `worldId` (byte-parity with `VgaiDebugInputHandle`); an
+      // explicit, unregistered id throws the registry's structured
+      // `DEBUG_INPUT_WORLD_NOT_FOUND`, shipped back over the wire as-is.
+      const worldId = (
+        method === 'input.setVirtualAction'
+          ? callArgs[2]
+          : method === 'input.tapVirtualAction'
+            ? callArgs[1]
+            : callArgs[0]
+      ) as string | undefined;
+      const inputTarget = runtime ? runtime.getInputTarget(worldId) : null;
+      if (!inputTarget) {
+        throw bridgeError(
+          'DEBUG_INPUT_UNAVAILABLE',
+          `session wire: ${method}() has no virtual-input target wired — no default threejs ` +
+            "world has mounted yet, or this project's mount path never wired one",
+        );
+      }
+      if (method === 'input.setVirtualAction') {
+        return inputTarget.setVirtualAction(
+          callArgs[0] as string,
+          callArgs[1] as boolean | number | { x: number; y: number },
+        );
+      }
+      if (method === 'input.tapVirtualAction') {
+        return inputTarget.tapVirtualAction(callArgs[0] as string);
+      }
+      if (method === 'input.clearVirtualActions') {
+        inputTarget.clearVirtualActions();
+        return undefined;
+      }
+      if (method === 'input.startRecording') {
+        inputTarget.startInputRecording();
+        return undefined;
+      }
+      if (method === 'input.stopRecording') {
+        inputTarget.stopInputRecording();
+        return undefined;
+      }
+      return inputTarget.isInputRecording();
+    }
+    case 'input.scheduleActionAtTick': {
+      // Wave-2 bridge↔wire coverage-parity gate: `window.__vgai.input.
+      // scheduleActionAtTick` (`runtime/debug-bridge.ts`, D15/T-D15.5) had NO
+      // bridge-call case — it was reachable over the relay ONLY via the
+      // separate `inject-input` command's `atTick` field (see that case,
+      // above), never by this method name. Same `getInputTarget(worldId?)`
+      // resolution as the other `input.*` cases; forwards `tick`/`action`/
+      // `value` straight through and returns whatever the target returns
+      // (`void`, same as the page bridge's own `scheduleActionAtTick`).
+      const runtime = getPlayRuntimeAccess();
+      const tick = callArgs[0] as number;
+      const action = callArgs[1] as string;
+      const value = callArgs[2] as boolean | number | { x: number; y: number };
+      const worldId = callArgs[3] as string | undefined;
+      const inputTarget = runtime ? runtime.getInputTarget(worldId) : null;
+      if (!inputTarget) {
+        throw bridgeError(
+          'DEBUG_INPUT_UNAVAILABLE',
+          'session wire: input.scheduleActionAtTick() has no virtual-input target wired — no ' +
+            "default threejs world has mounted yet, or this project's mount path never wired one",
+        );
+      }
+      return inputTarget.scheduleActionAtTick(tick, action, value);
+    }
+    case 'input.injectPointerDelta':
+    case 'input.injectPointerPosition': {
+      // Wave-2 pointer-dispatch op: `window.__vgai.input.injectPointerDelta`/
+      // `injectPointerPosition` (`runtime/debug-bridge.ts`) had no relay
+      // case — this is the HONEST gameplay-seam reading of "pointer
+      // dispatch" (docs/SHARED-SESSION-SPEC.md): the engine's existing
+      // virtual pointer-injection, never a synthesized DOM mouse event (that
+      // boundary belongs to the future playwright shim). Same
+      // `getInputTarget(worldId?)` resolution as every other `input.*` case.
+      const runtime = getPlayRuntimeAccess();
+      const sourceId = callArgs[0] as string;
+      const value = callArgs[1] as { x: number; y: number };
+      const worldId = callArgs[2] as string | undefined;
+      const inputTarget = runtime ? runtime.getInputTarget(worldId) : null;
+      if (!inputTarget) {
+        throw bridgeError(
+          'DEBUG_INPUT_UNAVAILABLE',
+          `session wire: ${method}() has no virtual-input target wired — no default threejs ` +
+            "world has mounted yet, or this project's mount path never wired one",
+        );
+      }
+      if (method === 'input.injectPointerDelta') {
+        inputTarget.injectPointerDelta(sourceId, value);
+      } else {
+        inputTarget.injectPointerPosition(sourceId, value);
+      }
+      return undefined;
+    }
+    case 'holdFor': {
+      // #140/D17: byte-identical semantics to `window.__vgai.holdFor` (door
+      // a, `runtime/debug-bridge.ts`) — same `getInputTarget(worldId?)`
+      // resolution as the `input.*` cases above, same `waitForHoldBudget`
+      // poll/stall loop (imported, not hand-copied, so the two doors can
+      // never silently drift apart), reached through `requireDebug().state
+      // ('time')` instead of a `DebugRegistry` (this relay only has
+      // `getActiveSystems().debug`, not the registry itself).
+      const runtime = getPlayRuntimeAccess();
+      const worldId = callArgs[2] as string | undefined;
+      const inputTarget = runtime ? runtime.getInputTarget(worldId) : null;
+      if (!inputTarget) {
+        throw bridgeError(
+          'DEBUG_INPUT_UNAVAILABLE',
+          'session wire: holdFor() has no virtual-input target wired — no default threejs ' +
+            "world has mounted yet, or this project's mount path never wired one",
+        );
+      }
+      const action = callArgs[0] as string;
+      const simSeconds = callArgs[1] as number;
+      const setResult = inputTarget.setVirtualAction(action, true);
+      if (!setResult.delivered) {
+        inputTarget.clearVirtualActions();
+        return { delivered: false, reason: setResult.reason };
+      }
+      const { stalled } = await waitForHoldBudget(
+        requireDebug(),
+        simSeconds,
+        runtime?.runTicks ? (n) => runtime.runTicks?.(n, { render: 'last' }) : undefined,
+      );
+      inputTarget.clearVirtualActions();
+      return stalled
+        ? { delivered: false, reason: 'play stopped during hold' }
+        : { delivered: true };
+    }
+    default:
+      throw bridgeError('UNKNOWN_BRIDGE_METHOD', `session wire: unknown bridge method "${method}"`);
+  }
+}
+
+/** `bridge-call` relay op handler — session not playing is the one
+ *  precondition checked up front (mirrors every other debug-seam case in
+ *  this file); everything else is `dispatchBridgeMethod`'s own structured
+ *  failure, caught here and shipped back via `structuredErrorResult` so
+ *  `code`/`data` survive the relay round trip byte-equivalent to the
+ *  page-transport's `unwrap()` path (`packages/vgai-probe/src/client.ts`). */
+async function handleBridgeCall(cmd: EditorCommand): Promise<CommandResult> {
+  if (!isPlayModeActive()) return notPlayingResult();
+  const method = cmd['method'] as string;
+  const callArgs = (cmd['callArgs'] as unknown[] | undefined) ?? [];
+  try {
+    const result = await dispatchBridgeMethod(method, callArgs);
+    return { ok: true, data: { result } };
+  } catch (err) {
+    return structuredErrorResult(err);
+  }
+}
+
+/** `bridge-screenshot` relay op handler — captures the live play-mode game
+ *  view and returns it in the same `{base64, mimeType}` shape
+ *  `capture-viewport` already uses. #146: the capture is now the FULL game
+ *  stack — canvas(es) plus the DOM UI layers (React adapter roots,
+ *  react-world layers) composited via `capturePlayComposite` — because a
+ *  canvas-only frame of a game whose score/health lives in the HUD is not
+ *  "what the game looks like". When the composite leg can't run (no
+ *  container, no DOM Image/XMLSerializer — e.g. the node-side relay tests —
+ *  or a rasterization failure), it degrades to the original canvas-only
+ *  `toDataURL` capture (readable because every runtime-mounted canvas sets
+ *  `preserveDrawingBuffer: true` — `create-runtime.ts`, D5 §1/§4), marked
+ *  honestly with `composite: false`. A caller (`RelayTransport.screenshot`
+ *  in `@vgai/probe`) writes the PNG to disk — this relay op stays a pure
+ *  "hand back the pixels" primitive, matching `bridge-call`'s own
+ *  session-generic, probe-lifecycle-free shape. */
+async function handleBridgeScreenshot(cmd: EditorCommand): Promise<CommandResult> {
+  if (!isPlayModeActive()) return notPlayingResult();
+  const canvas = getPlayCanvas();
+  // A paused canvas is provably stale, but a React-only root has no canvas:
+  // its DOM is self-driven and `capturePlayComposite` has its own bounded
+  // hidden-tab paint fallback. Do not apply a canvas freshness rule to the
+  // DOM-only adapter surface.
+  const runtime = getPlayRuntimeAccess();
+  if (canvas && runtime?.loop.liveness === 'hidden-paused') {
+    if (cmd['refreshHiddenFrame'] === true && runtime.runTicks) {
+      try {
+        runtime.runTicks(1, { render: 'last' });
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+    } else {
+      return {
+        ok: false,
+        error:
+          'cannot capture a fresh game frame while the editor tab is hidden — focus/open the editor tab and retry, or request a deterministic hidden-frame refresh',
+        data: { code: 'BRIDGE_SCREENSHOT_STALE' },
+      };
+    }
+  }
+  const container = getGameContainer();
+  if (
+    container &&
+    typeof Image !== 'undefined' &&
+    typeof XMLSerializer !== 'undefined' &&
+    typeof container.getBoundingClientRect === 'function'
+  ) {
+    try {
+      const composite = await capturePlayComposite(container);
+      if (composite.layers.canvases === 0 && composite.layers.domOverlays === 0) {
+        throw new Error('composite screenshot: no game layers');
+      }
+      return {
+        ok: true,
+        data: {
+          base64: composite.base64,
+          mimeType: composite.mimeType,
+          composite: true,
+          layers: composite.layers,
+        },
+      };
+    } catch {
+      // Degrade to the canvas-only leg below — a HUD-less capture beats no
+      // capture, and `composite: false` keeps the degradation visible.
+    }
+  }
+  // A native React game has no canvas by design. The composite leg above is
+  // therefore the PRIMARY capture path for a React-only root, not an
+  // enhancement after a canvas precondition. Only fail once both the full
+  // game-stack capture and the canvas fallback are unavailable.
+  if (!canvas) {
+    return {
+      ok: false,
+      error: 'no play-mode game surface is mounted yet',
+      data: { code: 'BRIDGE_SCREENSHOT_UNAVAILABLE' },
+    };
+  }
+  try {
+    const dataUrl = canvas.toDataURL('image/png');
+    const comma = dataUrl.indexOf(',');
+    const base64 = comma >= 0 ? dataUrl.slice(comma + 1) : dataUrl;
+    return { ok: true, data: { base64, mimeType: 'image/png', composite: false } };
+  } catch (err) {
+    // e.g. a tainted canvas (a cross-origin texture loaded with no CORS
+    // headers, which WebGL refuses to read back even with
+    // preserveDrawingBuffer:true) — a distinct, rarer failure from "no
+    // canvas at all" above, surfaced honestly rather than swallowed.
+    return {
+      ok: false,
+      error: `bridge-screenshot: canvas capture failed — ${err instanceof Error ? err.message : String(err)}`,
+      data: { code: 'BRIDGE_SCREENSHOT_UNAVAILABLE' },
+    };
+  }
+}
+
+/**
+ * `page-script` relay op handler — Wave-2 "the playwright shim in the editor
+ * page + script-mode wire op" (`docs/SHARED-SESSION-SPEC.md` §7). Standalone
+ * command (like `bridge-screenshot`), NOT a `bridge-call` method: this is
+ * editor-page UI automation, not the game-debug seam, so it deliberately
+ * stays outside `dispatchBridgeMethod`'s switch — the bridge↔wire parity gate
+ * (`bridge-wire-parity.test.ts`) only walks THAT switch, and must never need
+ * to know about this op.
+ *
+ * `cmd['src']` is a UI-automation step's `Function.prototype.toString()`
+ * source (`@vgai/probe`'s `RelayTransport.runPageScript` — see that file's
+ * doc comment for the client-facing half of the wire contract). Reconstructed
+ * here with `new Function` and run against a fresh `createPageShim` rooted at
+ * the SAME game container `bridge-screenshot`'s composite capture uses
+ * (`getGameContainer` — never editor chrome). `PageShimUnsupportedError`
+ * (thrown the instant the step touches an unimplemented `Page`/`Locator`
+ * member) is distinguished from any other step failure so a caller can tell
+ * "this shim doesn't support that yet" apart from "the step's own assertion
+ * failed" — both are structured failures, never a hang or a silent
+ * mis-report.
+ */
+async function handlePageScript(cmd: EditorCommand): Promise<CommandResult> {
+  if (!isPlayModeActive()) return notPlayingResult();
+  const src = cmd['src'];
+  if (typeof src !== 'string') {
+    return { ok: false, error: 'page-script requires a string "src" (the step\'s toString())' };
+  }
+  const container = getGameContainer();
+  if (!container) {
+    return {
+      ok: false,
+      error: 'page-script: no play-mode game container is mounted yet',
+      data: { code: 'PAGE_SCRIPT_ERROR' },
+    };
+  }
+  let step: (page: unknown) => unknown;
+  try {
+    // Reconstructing a wire-carried step's source is the documented wire
+    // contract (Wave-2 decision 2) — the same limitation class as
+    // Playwright's own evaluate serialization: closures over anything
+    // outside the step's own body do NOT survive the trip.
+    step = new Function('page', `return (${src})(page)`) as (page: unknown) => unknown;
+  } catch (err) {
+    return {
+      ok: false,
+      error: `page-script: failed to reconstruct the step function from source — ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      data: { code: 'PAGE_SCRIPT_ERROR' },
+    };
+  }
+  const page = createPageShim(container);
+  try {
+    const result = await step(page);
+    return { ok: true, data: { result: result === undefined ? null : result } };
+  } catch (err) {
+    if (err instanceof PageShimUnsupportedError) {
+      return {
+        ok: false,
+        error: err.message,
+        data: { code: 'PAGE_SHIM_UNSUPPORTED', member: err.member, supported: [...err.supported] },
+      };
+    }
+    return {
+      ok: false,
+      error: `page-script: step threw — ${err instanceof Error ? err.message : String(err)}`,
+      data: { code: 'PAGE_SCRIPT_ERROR' },
+    };
+  }
+}
+
 /** Validate the current scene document against the Zod schema. */
 function validateCurrentScene(store: EditorStore): CommandResult {
   const doc = store.getDocument();
@@ -93,6 +632,47 @@ function validateCurrentScene(store: EditorStore): CommandResult {
   }
 }
 
+async function handleAssetPreviewCommand(
+  store: EditorStore,
+  cmd: EditorCommand,
+): Promise<CommandResult> {
+  const assetPath = cmd['assetPath'];
+  const entityId = cmd['entityId'];
+  if ((typeof assetPath === 'string') === (typeof entityId === 'string')) {
+    return {
+      ok: false,
+      error: 'capture-asset-preview requires exactly one of assetPath or entityId.',
+    };
+  }
+  const width = cmd['width'];
+  const height = cmd['height'];
+  const background = cmd['background'];
+  if (
+    (width !== undefined && typeof width !== 'number') ||
+    (height !== undefined && typeof height !== 'number') ||
+    (background !== undefined && background !== 'neutral' && background !== 'transparent')
+  ) {
+    return { ok: false, error: 'Invalid asset preview dimensions or background.' };
+  }
+  if (typeof entityId === 'string' && !store.objectMap.has(entityId)) {
+    return { ok: false, error: `Entity not found: ${entityId}` };
+  }
+  try {
+    const options = {
+      ...(typeof width === 'number' ? { width } : {}),
+      ...(typeof height === 'number' ? { height } : {}),
+      ...(background ? { background: background as AssetPreviewBackground } : {}),
+    };
+    const capture =
+      typeof assetPath === 'string'
+        ? await captureModelAssetPreview(assetPath, options)
+        : captureObjectAssetPreview(store.objectMap.get(entityId as string)!, options);
+    return { ok: true, data: { ...capture } };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 /**
  * Exported (alongside `collectState` above) so unit tests can dispatch
  * commands directly against a headless `EditorStore`, with no SSE/server
@@ -107,6 +687,21 @@ export async function handleCommand(
   switch (cmd['type']) {
     // Play control
     case 'play': {
+      // Fix for the ghost-runtime bug — deliberately no `isPlayModeActive()`
+      // guard here: `play` on an already-playing (or still-booting) session
+      // is a RESTART, not a no-op, matching the SDK's own documented contract
+      // (`play.start`'s summary: "Start (or restart) play mode" —
+      // `packages/vgai-sdk/src/play/lifecycle-operations.ts`). What used to
+      // make a restart unsafe was `enterPlayMode()` having no reentrancy
+      // guard for the async-boot window before it assigns `_session` — two
+      // overlapping calls ran their entire prologues concurrently and
+      // corrupted shared module state (proven by a real console-patching
+      // stack overflow — see `play-mode-reentry-ghost.test.ts`). That is
+      // fixed at the source in `enterPlayMode()` itself (a FIFO queue
+      // serializes every invocation), so every caller of THIS case — CLI,
+      // SDK, a UI Play-button click racing a relayed command — gets a safe,
+      // clean restart for free without needing a guard here too.
+      //
       // Validate before play — enterPlayMode() also validates, but we need
       // the error message to flow back to the SDK/CLI.
       const validation = validateCurrentScene(store);
@@ -114,7 +709,11 @@ export async function handleCommand(
         return validation;
       }
       try {
-        await enterPlayMode();
+        // D15/T-D15.6 (objection-4 fix) — `vgai play --seed <n>` relays as
+        // `cmd['seed']`; `enterPlayMode`'s explicit-config seed leg (beats
+        // manifest.determinism.defaultSeed/?vgai-seed=).
+        const seed = cmd['seed'];
+        await enterPlayMode(typeof seed === 'number' ? seed : undefined);
       } catch (err) {
         return { ok: false, error: err instanceof Error ? err.message : String(err) };
       }
@@ -178,15 +777,35 @@ export async function handleCommand(
     case 'viewport-tab':
       store.setActiveViewportTab(cmd['tab'] as 'scene' | 'game');
       break;
-    case 'active-tab':
-      store.setActiveTab(cmd['key'] as string);
+    // W2: the legacy right-rail tab commands keep their key vocabulary but
+    // now drive the CENTER workspace documents (`asset-documents.tsx`).
+    // '__inspector__' ("show the Inspector") is a no-op now: the right rail
+    // ALWAYS shows the Inspector — nothing displaces it anymore (§10.3).
+    case 'active-tab': {
+      const key = cmd['key'] as string;
+      if (key !== '__inspector__') activateWorkspaceDocument(key);
       break;
+    }
     case 'open-asset-tab':
-      store.openAssetTab(cmd['path'] as string, cmd['kind'] as AssetKind);
+      openAssetDocument(store, cmd['path'] as string, cmd['kind'] as AssetKind);
       break;
-    case 'close-asset-tab':
-      store.closeAssetTab(cmd['key'] as string);
+    case 'close-asset-tab': {
+      // Legacy key vocabulary: the deleted store-era `closeAssetTab` only
+      // ever acted on asset tabs and no-op'd for anything else (scene/game/
+      // story keys included). `closeWorkspaceDocument` itself has no such
+      // guard — it closes ANY registered id, pinned or not (`closeable:
+      // false` is only a UI-affordance rule, not a registry invariant; see
+      // workspace-document-registry.ts) — so this command must keep the
+      // no-op itself. `isAssetDocumentId` is exactly the legacy asset key
+      // vocabulary check (project asset path / `asset-lab:entity:<id>` /
+      // `online:<source>:<id>` — see asset-documents.tsx), so gating on it
+      // blocks the pinned `workspace:scene`/`workspace:game` ids (and any
+      // story `story:<path>#<name>` id) while preserving the real behavior
+      // for actual asset tabs.
+      const key = cmd['key'] as string;
+      if (isAssetDocumentId(key)) closeWorkspaceDocument(key);
       break;
+    }
     case 'toggle-command-palette':
       store.toggleCommandPalette();
       break;
@@ -194,7 +813,10 @@ export async function handleCommand(
       window.dispatchEvent(new CustomEvent('editor:toggle-console'));
       break;
     case 'show-build':
-      window.dispatchEvent(new CustomEvent('editor:show-build-tab'));
+      // W3 build split: the config surface is the Build Profiles CENTER
+      // document (build-documents.tsx); the log streams into the Build
+      // Output utility. Same command vocabulary, new (semantic) home.
+      openBuildProfilesDocument(store);
       break;
     case 'capture-viewport': {
       // Fresh, unthrottled on-demand capture (see EditorStore.captureViewportImage's
@@ -213,6 +835,8 @@ export async function handleCommand(
       const base64 = comma >= 0 ? dataUrl.slice(comma + 1) : dataUrl;
       return { ok: true, data: { base64, mimeType: 'image/png' } };
     }
+    case 'capture-asset-preview':
+      return handleAssetPreviewCommand(store, cmd);
 
     // Scene loading
     case 'open-scene': {
@@ -266,16 +890,242 @@ export async function handleCommand(
       if (store.snapEnabled !== (cmd['enabled'] as boolean)) store.toggleSnap();
       break;
 
+    // Debug seam relay (Wave 5, docs/SYNTHETIC-PLAYER-SPEC.md §3.5): all six
+    // cases read/actuate the LIVE play session's game-scoped debug registry
+    // (`SystemAdapters.debug`, installed by `setActiveSystems` on play enter)
+    // or its InputManager/GameLoop (via `getPlayRuntimeAccess`). A stopped
+    // session answers with a structured failure, never a fabricated success;
+    // a running game that exposes NO debug adapter (a non-first-party mount)
+    // degrades to the honest empty/null shape.
+    case 'list-gameplay-state': {
+      const debug = getActiveSystems().debug;
+      if (!debug) {
+        return isPlayModeActive() ? { ok: true, data: { providers: [] } } : notPlayingResult();
+      }
+      return { ok: true, data: { providers: debug.providers() } };
+    }
+    case 'inspect-gameplay-state': {
+      const debug = getActiveSystems().debug;
+      if (!debug) {
+        return isPlayModeActive() ? { ok: true, data: { state: null } } : notPlayingResult();
+      }
+      const keys = cmd['keys'] as string[] | undefined;
+      try {
+        const state: Record<string, unknown> = {};
+        if (keys && keys.length > 0) {
+          for (const key of keys) state[key] = debug.state(key);
+        } else {
+          Object.assign(state, debug.stateAll());
+        }
+        return { ok: true, data: { state } };
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+    }
+    case 'list-debug-commands': {
+      const debug = getActiveSystems().debug;
+      if (!debug) {
+        return isPlayModeActive() ? { ok: true, data: { commands: [] } } : notPlayingResult();
+      }
+      return { ok: true, data: { commands: debug.commands() } };
+    }
+    case 'invoke-debug-command': {
+      const debug = getActiveSystems().debug;
+      if (!debug) {
+        if (!isPlayModeActive()) return notPlayingResult();
+        // Honest not-registered shape: no adapter means NOTHING is registered.
+        return {
+          ok: false,
+          error: `debug: no command registered under "${cmd['name']}" — this game exposes no debug adapter`,
+          data: { code: 'DEBUG_COMMAND_NOT_REGISTERED', registered: [] },
+        };
+      }
+      try {
+        const result = await debug.invoke(cmd['name'] as string, (cmd['args'] as unknown[]) ?? []);
+        return { ok: true, data: { result } };
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+    }
+    case 'inject-input': {
+      const runtime = getPlayRuntimeAccess();
+      if (!runtime) {
+        return { ok: false, error: 'not in play mode — start play before injecting input' };
+      }
+      // D15/T-D15.5 (review objection 2's fix) — resolved through the SAME
+      // per-world `DebugRegistry.getVirtualInputTarget(worldId?)` the debug
+      // bridge's `window.__vgai.input.*` calls, instead of the old
+      // `Game.input` (always the DEFAULT world only) — an explicit
+      // `cmd['worldId']` reaches that world specifically; omitted resolves
+      // to the same default both doors now share. Throws
+      // `DEBUG_INPUT_WORLD_NOT_FOUND` (caught below) for an explicit,
+      // unregistered world id.
+      let input: ReturnType<typeof runtime.getInputTarget>;
+      try {
+        input = runtime.getInputTarget(cmd['worldId'] as string | undefined);
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+      if (!input) {
+        return {
+          ok: false,
+          error: 'this play session has no first-party InputManager to inject into',
+        };
+      }
+      try {
+        // Action-level is primary (frozen decision, spec §3.2): the honest
+        // gated path — a gated actuation surfaces {delivered:false, reason},
+        // never a false ok. The four legacy kinds map to the persistent
+        // test-source injectors (read back only through declared test_*
+        // bindings, so `delivered` here means "the source was written").
+        if (cmd['kind'] === 'action') {
+          const atTick = cmd['atTick'];
+          // D15/T-D15.5 — `atTick` defers to InputManager.scheduleActionAtTick
+          // instead of an immediate setVirtualAction. scheduleActionAtTick
+          // throws InputActionError/a valueType mismatch (same as
+          // setVirtualAction) or InputTickError ('TICK_ALREADY_PASSED',
+          // data.currentTick) — all caught by this case's outer try/catch
+          // below via structuredErrorResult.
+          if (typeof atTick === 'number') {
+            input.scheduleActionAtTick(
+              atTick,
+              cmd['action'] as string,
+              cmd['value'] as boolean | number | { x: number; y: number },
+            );
+            return { ok: true, data: { scheduled: true, tick: atTick } };
+          }
+          const outcome = input.setVirtualAction(
+            cmd['action'] as string,
+            cmd['value'] as boolean | number | { x: number; y: number },
+          );
+          return { ok: true, data: outcome };
+        }
+        const sourceId = cmd['sourceId'] as string;
+        switch (cmd['kind']) {
+          case 'axis':
+            input.injectAxis(sourceId, cmd['value'] as number);
+            break;
+          case 'vector2':
+            input.injectVector2(sourceId, cmd['value'] as { x: number; y: number });
+            break;
+          case 'pointerDelta':
+            input.injectPointerDelta(sourceId, cmd['value'] as { x: number; y: number });
+            break;
+          case 'pointerPosition':
+            input.injectPointerPosition(sourceId, cmd['value'] as { x: number; y: number });
+            break;
+          default:
+            return { ok: false, error: `unknown injection kind "${cmd['kind']}"` };
+        }
+        return { ok: true, data: { delivered: true } };
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+    }
+    case 'set-time-scale': {
+      const runtime = getPlayRuntimeAccess();
+      if (!runtime) {
+        return { ok: false, error: 'not in play mode — start play before setting time-scale' };
+      }
+      runtime.loop.timeScale = cmd['timeScale'] as number;
+      // Read back after the loop's own [0,8] clamp so the caller sees the
+      // value actually applied.
+      return { ok: true, data: { timeScale: runtime.loop.timeScale } };
+    }
+    // D15/T-D15.6 — the `play.seed.set` relay case (`docs/D15-DETERMINISM-
+    // DESIGN.md` §2.d): reaches the live session's `ctx.random.reseed(seed)`
+    // through `getPlayRuntimeAccess()`'s `random` accessor. Gated on
+    // `determinismDeclared` (the running project's manifest
+    // `determinism.seededRandom`, per T4.1: reseeding a project with no
+    // documented determinism contract would silently imply one exists) —
+    // the structured `DETERMINISM_NOT_DECLARED` marker the SDK maps to its
+    // own declared error code.
+    case 'set-seed': {
+      const runtime = getPlayRuntimeAccess();
+      if (!runtime) {
+        return { ok: false, error: 'not in play mode — start play before setting the seed' };
+      }
+      if (!runtime.determinismDeclared) {
+        return {
+          ok: false,
+          error:
+            "this project's manifest does not declare determinism.seededRandom — " +
+            'play.seed.set has no documented contract to reseed against (D15)',
+          data: { code: 'DETERMINISM_NOT_DECLARED' },
+        };
+      }
+      if (!runtime.random) {
+        return {
+          ok: false,
+          error: 'this play session has no first-party ctx.random to reseed',
+        };
+      }
+      runtime.random.reseed(cmd['seed'] as number);
+      // Read back the live, post-reseed value (mirrors set-time-scale's own
+      // read-after-apply convention immediately above).
+      return { ok: true, data: { seed: runtime.random.seed } };
+    }
+    // D15/T-D15.4 — the `play.runTicks` relay case (`docs/D15-DETERMINISM-
+    // DESIGN.md` §2.b): reaches the live session's `GameInternal.runTicks`
+    // through `getPlayRuntimeAccess()`'s `runTicks` accessor (itself backed
+    // by the SAME `DebugRegistry.getRunTicksTarget()` the bridge's
+    // `window.__vgai.runTicks` calls — one implementation, byte-identical
+    // behavior across doors, D17). `runTicks` itself throws a structured
+    // `DebugError` (`RUN_TICKS_PAUSED`) while paused — never a silent no-op —
+    // which `structuredErrorResult` below carries through as `data.code`.
+    case 'run-ticks': {
+      const runtime = getPlayRuntimeAccess();
+      if (!runtime) {
+        return { ok: false, error: 'not in play mode — start play before running ticks' };
+      }
+      if (!runtime.runTicks) {
+        return {
+          ok: false,
+          error: 'this play session has no first-party Game to run ticks on',
+          data: { code: 'RUN_TICKS_UNAVAILABLE' },
+        };
+      }
+      try {
+        const n = cmd['n'] as number;
+        const render = cmd['render'] as 'last' | 'all' | 'none' | undefined;
+        runtime.runTicks(n, render ? { render } : undefined);
+        return { ok: true };
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+    }
+
+    // #140 — the session-generic debug-seam relay: see `dispatchBridgeMethod`'s
+    // doc comment above for why this is a distinct primitive from the six
+    // named debug-seam cases above it (list-gameplay-state etc.) rather than
+    // a duplicate of them.
+    case 'bridge-call':
+      return handleBridgeCall(cmd);
+    case 'bridge-screenshot':
+      return handleBridgeScreenshot(cmd);
+
+    // Wave-2 "the playwright shim in the editor page + script-mode wire op"
+    // (`docs/SHARED-SESSION-SPEC.md` §7) — a STANDALONE relay command (like
+    // `bridge-screenshot` above), deliberately NOT a `bridge-call` method: it
+    // is editor-page UI automation (the in-page Playwright shim), not the
+    // game-debug seam the bridge↔wire parity gate governs. See
+    // `handlePageScript`'s own doc comment.
+    case 'page-script':
+      return handlePageScript(cmd);
+
+    // Version-skew honesty (B3-followup false-ack fix + Wave 5's AC-A0.3):
+    // every unrecognized command type used to fall through to `return {ok:
+    // true}` below — a silent lie: the browser did NOTHING, but the SDK/CLI
+    // caller was told it succeeded. Reporting a structured failure must hold
+    // for ANY unrecognized `type`, not just the ones known about today. The
+    // `data.code` marker is what the SDK maps to its `*_UNSUPPORTED` codes;
+    // the prose is for humans only.
     default:
-      // Every unrecognized command type used to fall through to `return { ok:
-      // true }` below — a silent, false ack: the browser did NOTHING, but the
-      // SDK/CLI caller was told it succeeded. Every "honest gap" op in
-      // packages/vgai-sdk/src/editor/*-operations.ts (camera.get,
-      // hierarchy.inspect pre-wiring, story.open) exists specifically to avoid
-      // ever sending a command that would land here. Reporting a structured
-      // failure — never a fabricated success — is the fix, and it must hold for
-      // ANY unrecognized `type`, not just the ones known about today.
-      return { ok: false, error: `Unknown editor command: ${String(cmd['type'])}` };
+      return {
+        ok: false,
+        error: `unknown command type "${cmd['type']}" — editor page predates this CLI`,
+        data: { code: 'UNKNOWN_COMMAND_TYPE' },
+      };
   }
 
   return { ok: true };
@@ -322,5 +1172,29 @@ export function connectCommandListener(store: EditorStore): () => void {
     window.location.reload();
   });
 
-  return () => source.close();
+  // #145 — presence freshness: the state snapshot the server holds is only
+  // re-POSTed after commands, so visibility/focus changes between commands
+  // would go stale. Report on the three events that change presence.
+  const reportPresence = () => reportEditorState(collectState(store));
+  document.addEventListener('visibilitychange', reportPresence);
+  window.addEventListener('focus', reportPresence);
+  window.addEventListener('blur', reportPresence);
+
+  // pageErrors freshness (target-blaster friction #3): a runtime error
+  // between commands must reach the server snapshot too, or `vgai status`
+  // reads stale-clean. Deferred a tick so ViewportPanel's own
+  // error-capture listener (which feeds editorConsole — the list
+  // collectPageErrors reads) runs FIRST regardless of registration order.
+  const reportAfterError = () => setTimeout(reportPresence, 0);
+  window.addEventListener('error', reportAfterError);
+  window.addEventListener('unhandledrejection', reportAfterError);
+
+  return () => {
+    document.removeEventListener('visibilitychange', reportPresence);
+    window.removeEventListener('focus', reportPresence);
+    window.removeEventListener('blur', reportPresence);
+    window.removeEventListener('error', reportAfterError);
+    window.removeEventListener('unhandledrejection', reportAfterError);
+    source.close();
+  };
 }