@vgai/sdk 0.4.0-canary.20260715.0

package/src/editor/transport.ts

@@ -0,0 +1,647 @@
+/**
+ * Transport seam for B3's `editor.*` operations
+ * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B3).
+ *
+ * Every `editor.*` op needs two things this module provides:
+ *
+ *  1. DETERMINISTIC SESSION SELECTION (`resolveEditorSession`) — when more
+ *     than one `vgai edit` dev server is running, which one does an op
+ *     without an explicit target mean? The rule (documented on
+ *     `resolveEditorSession` below) mirrors the CLI's own existing
+ *     precedent (`packages/vgai-cli/src/index.ts`'s `getClient()`: explicit
+ *     override > cwd/project match > default) and adds an explicit,
+ *     documented tie-break for the *multi-session, no-match* case: lowest
+ *     port wins.
+ *
+ *  2. A NAMED-TIMEOUT, NEVER-HANG TRANSPORT (`EditorTransport` +
+ *     `HttpEditorTransport`) — every network call this module makes is
+ *     wrapped in `withTimeout`, so a dead/unreachable/slow editor process
+ *     resolves to a structured failure within a bounded time instead of
+ *     hanging `dispatch()` forever (§8 B3 AC: "Operations fail with
+ *     EDITOR_NOT_RUNNING rather than hanging").
+ *
+ * `EditorTransport` is INJECTABLE via `ctx['editorTransport']` (a plain
+ * bag key on `OperationContext`'s open `[key: string]: unknown` — no change
+ * to `types.ts` needed) so tests can swap in a mock/fake transport and
+ * exercise every op headlessly, with no real browser or dev server
+ * (see `../../test/editor-operations.test.ts`).
+ *
+ * REAL TRANSPORT SURFACE — what `HttpEditorTransport` actually talks to,
+ * and the honest limits of today's wire protocol:
+ *
+ *  - Session discovery reads `~/.vgai/editor-sessions.json` (the file-format
+ *    CONTRACT documented at `packages/editor/server/session-registry.ts` —
+ *    "the CLI has no editor-package dependency ... the FILE FORMAT is the
+ *    contract"; this module is the vgai-sdk-side analogue of the CLI's own
+ *    light reader, `packages/vgai-cli/src/editor-sessions.ts`), then
+ *    PID-liveness-filters and probes each survivor with `GET
+ *    /__editor/project` (always answered by a running dev server, whether
+ *    or not a browser tab is attached — see `editor-server.ts`).
+ *  - Selection read: `GET /__editor/state` — real, works end to end
+ *    (`EditorState.selectedEntityId`/`selectedEntityIds`, always populated).
+ *  - Selection set / scene open / asset open / camera set (via
+ *    focus-entity/focus-selection/view-preset/set-camera): `POST
+ *    /__editor/command` — the existing SSE command relay (`editor-server.ts`);
+ *    these command `type`s are real, already-handled cases in the browser's
+ *    `command-listener.ts` `handleCommand` switch, so they are genuinely
+ *    wired end to end. Every command relayed through this path that the
+ *    switch does NOT recognize now fails loudly (`{ok:false}`) instead of
+ *    silently acking (B3-followup's false-ack fix — see command-listener.ts)
+ *    — this module never has to work around that fallthrough by avoiding a
+ *    command send the way `openStory` below still does.
+ *  - Hierarchy inspect / viewport camera read (B3-followup, now genuinely
+ *    wired): `collectState` (`packages/editor/src/command-listener.ts`) now
+ *    reports the real flattened entity tree (`entities`, reusing
+ *    `EditorStore.entities` — the same nested `SceneEntity[]` data model
+ *    `GameHierarchy` renders from) and the real live viewport camera pose
+ *    (`camera`, off `EditorStore.cameraPose` — the bound Three.js camera +
+ *    orbit target `ViewportPanel.tsx` binds via `bindScene`/`setOrbitTarget`)
+ *    alongside the pre-existing `entityCount`/`selectedEntityId` fields.
+ *    `HttpEditorTransport.getHierarchy`/`getCamera` read them off `GET
+ *    /__editor/state`. Both fields are absent only in the narrow window
+ *    before any browser tab has POSTed state at least once (a session IS
+ *    connected — a timing gap, not a fabricated tree/pose); the operations'
+ *    declared error codes (`HIERARCHY_UNAVAILABLE` / `CAMERA_STATE_UNAVAILABLE`)
+ *    cover exactly that window, distinct from `EDITOR_NOT_RUNNING`.
+ *  - Viewport camera SET now also supports an arbitrary pose (not just the
+ *    three original relay verbs): `{mode:'pose', position, target, fov?}`
+ *    sends `{type:'set-camera', ...}`, a real, handled case that calls
+ *    `EditorViewport.setPose` (moves camera position + orbit target, updates
+ *    fov/projection matrix when given).
+ *  - Source-location lookup: `GET /__ui-source/index` — the OID -> {file,
+ *    line, col, component, tag} map built by `vite-plugin-ui-oid.ts`'s
+ *    `OidStore` (`packages/editor/src/ui-source/oid-transform.ts`). This
+ *    endpoint is PURELY a GET of an in-memory index; it never calls any of
+ *    that plugin's write endpoints (`/__ui-source/write|css|text|prop|
+ *    struct|struct-many|restore`), so it structurally cannot rewrite JSX.
+ *  - Viewport screenshot (B3-followup, now genuinely wired for the common
+ *    case): `getScreenshot` first tries `POST /__editor/command`
+ *    `{type:'capture-viewport'}` — a real, handled case that renders the
+ *    LIVE viewport on demand (`EditorStore.captureViewportImage`, the same
+ *    offscreen-render-target technique the periodic autosave thumbnail
+ *    already used) and returns PNG bytes through the command-result payload
+ *    (`commandResponseFor`'s `data` passthrough, `server-utils.ts`). Falls
+ *    back to `GET /__editor/project-thumbnail?path=<project>` — the
+ *    LAST-SAVED thumbnail (written via `POST /__editor/save-thumbnail`,
+ *    which the editor UI also calls on its own cadence) — only when no
+ *    browser tab can answer the relay, or the viewport hasn't bound a
+ *    renderer/scene/camera yet. The result schema's `fresh` field names
+ *    which path answered.
+ *  - Console/log subscription metadata: describes the real, existing SSE
+ *    endpoint (`GET /__editor/events`) + log endpoints
+ *    (`POST /__editor/log-session`, `GET/POST /__editor/log-entries`) and
+ *    reports the CURRENTLY buffered play-mode log-entry count — metadata
+ *    about how to subscribe, not a live streaming call (a request/response
+ *    SDK op cannot itself be a stream).
+ *  - Story open remains an HONEST GAP: the editor has no Storybook/CSF
+ *    story-preview surface at all today — there is no browser-side command
+ *    handler to add one FOR (`command-listener.ts`'s `handleCommand` switch
+ *    has no such case, and there is no story runner anywhere in
+ *    `packages/editor/src` to wire one to). `HttpEditorTransport.openStory`
+ *    therefore never sends a command; it reports the gap as a declared
+ *    `STORY_OPEN_UNSUPPORTED` error instead of a fabricated success. (Had it
+ *    sent an unrecognized command anyway, the B3-followup false-ack fix means
+ *    it would now fail loudly rather than silently ack — but this path is
+ *    deliberately never exercised in the first place.)
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import type { ErrorDefinition } from '../registry.js';
+import type { OperationContext } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Named timeouts (§8 B3 AC: "enforce a named timeout, don't block forever")
+// ---------------------------------------------------------------------------
+
+/** Bound on discovering + probe-verifying live editor sessions. */
+export const EDITOR_SESSION_DISCOVERY_TIMEOUT_MS = 2000;
+/** Bound on a single per-session liveness probe (GET /__editor/project). */
+export const EDITOR_PROBE_TIMEOUT_MS = 1500;
+/** Bound on a read (GET /__editor/state, /__ui-source/index, thumbnail, log-entries). */
+export const EDITOR_READ_TIMEOUT_MS = 3000;
+/**
+ * Bound on a relayed command (POST /__editor/command). Mirrors the real
+ * relay's own `COMMAND_TIMEOUT_MS` (`packages/editor/server/editor-server.ts`)
+ * — an editor IS connected but did not answer in time.
+ */
+export const EDITOR_COMMAND_TIMEOUT_MS = 5000;
+
+/** Thrown by `withTimeout` when the wrapped promise doesn't settle in time. */
+export class EditorTimeoutError extends Error {
+  constructor(label: string, ms: number) {
+    super(`${label} timed out after ${ms}ms`);
+    this.name = 'EditorTimeoutError';
+  }
+}
+
+/**
+ * Race `promise` against a `ms`-bounded timer. Guarantees THIS function
+ * returns/rejects within `ms` regardless of what `promise` (real fetch, or a
+ * test's deliberately-never-resolving mock transport) actually does — the
+ * mechanism that makes "no hang" true for every `editor.*` op, not just the
+ * ones talking to a well-behaved transport.
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise<T>((resolvePromise, reject) => {
+    const timer = setTimeout(() => reject(new EditorTimeoutError(label, ms)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolvePromise(v);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      },
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Shared shapes
+// ---------------------------------------------------------------------------
+
+export interface EditorSessionInfo {
+  /** The port this session's dev server is bound to. */
+  port: number;
+  /** Canonical project root path currently open, or null when none. */
+  project: string | null;
+  /** Dev-server process id, when known from the local session registry (null for an unregistered/legacy server the caller only probed by port). */
+  pid: number | null;
+}
+
+export interface EditorCommandResult {
+  ok: boolean;
+  error?: string;
+  /** Optional payload for commands that answer with data (e.g. `capture-viewport`'s base64 PNG). */
+  data?: Record<string, unknown>;
+}
+
+export interface OidSourceEntry {
+  file: string;
+  line: number;
+  col: number;
+  component: string | null;
+  tag: string;
+}
+
+export interface HierarchyNodeInfo {
+  id: string;
+  name: string;
+  childIds: string[];
+}
+
+export interface HierarchySummary {
+  savePath: string | null;
+  entityCount: number;
+  /** Full node list, or null when the connected editor's wire protocol doesn't carry a tree (see module jsdoc). */
+  entities: HierarchyNodeInfo[] | null;
+}
+
+export interface CameraPose {
+  position: { x: number; y: number; z: number };
+  target: { x: number; y: number; z: number };
+  fov: number;
+}
+
+export type CameraSetRequest =
+  | { mode: 'focusEntity'; entityId: string }
+  | { mode: 'focusSelection' }
+  | { mode: 'viewPreset'; preset: 'top' | 'front' | 'right' | 'perspective' }
+  | {
+      mode: 'pose';
+      position: { x: number; y: number; z: number };
+      target: { x: number; y: number; z: number };
+      fov?: number | undefined;
+    };
+
+export interface ScreenshotResult {
+  base64: string;
+  mimeType: string;
+  /** True when this came from an on-demand `capture-viewport` render just now; false for the last-saved thumbnail fallback. */
+  fresh: boolean;
+}
+
+export interface ConsoleSubscriptionMetadata {
+  sseUrl: string;
+  events: string[];
+  logEntriesUrl: string;
+  logSessionUrl: string;
+  bufferedLogCount: number;
+}
+
+/**
+ * The transport seam every `editor.*` op's `impl` goes through. Real
+ * production dispatch uses `HttpEditorTransport` (the default, lazily
+ * constructed); tests inject a fake via `ctx['editorTransport']` — see
+ * `getTransport` below.
+ */
+export interface EditorTransport {
+  listSessions(timeoutMs: number): Promise<EditorSessionInfo[]>;
+  getSelection(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<{ selectedEntityId: string | null; selectedEntityIds: string[] } | undefined>;
+  getHierarchy(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<HierarchySummary | undefined>;
+  getCamera(session: EditorSessionInfo, timeoutMs: number): Promise<CameraPose | undefined>;
+  setCamera(
+    session: EditorSessionInfo,
+    request: CameraSetRequest,
+    timeoutMs: number,
+  ): Promise<EditorCommandResult>;
+  /** The whole live OID -> source-location index, or undefined if unreachable. */
+  getSourceIndex(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<Record<string, OidSourceEntry> | undefined>;
+  getScreenshot(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<ScreenshotResult | undefined>;
+  getConsoleSubscriptionMetadata(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<ConsoleSubscriptionMetadata | undefined>;
+  sendCommand(
+    session: EditorSessionInfo,
+    command: Record<string, unknown>,
+    timeoutMs: number,
+  ): Promise<EditorCommandResult>;
+  /** Undefined = the live editor has no wire support for opening a story today (see module jsdoc). */
+  openStory(
+    session: EditorSessionInfo,
+    path: string,
+    timeoutMs: number,
+  ): Promise<EditorCommandResult | undefined>;
+}
+
+// ---------------------------------------------------------------------------
+// Real transport
+// ---------------------------------------------------------------------------
+
+interface RegistrySessionEntry {
+  project: string | null;
+  port: number;
+  pid: number;
+  startedAt: string;
+}
+
+function isRegistrySessionEntry(v: unknown): v is RegistrySessionEntry {
+  if (typeof v !== 'object' || v === null) return false;
+  const s = v as Record<string, unknown>;
+  return (
+    (typeof s['project'] === 'string' || s['project'] === null) &&
+    typeof s['port'] === 'number' &&
+    typeof s['pid'] === 'number' &&
+    typeof s['startedAt'] === 'string'
+  );
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read `~/.vgai/editor-sessions.json` (the format contract owned by
+ * `packages/editor/server/session-registry.ts`), PID-liveness-filtered.
+ * Deliberate light duplicate of the read half — see module jsdoc.
+ */
+function readRegisteredSessions(): RegistrySessionEntry[] {
+  const registryFile = join(homedir(), '.vgai', 'editor-sessions.json');
+  if (!existsSync(registryFile)) return [];
+  try {
+    const raw: unknown = JSON.parse(readFileSync(registryFile, 'utf8'));
+    return Array.isArray(raw)
+      ? raw.filter(isRegistrySessionEntry).filter((s) => pidAlive(s.pid))
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+async function fetchJson(url: string, timeoutMs: number): Promise<unknown | undefined> {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return undefined;
+    return await res.json();
+  } catch {
+    return undefined;
+  }
+}
+
+async function postJson(
+  url: string,
+  body: unknown,
+  timeoutMs: number,
+): Promise<{ status: number; json: unknown } | undefined> {
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const json = await res.json().catch(() => undefined);
+    return { status: res.status, json };
+  } catch {
+    return undefined;
+  }
+}
+
+function baseUrl(session: EditorSessionInfo): string {
+  return `http://localhost:${session.port}`;
+}
+
+/** The real, production transport — HTTP against a live `vgai edit` dev server. */
+export class HttpEditorTransport implements EditorTransport {
+  async listSessions(timeoutMs: number): Promise<EditorSessionInfo[]> {
+    const registered = readRegisteredSessions();
+    const perProbeTimeout = Math.min(EDITOR_PROBE_TIMEOUT_MS, Math.max(200, timeoutMs));
+    const probes = await Promise.all(
+      registered.map(async (s) => {
+        const body = await fetchJson(
+          `${baseUrl({ port: s.port, project: null, pid: s.pid })}/__editor/project`,
+          perProbeTimeout,
+        );
+        if (body === undefined) return undefined;
+        const project = (body as { project?: { path?: string } | null }).project?.path ?? null;
+        const info: EditorSessionInfo = { port: s.port, project, pid: s.pid };
+        return info;
+      }),
+    );
+    return probes.filter((p): p is EditorSessionInfo => p !== undefined);
+  }
+
+  async getSelection(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<{ selectedEntityId: string | null; selectedEntityIds: string[] } | undefined> {
+    const body = (await fetchJson(`${baseUrl(session)}/__editor/state`, timeoutMs)) as
+      | { selectedEntityId?: string | null; selectedEntityIds?: string[] }
+      | undefined;
+    if (!body) return undefined;
+    return {
+      selectedEntityId: body.selectedEntityId ?? null,
+      selectedEntityIds: body.selectedEntityIds ?? [],
+    };
+  }
+
+  async getHierarchy(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<HierarchySummary | undefined> {
+    const body = (await fetchJson(`${baseUrl(session)}/__editor/state`, timeoutMs)) as
+      | { savePath?: string | null; entityCount?: number; entities?: HierarchyNodeInfo[] }
+      | undefined;
+    if (!body) return undefined;
+    // `collectState` (packages/editor/src/command-listener.ts) now reports the
+    // real flattened entity tree alongside entityCount — `entities` is real
+    // data whenever a browser tab has POSTed state at least once, `null` only
+    // if none ever has (e.g. a session probed before its first command/connect
+    // report, which the state route's initial `editorState = {}` also implies).
+    return {
+      savePath: body.savePath ?? null,
+      entityCount: body.entityCount ?? 0,
+      entities: body.entities ?? null,
+    };
+  }
+
+  async getCamera(session: EditorSessionInfo, timeoutMs: number): Promise<CameraPose | undefined> {
+    const body = (await fetchJson(`${baseUrl(session)}/__editor/state`, timeoutMs)) as
+      | { camera?: CameraPose }
+      | undefined;
+    // `collectState` now reports the live viewport camera pose (position,
+    // orbit target, fov) whenever `ViewportPanel.tsx` has bound one — `camera`
+    // is absent only pre-mount / in a headless store (see EditorStore.cameraPose).
+    return body?.camera;
+  }
+
+  async setCamera(
+    session: EditorSessionInfo,
+    request: CameraSetRequest,
+    timeoutMs: number,
+  ): Promise<EditorCommandResult> {
+    const command =
+      request.mode === 'focusEntity'
+        ? { type: 'focus-entity', id: request.entityId }
+        : request.mode === 'focusSelection'
+          ? { type: 'focus-selection' }
+          : request.mode === 'viewPreset'
+            ? { type: 'view-preset', preset: request.preset }
+            : {
+                type: 'set-camera',
+                position: request.position,
+                target: request.target,
+                ...(request.fov !== undefined ? { fov: request.fov } : {}),
+              };
+    return this.sendCommand(session, command, timeoutMs);
+  }
+
+  async getSourceIndex(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<Record<string, OidSourceEntry> | undefined> {
+    const body = await fetchJson(`${baseUrl(session)}/__ui-source/index`, timeoutMs);
+    if (!body || typeof body !== 'object') return undefined;
+    return body as Record<string, OidSourceEntry>;
+  }
+
+  async getScreenshot(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<ScreenshotResult | undefined> {
+    // Try a fresh, on-demand capture first (`capture-viewport` — a real,
+    // already-handled case in command-listener.ts's handleCommand switch as
+    // of B3-followup). Falls back to the last-saved thumbnail snapshot below
+    // when no browser tab is attached to answer the relay, or the viewport
+    // hasn't bound a renderer/scene/camera yet (e.g. right after page load).
+    const fresh = await this.sendCommand(session, { type: 'capture-viewport' }, timeoutMs).catch(
+      () => undefined,
+    );
+    if (fresh?.ok && fresh.data) {
+      const base64 = fresh.data['base64'];
+      const mimeType = fresh.data['mimeType'];
+      if (typeof base64 === 'string' && typeof mimeType === 'string') {
+        return { base64, mimeType, fresh: true };
+      }
+    }
+    return this.getSavedThumbnail(session, timeoutMs);
+  }
+
+  /** The LAST-SAVED thumbnail PNG (fallback path — see `getScreenshot`). */
+  private async getSavedThumbnail(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<ScreenshotResult | undefined> {
+    if (!session.project) return undefined;
+    try {
+      const res = await fetch(
+        `${baseUrl(session)}/__editor/project-thumbnail?path=${encodeURIComponent(session.project)}`,
+        { signal: AbortSignal.timeout(timeoutMs) },
+      );
+      if (!res.ok) return undefined;
+      const buf = new Uint8Array(await res.arrayBuffer());
+      let binary = '';
+      for (const byte of buf) binary += String.fromCharCode(byte);
+      return { base64: btoa(binary), mimeType: 'image/png', fresh: false };
+    } catch {
+      return undefined;
+    }
+  }
+
+  async getConsoleSubscriptionMetadata(
+    session: EditorSessionInfo,
+    timeoutMs: number,
+  ): Promise<ConsoleSubscriptionMetadata | undefined> {
+    const body = (await fetchJson(`${baseUrl(session)}/__editor/log-entries`, timeoutMs)) as
+      | { entries?: unknown[] }
+      | undefined;
+    if (!body) return undefined;
+    return {
+      sseUrl: `${baseUrl(session)}/__editor/events`,
+      events: ['editor-command', 'project-changed', 'asset-moved', 'scene-changed'],
+      logEntriesUrl: `${baseUrl(session)}/__editor/log-entries`,
+      logSessionUrl: `${baseUrl(session)}/__editor/log-session`,
+      bufferedLogCount: Array.isArray(body.entries) ? body.entries.length : 0,
+    };
+  }
+
+  async sendCommand(
+    session: EditorSessionInfo,
+    command: Record<string, unknown>,
+    timeoutMs: number,
+  ): Promise<EditorCommandResult> {
+    const result = await postJson(`${baseUrl(session)}/__editor/command`, command, timeoutMs);
+    if (!result) return { ok: false, error: 'Command relay unreachable.' };
+    const json = result.json as
+      | { ok?: boolean; error?: string; [key: string]: unknown }
+      | undefined;
+    if (json?.ok) {
+      // `commandResponseFor` (editor-server.ts) spreads a command's `data`
+      // payload alongside `ok: true` at the top level — collect everything
+      // that isn't `ok` itself back into `data` for callers like getScreenshot.
+      const { ok: _ok, ...data } = json;
+      return Object.keys(data).length > 0 ? { ok: true, data } : { ok: true };
+    }
+    return { ok: false, error: json?.error ?? `Command relay returned status ${result.status}.` };
+  }
+
+  async openStory(
+    _session: EditorSessionInfo,
+    _path: string,
+    _timeoutMs: number,
+  ): Promise<EditorCommandResult | undefined> {
+    // No browser-side command handler exists for this today (see module
+    // jsdoc) — undefined signals the gap; the op turns this into a declared
+    // STORY_OPEN_UNSUPPORTED error rather than sending a command the
+    // browser would silently no-op and falsely ack.
+    return undefined;
+  }
+}
+
+const defaultTransport = new HttpEditorTransport();
+
+/** Resolve the transport to use: `ctx['editorTransport']` when injected (tests), else the shared real transport. */
+export function getTransport(ctx: OperationContext): EditorTransport {
+  const injected = ctx['editorTransport'];
+  return (injected as EditorTransport | undefined) ?? defaultTransport;
+}
+
+// ---------------------------------------------------------------------------
+// EDITOR_NOT_RUNNING + deterministic session resolution
+// ---------------------------------------------------------------------------
+
+export const EDITOR_NOT_RUNNING_ERROR: ErrorDefinition = {
+  code: 'EDITOR_NOT_RUNNING',
+  summary:
+    'No live, responsive editor session is available to target (none running, none matching ' +
+    'the requested target, or discovery timed out).',
+  data: z.object({ editorUrl: z.string().optional() }),
+};
+
+function canonicalize(p: string): string {
+  return resolve(p);
+}
+
+/** Extract the port from an `http(s)://host:port` URL, or undefined if unparseable. */
+function portOf(url: string): number | undefined {
+  try {
+    const port = new URL(url).port;
+    return port ? Number(port) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Deterministic session selection (§8 B3 AC: "Session selection is
+ * deterministic when multiple editors are running"). Precedence, in order:
+ *
+ *  1. `ctx.editorUrl` given -> the live session on THAT exact port, or
+ *     EDITOR_NOT_RUNNING if no live session answers there. (Explicit
+ *     targeting always wins — mirrors `vgai-cli`'s own `--url` override.)
+ *  2. `ctx.projectRoot` given (no editorUrl) -> the live session whose
+ *     canonical project path matches `ctx.projectRoot`'s canonical path.
+ *     (Mirrors `packages/vgai-cli/src/index.ts`'s `getClient()` cwd rule —
+ *     "run `vgai play` from inside a project and it targets THAT project's
+ *     editor, whichever port it landed on".)
+ *  3. Neither given, or neither matched -> the LOWEST-numbered port among
+ *     all live sessions (a total order over the only session field that is
+ *     always present and stable, so the rule never depends on registration
+ *     order or wall-clock time).
+ *  4. Zero live sessions at all -> EDITOR_NOT_RUNNING.
+ *
+ * Bounded by `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS` via `withTimeout` — a
+ * transport whose `listSessions` never resolves (or takes too long) still
+ * surfaces EDITOR_NOT_RUNNING within that bound, never a hang.
+ */
+export async function resolveEditorSession(
+  ctx: OperationContext,
+  transport: EditorTransport,
+): Promise<EditorSessionInfo> {
+  const editorUrl = ctx.editorUrl;
+  const notRunning = (): never => {
+    throw new OperationError('EDITOR_NOT_RUNNING', 'No editor connected.', {
+      ...(editorUrl !== undefined ? { editorUrl } : {}),
+    });
+  };
+
+  let sessions: EditorSessionInfo[];
+  try {
+    sessions = await withTimeout(
+      transport.listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
+      EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
+      'editor session discovery',
+    );
+  } catch {
+    return notRunning();
+  }
+  if (sessions.length === 0) return notRunning();
+
+  if (editorUrl !== undefined) {
+    const port = portOf(editorUrl);
+    const match = sessions.find((s) => s.port === port);
+    if (!match) return notRunning();
+    return match;
+  }
+
+  if (ctx.projectRoot !== undefined) {
+    const canon = canonicalize(ctx.projectRoot);
+    const match = sessions.find((s) => s.project !== null && canonicalize(s.project) === canon);
+    if (match) return match;
+  }
+
+  return [...sessions].sort((a, b) => a.port - b.port)[0]!;
+}