@volter/play 0.5.211 → 0.5.213

package/src/play-log.ts

@@ -1,75 +1,58 @@
 /**
- * THE MODEL PLAY LOG — what a play script says happened, stamped with the run's own clock.
+ * THE PLAY LOG: what the game's run says happened.
  *
- * The game editor's play log is the receipt of a run (`play-*.jsonl`, `log-format.ts`); this
- * is Model Play's. A script calls `play.log(kind, facts)` (`play-script.ts`) on the
- * transitions that explain a run — a jump, a landing, a death and its cause, autoplay's
- * choice — and an agent reads them back with `cyclotron play-log` or
- * `editor.modelPlayLog()` in `eval`. `console.log` cannot do this job: the session's
- * console feed keeps warnings and errors only.
+ * Each player's page traces its run (std's trace, as the dev server's receiver writes it, `build/runs/<run>/<page>.jsonl`)
+ * and the run reads each trace into this log, each entry tagged with its player's slot (`std-game.ts`, `source:
+ * 'script'`). Play adds its own lifecycle entries (`source: 'play'`): `play-start`, `running`, `player-joined`,
+ * `player-page-loaded`, `player-left`, `view`, `autoplay-on` and `autoplay-off` (each with `by`), `pause`, `resume`,
+ * `step` and `speed` (each with the clock std answered), `capture` (its file), `script-error` (with its `phase`) and
+ * `play-stop`. An agent reads them back with `cyclotron play-log` or `editor.contributedVerb('play-log')` in
+ * `eval`: the session's console feed keeps warnings and errors only.
  *
- * Every entry carries `simT` (the seconds of simulation since Play started: the sum of the
- * `dt`s the runner has handed to `update`) and `tick` (the number of the update in
- * progress; 0 while the script's default export runs), the same two stamps the game
- * editor's entries carry. They are the Game panel's clock too: the runner advances both at
- * the same call (`play-script.ts`), so they stand still while paused and run at the speed. The
- * runner adds its own lifecycle entries (`source: 'play'`): `play-start`, `play-restart` (a
- * Restart's fresh run, right after its `play-start`), `script-reload` with its reason,
- * `script-error`, `tint-unsupported`, `tint-unknown-object`, `pause`, `resume`, `step` (one per
- * stepped update, with its `dt`), `speed` (on a change, and at a start that is not 1×),
- * `autoplay-on` and `autoplay-off` (each with `by`: `panel`, `cli`, `takeover`, `script`),
- * `autoplay-unavailable` (a script ran its first update without offering a bot),
- * `play-stop`.
+ * WHEN EACH HAPPENED: a trace entry carries its page's own time, its trace's step (std's trace format 3: `s`, sixty a
+ * second of the page's game clock, its `performance.now` on a live page) as `tick` and that step in seconds as `simT`;
+ * Play's own entries carry the run's elapsed seconds since its `play-start` as `simT`, and the newest trace step heard
+ * as `tick`. So `--since` reads the run's seconds, a page's from its own start.
  *
- * ONE LOG PER MODEL DOCUMENT, each its document's latest run. Two documents playing at once
- * keep separate logs; a read names its document or takes the active Play's (the latest
- * started that still plays, else the latest started). Play starting from a fresh copy
- * replaces its document's log; a script reload does not, and the log outlives Stop so a
- * finished run can be read. The runner writes through the {@link ModelPlayRun} handle Play
- * started: once that run has ended its handle writes nothing, so a stale timer of an old
- * script cannot reach the next run's log.
+ * ONE LOG, the latest run's. Each Play replaces it, and it outlives Stop so a finished run can be read. The run writes
+ * through the {@link PlayLogRun} handle Play started: once that run has ended its handle writes nothing, so a stale
+ * timer of an old run cannot reach the next run's log.
  *
- * BOUNDED AND PAGE-LIFETIME. The newest {@link MODEL_PLAY_LOG_CAPACITY} entries of a run are
- * kept in a ring (older ones are counted in `dropped`); one entry's facts are kept as JSON of
- * at most {@link MODEL_PLAY_LOG_FACTS_CHARS} characters. It is never stored: a reload of the
- * page forgets it, as it forgets the game.
+ * BOUNDED AND PAGE-LIFETIME. The newest {@link PLAY_LOG_CAPACITY} entries of a run are kept in a ring (older
+ * ones are counted in `dropped`); one entry's facts are kept as JSON of at most {@link PLAY_LOG_FACTS_CHARS}
+ * characters. It is never stored: a reload of the page forgets it, as it forgets the run.
  *
- * THE GAME PANEL DRAWS IT LIVE: {@link subscribeModelPlayLog} hears every write, and
- * {@link tailModelPlayLog} reads the newest entries of one document without copying the ring.
- *
- * Logging is a read of the script's own values: it never throws into the script and touches
- * neither the clock nor the copy.
+ * THE GAME PANEL DRAWS IT LIVE: {@link subscribePlayLog} hears every write, and {@link tailPlayLog} reads the newest
+ * entries without copying the ring.
  */
 
-/** Entries a run's ring keeps; the oldest beyond this are dropped and counted. */
-export const MODEL_PLAY_LOG_CAPACITY = 5000;
-/** The longest JSON one entry's facts keep; longer facts are kept truncated, as a string. */
-export const MODEL_PLAY_LOG_FACTS_CHARS = 2048;
-
-export interface ModelPlayLogEntry {
-  /** The entry's place in this run, from 0: a gap in `seq` is entries the ring dropped. */
+/** One entry of the play log (`play-log`): read from a player's page's trace, or written by Play. */
+export interface PlayLogEntry {
+  /** The entry's place in its run, from 0: a gap in `seq` is entries the bounded log dropped. */
   readonly seq: number;
   /** Wall-clock ms. */
   readonly t: number;
-  /** Seconds of simulation since Play started, across script reloads. */
+  /** When it happened: a trace entry's page time (its step's seconds, and its step), Play's own the run's elapsed
+   *  seconds (and the newest step heard). */
   readonly simT: number;
-  /** The update in progress (the first is 1); 0 before the first. */
   readonly tick: number;
   readonly kind: string;
-  /** `script` for the play script's own entries; `play` for the runner's lifecycle ones. */
+  /** `script` for the game's own entries (its pages' traces); `play` for Play's lifecycle ones. */
   readonly source: 'script' | 'play';
   readonly facts?: Record<string, unknown>;
 }
 
-export interface ModelPlayLogReading {
+/** Entries a run's ring keeps; the oldest beyond this are dropped and counted. */
+const PLAY_LOG_CAPACITY = 5000;
+/** The longest JSON one entry's facts keep; longer facts are kept truncated, as a string. */
+const PLAY_LOG_FACTS_CHARS = 2048;
+
+export interface PlayLogReading {
   /** The run is still playing; false after Stop, or when nothing has played. */
   readonly playing: boolean;
-  /** The model document and play script of the run read; null when nothing has played. */
-  readonly documentId: string | null;
+  /** What the run ran (the game's dev server command); null when nothing has played. */
   readonly script: string | null;
   readonly startedAt: number | null;
-  /** Every model document with a log, so a read can name another. */
-  readonly documents: readonly string[];
   /** The run's clock now. */
   readonly simT: number;
   readonly tick: number;
@@ -78,46 +61,42 @@ export interface ModelPlayLogReading {
   readonly total: number;
   readonly dropped: number;
   /** The kept entries that match the read's filters, oldest first. */
-  readonly entries: readonly ModelPlayLogEntry[];
+  readonly entries: readonly PlayLogEntry[];
 }
 
-export interface ModelPlayLogQuery {
-  /** The model document whose log to read; the active Play's when omitted. */
-  readonly documentId?: string;
-  /** Only entries at or after this simulation time (seconds). */
+export interface PlayLogQuery {
+  /** Only entries at or after this game time (seconds). */
   readonly since?: number;
   /** Only entries of this kind. */
   readonly kind?: string;
 }
 
 interface Run {
-  readonly documentId: string;
   readonly script: string;
   readonly startedAt: number;
   playing: boolean;
   simT: number;
   tick: number;
-  readonly ring: ModelPlayLogEntry[];
+  readonly ring: PlayLogEntry[];
   total: number;
   /** Every kind this run has written, for the panel's filter. */
   readonly kinds: Set<string>;
 }
 
-/** The runner's door onto its own run's log: inert once the run has ended. */
-export interface ModelPlayRun {
-  /** The runner is about to call `update(deltaSeconds)`. */
-  advance(deltaSeconds: number): void;
-  append(source: ModelPlayLogEntry['source'], kind: string, facts?: unknown): void;
+/** The run's door onto its own log: inert once the run has ended. */
+export interface PlayLogRun {
+  /** An entry, stamped with `at` (a trace line's page time) or else the run's elapsed seconds. */
+  append(source: PlayLogEntry['source'], kind: string, facts?: unknown, at?: { readonly simT: number; readonly tick: number }): void;
   /** `play-stop`, then nothing more is written; the entries stay readable. */
   end(facts?: Record<string, unknown>): void;
 }
 
 // One registry per page, whichever copy of this module a contribution loaded it through: the
-// runner writes it from the service, the session verb reads it from the command module.
-const key = Symbol.for('volter.model-play-log');
-const page = globalThis as typeof globalThis & { [key]?: Map<string, Run> };
-const runs: Map<string, Run> = page[key] ??= new Map();
-const listenersKey = Symbol.for('volter.model-play-log.listeners');
+// run writes it, the session verb reads it from the command module.
+const key = Symbol.for('volter.play-log');
+const page = globalThis as typeof globalThis & { [key]?: { run: Run | null } };
+const held: { run: Run | null } = page[key] ??= { run: null };
+const listenersKey = Symbol.for('volter.play-log.listeners');
 const pageListeners = globalThis as typeof globalThis & { [listenersKey]?: Set<() => void> };
 const listeners: Set<() => void> = pageListeners[listenersKey] ??= new Set();
 
@@ -127,53 +106,78 @@ function publish(): void {
   }
 }
 
-/** Hear every write to any document's log (several may land in one frame; coalesce). */
-export function subscribeModelPlayLog(listener: () => void): () => void {
+/** Hear every write to the log (several may land in one frame; coalesce). */
+export function subscribePlayLog(listener: () => void): () => void {
   listeners.add(listener);
   return () => { listeners.delete(listener); };
 }
 
+/** The facts that say what happened, first in an entry's facts: an error's message (std's trace `label`), then its
+ *  source and where. */
+const MEANING_FIRST = ['label', 'message', 'why', 'text', 'source', 'file', 'line', 'column', 'slot'];
+/** The frames of a stack an entry keeps once its facts are too long. */
+const STACK_FRAMES = 4;
+
+/** Facts in the order that keeps their meaning: what happened first, everything else after. */
+function meaningFirst(facts: Record<string, unknown>): Record<string, unknown> {
+  const first = MEANING_FIRST.filter((key) => key in facts);
+  return Object.fromEntries([...first, ...Object.keys(facts).filter((key) => !first.includes(key))].map((key) => [key, facts[key]]));
+}
+
+/** Facts too long to keep whole, shortened where it costs no meaning: the trace's session goes, a URL keeps its path,
+ *  a stack its first frames, each frame's URL its path. */
+function shortened(facts: Record<string, unknown>): Record<string, unknown> {
+  const path = (text: string): string => text.replace(/\bhttps?:\/\/[^/\s)]+/g, '').replace(/\?[^\s):]*/g, '');
+  const kept: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(facts)) {
+    if (key === 'session') continue;
+    kept[key] = typeof value !== 'string' ? value
+      : key === 'stack' ? path(value.split('\n').slice(0, STACK_FRAMES + 1).join('\n'))
+      : key === 'label' || key === 'message' ? value
+      : path(value);
+  }
+  return kept;
+}
+
 function keptFacts(facts: unknown): Record<string, unknown> | undefined {
   if (facts === undefined || facts === null) return undefined;
   let json: string | undefined;
-  try { json = JSON.stringify(facts); }
+  const ordered = typeof facts === 'object' && !Array.isArray(facts) ? meaningFirst(facts as Record<string, unknown>) : facts;
+  try { json = JSON.stringify(ordered); }
   catch (error) { return { unserializable: error instanceof Error ? error.message : String(error) }; }
   if (json === undefined) return undefined;
-  if (json.length > MODEL_PLAY_LOG_FACTS_CHARS) return { truncated: json.slice(0, MODEL_PLAY_LOG_FACTS_CHARS) };
+  if (json.length > PLAY_LOG_FACTS_CHARS && ordered !== facts) json = JSON.stringify(shortened(ordered as Record<string, unknown>));
+  if (json.length > PLAY_LOG_FACTS_CHARS) return { truncated: json.slice(0, PLAY_LOG_FACTS_CHARS) };
   // A snapshot, so a script that goes on mutating what it logged does not rewrite history.
   const value: unknown = JSON.parse(json);
   return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : { value };
 }
 
-function append(run: Run, source: ModelPlayLogEntry['source'], kind: string, facts?: unknown): void {
+function append(run: Run, source: PlayLogEntry['source'], kind: string, facts?: unknown, at?: { readonly simT: number; readonly tick: number }): void {
   try {
     const kept = keptFacts(facts);
-    const entry: ModelPlayLogEntry = {
-      seq: run.total, t: Date.now(), simT: run.simT, tick: run.tick, kind: String(kind), source,
+    const t = Date.now();
+    const simT = at?.simT ?? (t - run.startedAt) / 1000;
+    if (at !== undefined) run.tick = Math.max(run.tick, at.tick);
+    run.simT = Math.max(run.simT, (t - run.startedAt) / 1000);
+    const entry: PlayLogEntry = {
+      seq: run.total, t, simT, tick: at?.tick ?? run.tick, kind: String(kind), source,
       ...(kept ? { facts: kept } : {}),
     };
-    run.ring[run.total % MODEL_PLAY_LOG_CAPACITY] = entry;
+    run.ring[run.total % PLAY_LOG_CAPACITY] = entry;
     run.total += 1;
     run.kinds.add(entry.kind);
-  } catch { /* A log that cannot be written is not the script's failure. */ }
+  } catch { /* A log that cannot be written is not the run's failure. */ }
   publish();
 }
 
-/** Play started from a fresh copy: the document's log replaced by an empty one at zero,
- *  opened by `play-start`. */
-export function beginModelPlayLog(documentId: string, script: string): ModelPlayRun {
-  const run: Run = { documentId, script, startedAt: Date.now(), playing: true, simT: 0, tick: 0, ring: [], total: 0, kinds: new Set() };
-  // Re-inserted, so the map's order is the order Plays started.
-  runs.delete(documentId);
-  runs.set(documentId, run);
-  append(run, 'play', 'play-start', { documentId, script });
+/** A run started: the log replaced by an empty one at zero, opened by `play-start`. */
+export function beginPlayLog(script: string): PlayLogRun {
+  const run: Run = { script, startedAt: Date.now(), playing: true, simT: 0, tick: 0, ring: [], total: 0, kinds: new Set() };
+  held.run = run;
+  append(run, 'play', 'play-start', { script });
   return {
-    advance(deltaSeconds) {
-      if (!run.playing) return;
-      run.tick += 1;
-      run.simT += deltaSeconds;
-    },
-    append(source, kind, facts) { if (run.playing) append(run, source, kind, facts); },
+    append(source, kind, facts, at) { if (run.playing) append(run, source, kind, facts, at); },
     end(facts) {
       if (!run.playing) return;
       append(run, 'play', 'play-stop', facts);
@@ -182,51 +186,46 @@ export function beginModelPlayLog(documentId: string, script: string): ModelPlay
   };
 }
 
-function activeRun(): Run | undefined {
-  const started = [...runs.values()].reverse();
-  return started.find((run) => run.playing) ?? started[0];
-}
-
-export function readModelPlayLog(query: ModelPlayLogQuery = {}): ModelPlayLogReading {
-  const run = query.documentId === undefined ? activeRun() : runs.get(query.documentId);
-  const documents = [...runs.keys()];
+export function readPlayLog(query: PlayLogQuery = {}): PlayLogReading {
+  const { run } = held;
   if (!run) {
     return {
-      playing: false, documentId: query.documentId ?? null, script: null, startedAt: null, documents,
-      simT: 0, tick: 0, capacity: MODEL_PLAY_LOG_CAPACITY, total: 0, dropped: 0, entries: [],
+      playing: false, script: null, startedAt: null,
+      simT: 0, tick: 0, capacity: PLAY_LOG_CAPACITY, total: 0, dropped: 0, entries: [],
     };
   }
-  const dropped = Math.max(0, run.total - MODEL_PLAY_LOG_CAPACITY);
-  const entries: ModelPlayLogEntry[] = [];
+  const dropped = Math.max(0, run.total - PLAY_LOG_CAPACITY);
+  const entries: PlayLogEntry[] = [];
   for (let seq = dropped; seq < run.total; seq++) {
-    const entry = run.ring[seq % MODEL_PLAY_LOG_CAPACITY]!;
+    const entry = run.ring[seq % PLAY_LOG_CAPACITY]!;
     if (query.since !== undefined && entry.simT < query.since) continue;
     if (query.kind !== undefined && entry.kind !== query.kind) continue;
     entries.push(entry);
   }
   return {
-    playing: run.playing, documentId: run.documentId, script: run.script, startedAt: run.startedAt, documents,
-    simT: run.simT, tick: run.tick, capacity: MODEL_PLAY_LOG_CAPACITY, total: run.total, dropped, entries,
+    playing: run.playing, script: run.script, startedAt: run.startedAt,
+    simT: run.playing ? Math.max(run.simT, (Date.now() - run.startedAt) / 1000) : run.simT, tick: run.tick,
+    capacity: PLAY_LOG_CAPACITY, total: run.total, dropped, entries,
   };
 }
 
-export interface ModelPlayLogTail {
-  /** Entries the document's latest run has written; 0 when it has no log. */
+export interface PlayLogTail {
+  /** Entries the latest run has written; 0 when nothing has played. */
   readonly total: number;
   /** Every kind that run has written, in the order first seen. */
   readonly kinds: readonly string[];
   /** The newest kept entries (of the asked kind), at most `last`, oldest first. */
-  readonly entries: readonly ModelPlayLogEntry[];
+  readonly entries: readonly PlayLogEntry[];
 }
 
-/** The newest `last` entries of one document's log, walked from the newest end. */
-export function tailModelPlayLog(documentId: string, last: number, kind?: string): ModelPlayLogTail {
-  const run = runs.get(documentId);
+/** The newest `last` entries of the log, walked from the newest end. */
+export function tailPlayLog(last: number, kind?: string): PlayLogTail {
+  const { run } = held;
   if (!run) return { total: 0, kinds: [], entries: [] };
-  const oldest = Math.max(0, run.total - MODEL_PLAY_LOG_CAPACITY);
-  const entries: ModelPlayLogEntry[] = [];
+  const oldest = Math.max(0, run.total - PLAY_LOG_CAPACITY);
+  const entries: PlayLogEntry[] = [];
   for (let seq = run.total - 1; seq >= oldest && entries.length < last; seq--) {
-    const entry = run.ring[seq % MODEL_PLAY_LOG_CAPACITY]!;
+    const entry = run.ring[seq % PLAY_LOG_CAPACITY]!;
     if (kind === undefined || entry.kind === kind) entries.push(entry);
   }
   return { total: run.total, kinds: [...run.kinds], entries: entries.reverse() };

package/src/std-controls.ts

@@ -0,0 +1,128 @@
+/**
+ * STD'S DEVICE CONTROLS, AS PLAY SPEAKS THEM. Every word Play says to a player's page goes through this module, so a
+ * change in std's shapes is a change here alone. Each is std's own control (`POST /__std/devices/<id>/control`,
+ * std-dev's std-endpoints.ts), reached through play's session route (`../serving/std-dev.ts`), which holds the dev
+ * server's token:
+ *
+ * - `clock`: `{ control: 'clock', action: 'pause' | 'resume' | 'step' | 'speed', frames?, speed? }`, answered with the
+ *   page's clock, `{ paused, speed, time, frame }` (`time` in seconds; speed one of 0.25, 0.5, 1, 2, 4; a step pauses
+ *   first, then runs `frames` frames of 1/60 s). It holds the page: a room the game hosts beside it runs on, since
+ *   Colyseus has no pause for a room.
+ * - `inspect`: `{ control: 'inspect' }`, answered with the scene the page last drew and its labelled screen nodes,
+ *   `{ objects, screen, truncated? }` (at most 2000 objects and 500 nodes, `truncated` saying how many were left out).
+ * - `act`: `{ control: 'act', actions, observe? }`, std-driver/3 `Action`s through the page's own input path, answered
+ *   with the observation (std-driver/3 `Observation`) where `observe` asks for one, else `{ ok: true }`. A refused
+ *   action fails the whole control, the actions before it already taken.
+ *
+ * `clock`, `inspect` and `act` need a device of exactly one page (a tab or a frame, as each of Play's players is).
+ * Each refusal is std's own answer (HTTP 400, `{ error }`), thrown with its words.
+ * - `autoplay` and `manual`: who drives the page, its bot (with its slot and goal) or the person.
+ * - `capture`: the page's next frame, written by std's receiver, answered with its file.
+ *
+ * The session's other routes for a std game (whether the project is one, its dev server, its devices, its pages and
+ * their traces, its bot's goals) are asked through {@link askPlay} too.
+ */
+
+const ROUTE = '/__editor/play/std';
+
+/** One of play's std routes, its JSON answer; a refusal thrown with what the route said. */
+export async function askPlay<T>(path: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(`${ROUTE}${path}`, init);
+  const body = (await response.json()) as T & { error?: string };
+  if (!response.ok) throw new Error(body.error ?? `${ROUTE}${path} answered ${response.status}`);
+  return body;
+}
+
+function control<T>(device: string, said: Record<string, unknown>): Promise<T> {
+  return askPlay<T>(`/devices/${encodeURIComponent(device)}/control`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(said),
+  });
+}
+
+/** A page's clock as std answers it: held or running, its speed, its game seconds and its frames. */
+export interface StdClock {
+  readonly paused: boolean;
+  readonly speed: number;
+  readonly time: number;
+  readonly frame: number;
+}
+
+/** What Play asks of a page's clock. */
+export type StdClockAction =
+  | { readonly action: 'pause' }
+  | { readonly action: 'resume' }
+  | { readonly action: 'step'; readonly frames: number }
+  | { readonly action: 'speed'; readonly speed: number };
+
+/** A page's clock held, released, stepped or set to a speed; its clock after. */
+export function stdClock(device: string, asked: StdClockAction): Promise<StdClock> {
+  return control<StdClock>(device, { control: 'clock', ...asked });
+}
+
+/** One object of the scene a page last drew, as std's inspect reads it. */
+interface StdInspectedObject {
+  readonly name: string;
+  /** three's own `type`. */
+  readonly type: string;
+  /** Its names from the scene down, joined by `/`. */
+  readonly path: string;
+  /** Its world position, `[x, y, z]`. */
+  readonly position: readonly number[];
+  readonly visible: boolean;
+  /** Its label: its `userData`'s `role`, `aria-label` and `aria-description`. */
+  readonly userData?: { readonly role?: string; readonly 'aria-label'?: string; readonly 'aria-description'?: string };
+}
+
+/** The scene a page last drew and its labelled screen nodes, as std bounds them. */
+export interface StdInspection {
+  readonly objects: readonly StdInspectedObject[];
+  readonly screen: readonly StdScreenNode[];
+  /** How many objects and nodes past std's bound were left out, where any were. */
+  readonly truncated?: { readonly objects: number; readonly screen: number };
+}
+
+/** One labelled node of a page's screen, as std's inspect names it (std-driver/3's `NodeObserved`). */
+interface StdScreenNode {
+  readonly role?: string;
+  readonly name?: string;
+  readonly [key: string]: unknown;
+}
+
+export function stdInspect(device: string): Promise<StdInspection> {
+  return control<StdInspection>(device, { control: 'inspect' });
+}
+
+/** One std-driver/3 action: a key pressed or let go, or the pointer at a point of the page (0 to 1, x right, y down)
+ *  with `button` pressed or let go. */
+export type StdAction =
+  | { readonly key: { readonly key: string; readonly down: boolean } }
+  | { readonly pointer: { readonly x: number; readonly y: number; readonly button?: number; readonly down?: boolean } };
+
+/** Actions taken through the page's own input path, as a player's own; the observation after them (std-driver/3's
+ *  `Observation`) where asked, else `{ ok: true }`. */
+export function stdAct(device: string, actions: readonly StdAction[], observe = false): Promise<unknown> {
+  return control(device, { control: 'act', actions, ...(observe ? { observe: true } : {}) });
+}
+
+/** Who drives a page: its bot, playing `goal` as the player `slot`, or the person. */
+export function stdDrive(device: string, driver: { readonly slot: string; readonly goal: string } | null): Promise<unknown> {
+  return control(device, driver === null ? { control: 'manual' } : { control: 'autoplay', slot: driver.slot, goal: driver.goal });
+}
+
+/** A frame std's receiver wrote (`stdCapture`'s file), as the PNG itself. */
+export async function stdCaptured(file: string): Promise<Blob> {
+  const name = file.split(/[\\/]/).at(-1) ?? file;
+  const response = await fetch(`${ROUTE}/capture?file=${encodeURIComponent(name)}`);
+  if (!response.ok) throw new Error(((await response.json()) as { error?: string }).error ?? `${ROUTE}/capture answered ${response.status}`);
+  return response.blob();
+}
+
+/** The page's next frame, captured by std's receiver; its file. */
+export async function stdCapture(device: string): Promise<string> {
+  const { files } = await control<{ files: string[] }>(device, { control: 'capture', id: crypto.randomUUID() });
+  const file = files[0];
+  if (file === undefined) throw new Error(`std's receiver wrote no capture for ${device}.`);
+  return file;
+}

package/src/std-export.ts

@@ -0,0 +1,120 @@
+/**
+ * A STD GAME EXPORTED, AS PLAY ASKS IT (`POST /__editor/play/std/export`, `../serving/std-dev.ts`): to the web (`std
+ * build`) or to an engine, made one of the game's targets first where the asker says to add it (`std target add`), as
+ * an engine's editor builds for a platform once it is added. One export at a time, the session's per project. Its
+ * state (the target, whether it runs, the last line std printed, how it ended, whether the target was added, where the
+ * export is) is the open project's, a store the Game panel draws and the `export` verb answers with; each line std
+ * prints goes to the editor's console. Another project opened, the state is that project's: none yet.
+ */
+import { onProjectChange } from '@volter/sdk/active-project';
+import { editorHost } from '@volter/sdk/host';
+import { askPlay } from './std-controls';
+
+/** Where a std game exports: the web, or an engine std ships to. */
+export const EXPORT_TARGETS = ['web', 'roblox', 'unreal'] as const;
+export type ExportTarget = (typeof EXPORT_TARGETS)[number];
+export const isExportTarget = (value: unknown): value is ExportTarget =>
+  typeof value === 'string' && (EXPORT_TARGETS as readonly string[]).includes(value);
+
+/** Each target's name as a person reads it. */
+export const EXPORT_LABELS: Readonly<Record<ExportTarget, string>> = { web: 'Web', roblox: 'Roblox', unreal: 'Unreal' };
+
+/** An export: running, or how it ended. */
+export interface StdExport {
+  readonly target: ExportTarget;
+  readonly running: boolean;
+  /** The last line std printed. */
+  readonly line: string | null;
+  /** Whether it ended exported; null while it runs. */
+  readonly ok: boolean | null;
+  /** Whether the engine became a target of the game for it. */
+  readonly added: boolean;
+  /** Where the export is, from the game's folder, once it ended. */
+  readonly out: string | null;
+}
+
+let current: StdExport | null = null;
+/** The export's start: only its own answers land, never an earlier start's still running. */
+let started = 0;
+const listeners = new Set<() => void>();
+
+onProjectChange(() => {
+  current = null;
+  started += 1;
+  for (const listener of listeners) listener();
+});
+
+function publish(next: StdExport): void {
+  current = next;
+  for (const listener of listeners) listener();
+}
+
+/** The latest export, running or ended; null before any. */
+export const stdExport = (): StdExport | null => current;
+
+/** Told each time the export changes. */
+export function onStdExport(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** The engines the game ships to besides the web (std's targets), as the session reads its packages. */
+export async function stdTargets(): Promise<readonly ExportTarget[]> {
+  return (await askPlay<{ targets?: readonly ExportTarget[] }>('')).targets ?? [];
+}
+
+/** The game exported to `target`, started, an engine added as the game's target first where `add` says (refused,
+ *  by the session, for an engine the game doesn't target otherwise); refused while another export runs. Its state as
+ *  it starts. */
+export function startStdExport(target: ExportTarget, add = false): StdExport {
+  if (current?.running === true) throw new Error(`An export to ${EXPORT_LABELS[current.target]} is running: wait for it to end.`);
+  started += 1;
+  const mine = started;
+  publish({ target, running: true, line: null, ok: null, added: false, out: null });
+  // (an answer for another project opened since, or an earlier start, is the console's alone)
+  const ours = (): boolean => started === mine && current !== null;
+  const said = (line: string): void => {
+    editorHost().console.log(line, 'export');
+    if (ours() && current !== null) publish({ ...current, line });
+  };
+  const ended = (ok: boolean, added: boolean, out: string | null): void => {
+    const label = EXPORT_LABELS[target];
+    if (ok) editorHost().console.log(`Exported to ${label}: ${out ?? ''}${added ? ` (${label} added as a target)` : ''}`, 'export');
+    else editorHost().console.error(`The export to ${label} failed: ${ours() ? current?.line ?? 'std said nothing' : 'its project was closed'}`, 'export');
+    if (ours() && current !== null) publish({ ...current, running: false, ok, added, out });
+  };
+  void (async () => {
+    const response = await fetch('/__editor/play/std/export', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ target, add }),
+    });
+    if (!response.ok || response.body === null) {
+      said(((await response.json().catch(() => ({}))) as { error?: string }).error ?? `The export answered ${response.status}.`);
+      ended(false, false, null);
+      return;
+    }
+    const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+    let rest = '';
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      rest += value;
+      for (let at = rest.indexOf('\n'); at >= 0; at = rest.indexOf('\n')) {
+        const message = JSON.parse(rest.slice(0, at)) as { line?: string; end?: { ok?: boolean; added?: boolean; out?: string } };
+        rest = rest.slice(at + 1);
+        if (message.end !== undefined) {
+          ended(message.end.ok === true, message.end.added === true, message.end.out ?? null);
+          return;
+        }
+        if (typeof message.line === 'string') said(message.line);
+      }
+    }
+    said('The export ended before it said how.');
+    ended(false, false, null);
+  })().catch((error: unknown) => {
+    said(error instanceof Error ? error.message : String(error));
+    ended(false, false, null);
+  });
+  return current ?? { target, running: true, line: null, ok: null, added: false, out: null };
+}

package/src/std-game-adapter.ts

@@ -0,0 +1,26 @@
+/**
+ * A STD GAME'S EDITOR, as Play supplies it (`package.json#contributes.volter.projectAdapters`, for a project with
+ * `std.json`). A std game carries no editor code: std's design has the editor add nothing to the game (design 8), so
+ * the adapter a Cyclotron project would keep in `editor/volter.adapter.ts` is Play's. It is the one a models project
+ * gets from `cyclotron create`, Blender's layout, keymap and properties inspector, with the game's Blender files as its
+ * documents: every `.blend` under `levels/` and every prefab's under `prefabs/` (std's `prefabs/<name>/<name>.blend`),
+ * and each level (`levels/<Name>Level.tsx`) a document of its own (`stdLevelDocuments`), the main level the one the
+ * project opens on.
+ */
+import { defineAdapter } from '@volter/project/adapter/adapter-module';
+import { ModelLayout } from '@volter/editor-blender/layouts';
+import { blenderKeymap } from '@volter/editor-blender/looks';
+// (the game's dev server serves this module, so the SDK's change channel it brings is that server's: it joins the
+// editor's page to the server's file events, which a std game's own modules never import, and a level's document and
+// Play's remount hear each save's export through it)
+import '@volter/sdk/project-module-changes';
+
+export default defineAdapter({
+  editor: { Layout: ModelLayout, keymap: blenderKeymap, inspector: 'properties' },
+  documents: {
+    find: [
+      { finder: 'modelsFromBlendFiles', include: ['levels/**/*.blend', 'prefabs/**/*.blend'] },
+      { finder: 'stdLevelDocuments', include: ['levels/**/*.tsx', 'levels/**/*.blend'] },
+    ],
+  },
+});