@vgai/sdk 0.4.0-canary.20260715.0

package/src/play/transport.ts

@@ -0,0 +1,728 @@
+/**
+ * Transport seam for B4's `play.*` operations
+ * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B4).
+ *
+ * `play.*` targets or launches a playable runtime (§5.7). TODAY, the only
+ * playable runtime this repo can launch/target is the one already mounted
+ * inside a connected editor's browser tab — `enterPlayMode`/`exitPlayMode`/
+ * `pausePlayMode`/`resumePlayMode`/`stepPlayMode`
+ * (`packages/editor/src/play-mode.ts`) driven through the SAME
+ * `POST /__editor/command` SSE relay B3's `editor.*` ops use
+ * (`packages/editor/server/editor-server.ts`). There is no separate
+ * "runtime-page" launcher for play sessions yet (that concept exists only
+ * for the deterministic render-control harness, `render-control.ts`'s
+ * `?vgai-render=1` page and `cinematic.render`'s own launched browser — a
+ * completely different, request-scoped, non-interactive harness). Every
+ * `play.*` op below is declared `host: 'runtime-page'` per §8 B1's taxonomy
+ * (these ops target/launch a playable runtime, which is the host
+ * classification's whole point), while the REAL transport underneath rides
+ * the existing editor-browser relay — see each op file's jsdoc for exactly
+ * which relay call it reuses, and PLAY-GAPS.md-style notes below for what
+ * has no relay wiring today.
+ *
+ * SESSION RESOLUTION: `resolvePlaySession` mirrors
+ * `../editor/transport.ts`'s `resolveEditorSession` byte-for-byte in
+ * PRECEDENCE (explicit `ctx.editorUrl` > `ctx.projectRoot` match > lowest
+ * live port) — deliberately NOT imported and reused directly, because
+ * `resolveEditorSession`'s parameter type is the full `EditorTransport`
+ * interface (selection/hierarchy/camera/screenshot/etc.), and forcing every
+ * `play.*` test's mock transport to also stub all of THOSE unrelated methods
+ * just to get session resolution would be pure boilerplate. This is the
+ * same "deliberate light duplicate" tradeoff `../editor/transport.ts`'s own
+ * module jsdoc documents for its session-registry reader — a few lines
+ * duplicated beats a much larger, unrelated interface coupling.
+ *
+ * REAL TRANSPORT SURFACE — what `HttpPlayTransport` actually talks to.
+ * Wave 5 (docs/SYNTHETIC-PLAYER-SPEC.md §3.5) closed the version-skew lie:
+ * `command-listener.ts`'s `handleCommand` now has a `default:` case answering
+ * `{ok:false, data:{code:'UNKNOWN_COMMAND_TYPE'}}` for any command type the
+ * connected editor page predates, and the relay's result leg carries `data`
+ * end to end (`reportCommandResult` → `/__editor/command-result` →
+ * `commandResponseFor` → `relayCommand` below). Methods here translate that
+ * structured marker into `undefined` — the undefined-means-unsupported
+ * convention `editor/transport.ts`'s `openStory`/`getCamera` established —
+ * so each op throws its own declared `*_UNSUPPORTED` code against a stale
+ * editor, never trusting a fabricated ack.
+ *
+ *  - start/pause/resume/stop/frameStep: `POST /__editor/command` with
+ *    `{type:'play'|'stop'|'pause'|'resume'|'step'}` — ALL FIVE are real,
+ *    already-handled cases in `command-listener.ts`'s `handleCommand`
+ *    (`case 'play'` awaits the browser's `enterPlayMode()`, i.e. the whole
+ *    async game boot, before acking — see `PLAY_COMMAND_TIMEOUT_MS` below;
+ *    `stop`/`pause`/`resume`/`step` are synchronous and use the relay's
+ *    generic 5s command timeout).
+ *  - status: `GET /__editor/state`'s `playState`/`timeScale`/`seed`/
+ *    `deterministic` fields — ALL real since D15/T-D15.6 (`collectState`
+ *    reports the live session's `ctx.random.seed` and whether the manifest
+ *    declares `determinism.seededRandom`).
+ *  - gameplay-state listing/inspection, debug-command listing/invocation,
+ *    input injection (including D15/T-D15.5's tick-indexed `atTick` and
+ *    per-world `worldId`), time-scale control, and seed control (D15/
+ *    T-D15.6) are REAL: relay cases `list-gameplay-state`/
+ *    `inspect-gameplay-state`/`list-debug-commands`/`invoke-debug-command`/
+ *    `inject-input`/`set-time-scale`/`set-seed` in `command-listener.ts` read
+ *    the live session's game-scoped debug registry (`SystemAdapters.debug`),
+ *    its per-world `InputManager`(s)/`GameLoop`, or its `ctx.random`.
+ *  - active-world inspection remains a documented GAP: no command case, no
+ *    capability (see `status-operations.ts`).
+ *  - log discovery/read are file-native (`<projectRoot>/logs/play-*.jsonl`,
+ *    written by `play-mode.ts`'s log-session flow) — read directly off disk
+ *    by the `node`-hosted ops in `log-operations.ts`, no transport/relay
+ *    involved at all. log FOLLOW describes the real, existing poll surface
+ *    (`GET/POST /__editor/log-entries`, `POST /__editor/log-session`) for
+ *    the CURRENTLY active play session — metadata only, same shape as B3's
+ *    `editor.console.subscribe`.
+ */
+
+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
+// ---------------------------------------------------------------------------
+
+/** Bound on discovering + probe-verifying live editor sessions (mirrors `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`). */
+export const PLAY_SESSION_DISCOVERY_TIMEOUT_MS = 2000;
+/** Bound on a single per-session liveness probe. */
+export const PLAY_PROBE_TIMEOUT_MS = 1500;
+/** Bound on a plain read (status, log-entries count, ...). */
+export const PLAY_READ_TIMEOUT_MS = 3000;
+/** Bound on a relayed pause/resume/stop/frame-step command — mirrors the relay's generic `COMMAND_TIMEOUT_MS` (editor-server.ts). */
+export const PLAY_COMMAND_TIMEOUT_MS = 5000;
+/**
+ * Bound on `play.start`. Mirrors the real relay's own
+ * `PLAY_COMMAND_TIMEOUT_MS = 120_000` (`packages/editor/server/editor-server.ts:385`)
+ * plus a small buffer, so the CLIENT-side bound never fires before the
+ * SERVER's own 120s window would — a real "editor connected but the game's
+ * async setup() didn't finish" timeout is reported by the relay itself
+ * (surfaced as `result.ok === false`), while THIS constant only bounds a
+ * transport that never resolves/responds at all (see `PLAY_START_TIMEOUT`
+ * below). Overridable per-call via the op's `readyTimeoutMs` input.
+ */
+export const PLAY_START_TIMEOUT_MS = 125_000;
+
+/** Thrown by `withPlayTimeout` when the wrapped promise doesn't settle in time. */
+export class PlayTimeoutError extends Error {
+  constructor(label: string, ms: number) {
+    super(`${label} timed out after ${ms}ms`);
+    this.name = 'PlayTimeoutError';
+  }
+}
+
+/**
+ * Race `promise` against a `ms`-bounded timer — the mechanism that makes
+ * "start returns only after readiness OR a named timeout" true (§8 B4 AC)
+ * regardless of what the underlying transport does (real fetch, or a test's
+ * deliberately never-resolving mock).
+ */
+export function withPlayTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise<T>((resolvePromise, reject) => {
+    const timer = setTimeout(() => reject(new PlayTimeoutError(label, ms)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolvePromise(v);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      },
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Shared shapes
+// ---------------------------------------------------------------------------
+
+/** Same shape as `../editor/transport.ts`'s `EditorSessionInfo` — a play session IS an editor session today (see module jsdoc). */
+export interface PlaySessionInfo {
+  port: number;
+  project: string | null;
+  pid: number | null;
+}
+
+export interface PlayCommandResult {
+  ok: boolean;
+  error?: string;
+  /** The relay's read-payload leg (Wave 5): the browser handler's structured
+   *  result on success, or a structured `{ code, ... }` failure marker
+   *  (registered-name lists, zod issues) on `ok: false`. */
+  data?: unknown;
+}
+
+/** Extract a relayed failure's structured `{ code, ...data }` marker
+ *  (`command-listener.ts`'s `structuredErrorResult` shape), or null. Ops map
+ *  these to their declared error codes — never by parsing message prose. */
+export function relayErrorMarker(
+  result: PlayCommandResult,
+): { code: string; data: Record<string, unknown> } | null {
+  if (result.ok || typeof result.data !== 'object' || result.data === null) return null;
+  const { code, ...rest } = result.data as Record<string, unknown>;
+  if (typeof code !== 'string') return null;
+  return { code, data: rest };
+}
+
+/** Best-effort string[] out of relayed marker data (e.g. `registered` name
+ *  lists) — never throws on a malformed wire payload. */
+export function relayStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : [];
+}
+
+export type PlayState = 'stopped' | 'playing' | 'paused';
+
+export interface PlayStatus {
+  playState: PlayState;
+  /** The running session's current `ctx.random` root seed (D15/T-D15.6:
+   *  real since this track — reflects the manifest/query boot seed, or the
+   *  last successful `play.seed.set`), or `null` when no first-party `Game`
+   *  is running (nothing to report — never a fabricated value). */
+  seed: number | null;
+  /** True iff the running project's manifest declares
+   *  `determinism.seededRandom` (D15) — i.e. `play.seed.set`/the
+   *  `gameplay-rng-ban` scan/the dev-mode RNG trap all apply to it. `false`
+   *  for an undeclared project even though `ctx.random` still exists (it
+   *  just isn't a documented contract — see `docs/D15-DETERMINISM-DESIGN.md`
+   *  §2.a). */
+  deterministic: boolean;
+  /** Currently-applied simulation time-scale, when known — null when never successfully set (see `control-operations.ts`'s honest gap). */
+  timeScale: number | null;
+}
+
+export interface ActiveWorldInfo {
+  worldId: string;
+  worldKind: string;
+}
+
+/** One raw play-mode log entry exactly as persisted (`editor-api.ts`'s `LogEntry`) — see `log-operations.ts` for the identity fields this module ADDS on top when reading. */
+export interface RawPlayLogEntry {
+  t: number;
+  level: string;
+  source?: string;
+  sub?: string;
+  msg: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface PlayLogFollowMetadata {
+  logEntriesUrl: string;
+  logSessionUrl: string;
+  bufferedLogCount: number;
+}
+
+export type InputInjectionKind = 'axis' | 'vector2' | 'pointerDelta' | 'pointerPosition';
+
+/** Action-level injection (`kind: 'action'`, spec §3.2's `setVirtualAction` —
+ *  PRIMARY since Wave 5: the honest, focus-gated path whose relay result
+ *  carries `{delivered, reason?}`) plus the four legacy named-test-source
+ *  shapes (`InputManager.injectAxis` family, read back only through declared
+ *  `test_*` bindings). `atTick` (D15/T-D15.5, action-kind only) defers the
+ *  actuation to `InputManager.scheduleActionAtTick` instead of applying it
+ *  immediately — see `input-operations.ts`'s module jsdoc. `worldId` (D15
+ *  review objection 2's fix, all kinds) targets a SPECIFIC world's
+ *  `InputManager` — omitted, it resolves to the same default world every
+ *  door (this relay AND `window.__vgai.input.*`) now shares. */
+export type InputInjectionRequest =
+  | {
+      kind: 'action';
+      action: string;
+      value: boolean | number | { x: number; y: number };
+      atTick?: number;
+      worldId?: string;
+    }
+  | {
+      kind: InputInjectionKind;
+      sourceId: string;
+      value: number | { x: number; y: number };
+      worldId?: string;
+    };
+
+/**
+ * The transport seam every `play.*` op's `impl` goes through (except the
+ * file-native log discover/read ops, which never need a session at all).
+ * Real production dispatch uses `HttpPlayTransport`; tests inject a fake via
+ * `ctx['playTransport']`.
+ *
+ * Every method that has no real wire support returns `undefined` (never a
+ * fabricated success) — the honest-gap convention `../editor/transport.ts`
+ * established for `openStory`/`getCamera`/`getHierarchy`.
+ */
+export interface PlayTransport {
+  listSessions(timeoutMs: number): Promise<PlaySessionInfo[]>;
+  /** `seed` (D15/T-D15.6, optional) — relayed as `cmd['seed']` in the `'play'`
+   *  command body; `command-listener.ts`'s `'play'` case threads it into
+   *  `enterPlayMode`'s explicit-config seed leg. Omitted, boot seeding falls
+   *  back to the manifest/`?vgai-seed=` precedence unchanged. */
+  start(session: PlaySessionInfo, timeoutMs: number, seed?: number): Promise<PlayCommandResult>;
+  stop(session: PlaySessionInfo, timeoutMs: number): Promise<PlayCommandResult>;
+  pause(session: PlaySessionInfo, timeoutMs: number): Promise<PlayCommandResult>;
+  resume(session: PlaySessionInfo, timeoutMs: number): Promise<PlayCommandResult>;
+  frameStep(session: PlaySessionInfo, timeoutMs: number): Promise<PlayCommandResult>;
+  getStatus(session: PlaySessionInfo, timeoutMs: number): Promise<PlayStatus | undefined>;
+  /** Honest gap against the real transport — see `status-operations.ts`. */
+  getActiveWorld(session: PlaySessionInfo, timeoutMs: number): Promise<ActiveWorldInfo | undefined>;
+  getLogFollowMetadata(
+    session: PlaySessionInfo,
+    timeoutMs: number,
+  ): Promise<PlayLogFollowMetadata | undefined>;
+  /** Real since Wave 5 (relay case `inject-input`); `undefined` only against
+   *  a stale editor page (UNKNOWN_COMMAND_TYPE marker). On success `data`
+   *  carries `{delivered, reason?}` for action-level injections. */
+  injectInput(
+    session: PlaySessionInfo,
+    request: InputInjectionRequest,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined>;
+  /**
+   * D15/T-D15.6 (`docs/D15-DETERMINISM-DESIGN.md` §2.d): real since this
+   * track — relay case `set-seed` (`command-listener.ts`) reaching the live
+   * session's `ctx.random.reseed(seed)` through `play-mode.ts`'s
+   * `getPlayRuntimeAccess()`. FUTURE DRAWS ONLY (reseeding mid-run can never
+   * make an already-diverged session reproducible — for that, seed at
+   * session start instead). `undefined` only against a stale editor page
+   * (`UNKNOWN_COMMAND_TYPE` marker); a structured `DETERMINISM_NOT_DECLARED`
+   * failure (`data.code`) when the running project's manifest doesn't
+   * declare `determinism.seededRandom`.
+   */
+  setSeed(
+    session: PlaySessionInfo,
+    seed: number,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined>;
+  /** Real since Wave 5 (relay case `set-time-scale`, reaching
+   *  `GameLoop.timeScale`); `undefined` only against a stale editor page. */
+  setTimeScale(
+    session: PlaySessionInfo,
+    timeScale: number,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined>;
+  /** Real since Wave 5 (relay case `inspect-gameplay-state`): success `data`
+   *  is `{ state: Record<string, unknown> | null }` (null when the running
+   *  game exposes no debug adapter); `undefined` only against a stale editor
+   *  page. Structured failures (`STATE_PROVIDER_NOT_FOUND`) ride
+   *  `data.code`. */
+  getGameplayState(
+    session: PlaySessionInfo,
+    keys: string[] | undefined,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined>;
+  /** Real since Wave 5 (relay case `list-gameplay-state`): success `data` is
+   *  `{ providers: {name, tier}[] }`. `undefined` = stale editor page. */
+  listGameplayState(
+    session: PlaySessionInfo,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined>;
+  /** Real since Wave 5 (relay case `list-debug-commands`): success `data` is
+   *  `{ commands: DebugCommandInfo[] }` (name/description/argsJsonSchema/
+   *  locus). `undefined` = stale editor page. */
+  listDebugCommands(
+    session: PlaySessionInfo,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined>;
+  /** Real since Wave 5 (relay case `invoke-debug-command`): success `data` is
+   *  `{ result: unknown }`; structured failures (`DEBUG_COMMAND_NOT_REGISTERED`/
+   *  `DEBUG_COMMAND_ARGS_INVALID`/`DEBUG_COMMAND_FAILED`) ride `data.code`.
+   *  `undefined` = stale editor page. */
+  invokeDebugCommand(
+    session: PlaySessionInfo,
+    name: string,
+    args: unknown[],
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined>;
+  /**
+   * D15/T-D15.4 (`docs/D15-DETERMINISM-DESIGN.md` §2.b): real since this
+   * track — relay case `run-ticks` (`command-listener.ts`) reaching the live
+   * session's `GameInternal.runTicks` through `play-mode.ts`'s
+   * `getPlayRuntimeAccess()`. Success is a plain `{ok: true}` (no data leg);
+   * `undefined` only against a stale editor page (`UNKNOWN_COMMAND_TYPE`
+   * marker). Structured failures (`RUN_TICKS_PAUSED`, `RUN_TICKS_UNAVAILABLE`)
+   * ride `data.code`.
+   */
+  runTicks(
+    session: PlaySessionInfo,
+    n: number,
+    render: 'last' | 'all' | 'none' | undefined,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | 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;
+  }
+}
+
+/** Deliberate light duplicate of `../editor/transport.ts`'s identical reader — 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: PlaySessionInfo): string {
+  return `http://localhost:${session.port}`;
+}
+
+async function relayCommand(
+  session: PlaySessionInfo,
+  command: Record<string, unknown>,
+  timeoutMs: number,
+): Promise<PlayCommandResult> {
+  const result = await postJson(`${baseUrl(session)}/__editor/command`, command, timeoutMs);
+  if (!result) return { ok: false, error: 'Command relay unreachable.' };
+  const json = result.json as Record<string, unknown> | undefined;
+  // `commandResponseFor` (editor server-utils.ts) SPREADS the browser
+  // handler's `data` into the response body at the top level, beside
+  // `ok`/`error` — the same wire shape `HttpEditorTransport.sendCommand`
+  // reads. Collect everything else back into `data` here so ops see one
+  // uniform payload field.
+  if (json?.['ok']) {
+    const { ok: _ok, ...data } = json;
+    return Object.keys(data).length > 0 ? { ok: true, data } : { ok: true };
+  }
+  const { ok: _ok, error, ...data } = json ?? {};
+  return {
+    ok: false,
+    error: typeof error === 'string' ? error : `Command relay returned status ${result.status}.`,
+    ...(Object.keys(data).length > 0 ? { data } : {}),
+  };
+}
+
+/** Translate the browser's structured version-skew marker (`data.code ===
+ *  'UNKNOWN_COMMAND_TYPE'`, sent by `command-listener.ts`'s `default:` case)
+ *  into `undefined` — the undefined-means-unsupported convention — so ops
+ *  throw their declared `*_UNSUPPORTED` codes against a stale editor page. */
+function unlessUnknownCommandType(result: PlayCommandResult): PlayCommandResult | undefined {
+  return relayErrorMarker(result)?.code === 'UNKNOWN_COMMAND_TYPE' ? undefined : result;
+}
+
+/** The real, production transport — HTTP against a live `vgai edit` dev server. */
+export class HttpPlayTransport implements PlayTransport {
+  async listSessions(timeoutMs: number): Promise<PlaySessionInfo[]> {
+    const registered = readRegisteredSessions();
+    const perProbeTimeout = Math.min(PLAY_PROBE_TIMEOUT_MS, Math.max(200, timeoutMs));
+    const probes = await Promise.all(
+      registered.map(async (s) => {
+        const body = await fetchJson(
+          `http://localhost:${s.port}/__editor/project`,
+          perProbeTimeout,
+        );
+        if (body === undefined) return undefined;
+        const project = (body as { project?: { path?: string } | null }).project?.path ?? null;
+        const info: PlaySessionInfo = { port: s.port, project, pid: s.pid };
+        return info;
+      }),
+    );
+    return probes.filter((p): p is PlaySessionInfo => p !== undefined);
+  }
+
+  async start(
+    session: PlaySessionInfo,
+    timeoutMs: number,
+    seed?: number,
+  ): Promise<PlayCommandResult> {
+    return relayCommand(
+      session,
+      { type: 'play', ...(seed !== undefined ? { seed } : {}) },
+      timeoutMs,
+    );
+  }
+
+  async stop(session: PlaySessionInfo, timeoutMs: number): Promise<PlayCommandResult> {
+    return relayCommand(session, { type: 'stop' }, timeoutMs);
+  }
+
+  async pause(session: PlaySessionInfo, timeoutMs: number): Promise<PlayCommandResult> {
+    return relayCommand(session, { type: 'pause' }, timeoutMs);
+  }
+
+  async resume(session: PlaySessionInfo, timeoutMs: number): Promise<PlayCommandResult> {
+    return relayCommand(session, { type: 'resume' }, timeoutMs);
+  }
+
+  async frameStep(session: PlaySessionInfo, timeoutMs: number): Promise<PlayCommandResult> {
+    return relayCommand(session, { type: 'step' }, timeoutMs);
+  }
+
+  async getStatus(session: PlaySessionInfo, timeoutMs: number): Promise<PlayStatus | undefined> {
+    const body = (await fetchJson(`${baseUrl(session)}/__editor/state`, timeoutMs)) as
+      | {
+          playState?: PlayState;
+          timeScale?: number | null;
+          seed?: number | null;
+          deterministic?: boolean;
+        }
+      | undefined;
+    if (!body) return undefined;
+    // timeScale is real since Wave 5 (`collectState` reports the live loop's
+    // value; null while not playing or from an older editor page). seed/
+    // deterministic are real since D15/T-D15.6 (`collectState` reports the
+    // live session's `ctx.random.seed` + whether the manifest declares
+    // `determinism.seededRandom`); still null/false against an older editor
+    // page whose `collectState` predates these fields.
+    return {
+      playState: body.playState ?? 'stopped',
+      seed: typeof body.seed === 'number' ? body.seed : null,
+      deterministic: body.deterministic === true,
+      timeScale: typeof body.timeScale === 'number' ? body.timeScale : null,
+    };
+  }
+
+  async getActiveWorld(
+    _session: PlaySessionInfo,
+    _timeoutMs: number,
+  ): Promise<ActiveWorldInfo | undefined> {
+    // `collectState()` (command-listener.ts) carries no world field today —
+    // honest gap, never a fabricated world id (see status-operations.ts).
+    return undefined;
+  }
+
+  async getLogFollowMetadata(
+    session: PlaySessionInfo,
+    timeoutMs: number,
+  ): Promise<PlayLogFollowMetadata | undefined> {
+    const body = (await fetchJson(`${baseUrl(session)}/__editor/log-entries`, timeoutMs)) as
+      | { entries?: unknown[] }
+      | undefined;
+    if (!body) return undefined;
+    return {
+      logEntriesUrl: `${baseUrl(session)}/__editor/log-entries`,
+      logSessionUrl: `${baseUrl(session)}/__editor/log-session`,
+      bufferedLogCount: Array.isArray(body.entries) ? body.entries.length : 0,
+    };
+  }
+
+  async injectInput(
+    session: PlaySessionInfo,
+    request: InputInjectionRequest,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined> {
+    return unlessUnknownCommandType(
+      await relayCommand(session, { type: 'inject-input', ...request }, timeoutMs),
+    );
+  }
+
+  async setSeed(
+    session: PlaySessionInfo,
+    seed: number,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined> {
+    return unlessUnknownCommandType(
+      await relayCommand(session, { type: 'set-seed', seed }, timeoutMs),
+    );
+  }
+
+  async setTimeScale(
+    session: PlaySessionInfo,
+    timeScale: number,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined> {
+    return unlessUnknownCommandType(
+      await relayCommand(session, { type: 'set-time-scale', timeScale }, timeoutMs),
+    );
+  }
+
+  async getGameplayState(
+    session: PlaySessionInfo,
+    keys: string[] | undefined,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined> {
+    return unlessUnknownCommandType(
+      await relayCommand(
+        session,
+        { type: 'inspect-gameplay-state', ...(keys !== undefined ? { keys } : {}) },
+        timeoutMs,
+      ),
+    );
+  }
+
+  async listGameplayState(
+    session: PlaySessionInfo,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined> {
+    return unlessUnknownCommandType(
+      await relayCommand(session, { type: 'list-gameplay-state' }, timeoutMs),
+    );
+  }
+
+  async listDebugCommands(
+    session: PlaySessionInfo,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined> {
+    return unlessUnknownCommandType(
+      await relayCommand(session, { type: 'list-debug-commands' }, timeoutMs),
+    );
+  }
+
+  async invokeDebugCommand(
+    session: PlaySessionInfo,
+    name: string,
+    args: unknown[],
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined> {
+    return unlessUnknownCommandType(
+      await relayCommand(session, { type: 'invoke-debug-command', name, args }, timeoutMs),
+    );
+  }
+
+  async runTicks(
+    session: PlaySessionInfo,
+    n: number,
+    render: 'last' | 'all' | 'none' | undefined,
+    timeoutMs: number,
+  ): Promise<PlayCommandResult | undefined> {
+    return unlessUnknownCommandType(
+      await relayCommand(
+        session,
+        { type: 'run-ticks', n, ...(render !== undefined ? { render } : {}) },
+        timeoutMs,
+      ),
+    );
+  }
+}
+
+const defaultTransport = new HttpPlayTransport();
+
+/** Resolve the transport to use: `ctx['playTransport']` when injected (tests), else the shared real transport. */
+export function getPlayTransport(ctx: OperationContext): PlayTransport {
+  const injected = ctx['playTransport'];
+  return (injected as PlayTransport | undefined) ?? defaultTransport;
+}
+
+// ---------------------------------------------------------------------------
+// EDITOR_NOT_RUNNING (reused verbatim — play targets an editor session too)
+// + deterministic session resolution
+// ---------------------------------------------------------------------------
+
+export const PLAY_RUNTIME_NOT_AVAILABLE_ERROR: ErrorDefinition = {
+  code: 'EDITOR_NOT_RUNNING',
+  summary:
+    'No live, responsive editor session is available to host a play runtime (none running, ' +
+    'none matching the requested target, or discovery timed out). The SAME code B3 uses ' +
+    '(`editor.*`) — today, a play runtime only ever exists inside a connected editor session.',
+  data: z.object({ editorUrl: z.string().optional() }),
+};
+
+function canonicalize(p: string): string {
+  return resolve(p);
+}
+
+function portOf(url: string): number | undefined {
+  try {
+    const port = new URL(url).port;
+    return port ? Number(port) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Deterministic session selection for `play.*` ops — see module jsdoc for
+ * why this duplicates (rather than imports) `../editor/transport.ts`'s
+ * `resolveEditorSession`. Precedence is IDENTICAL: explicit `ctx.editorUrl`
+ * > `ctx.projectRoot` match > lowest live port > `EDITOR_NOT_RUNNING`.
+ */
+export async function resolvePlaySession(
+  ctx: OperationContext,
+  transport: Pick<PlayTransport, 'listSessions'>,
+): Promise<PlaySessionInfo> {
+  const editorUrl = ctx.editorUrl;
+  const notRunning = (): never => {
+    throw new OperationError('EDITOR_NOT_RUNNING', 'No editor connected to host a play runtime.', {
+      ...(editorUrl !== undefined ? { editorUrl } : {}),
+    });
+  };
+
+  let sessions: PlaySessionInfo[];
+  try {
+    sessions = await withPlayTimeout(
+      transport.listSessions(PLAY_SESSION_DISCOVERY_TIMEOUT_MS),
+      PLAY_SESSION_DISCOVERY_TIMEOUT_MS,
+      'play 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]!;
+}