@volter/play 0.5.211 → 0.5.212

package/src/std-game.ts

@@ -0,0 +1,841 @@
+/**
+ * A STD GAME, PLAYED IN THE MODEL DOCUMENT'S STAGE (volter-ai/std, design/circle-1.md, "Devices"): a project with
+ * `std.json` that depends on `@volter-ai/std-dev` plays its own dev page, each player a page of its own, since std's
+ * client is one a page. Play starts the game's dev server where none runs (`../serving/std-dev.ts`) and stands each
+ * player's page in the stage's container as an iframe: each is one device of the dev server (std's page says its kind,
+ * a person's `tab`), one player, a real client joining the game's room. Every word said to a page is std's own control
+ * (`std-controls.ts`).
+ *
+ * THE FRAMES. Each is `credentialless`: the workbench is cross-origin isolated (COEP `credentialless`) and the dev
+ * server sends no COEP, so a plain frame of it would be refused. Each loads the dev server at the workbench page's own
+ * hostname (`editor-<key>.localhost`), so it is the same site as the page and std's receiver takes its trace (its
+ * cookie is `SameSite=Strict`); Vite allows `*.localhost` by default. Every frame stays full size and drawn while
+ * another is viewed (only its opacity changes), so a browser does not throttle the frames out of view.
+ *
+ * WHICH PAGE IS WHICH PLAYER. Each frame's address names a slot of this run's own (`?slot=<run>-<n>`; std's bot reads
+ * the number at its end), which the page's trace says in its first line. A device is a player's when its page's trace
+ * names the player's slot (`/pages`), read again as the run goes, so a page that loads again (a new page, a new
+ * device) is found again, and a page of another editor's is never taken for one of these.
+ *
+ * THE VIEWS (the view bar, `std-view-bar.tsx`): Edit (the document's own area, live for editing, while the game runs
+ * on: `DocumentPlayStage.edit`), Player N, and Grid (Edit and every player tiled; a tile clicked opens it). Keys 1 to 4
+ * open Player N, Tab the next view and Escape Edit, while the editor holds the keyboard: a viewed player's page holds
+ * it, and its keys are the game's; a press on the view bar gives it back to the editor. A view changes at once.
+ *
+ * WHO DRIVES. The viewed player is the person's ("you"): its page is told `manual`, and a press in it is the person's
+ * own, which std's page hears itself. Every other player is the game's bot ("autopilot"): its page is told `autoplay`
+ * with its slot and the run's goal: one of the game's goals (its `autopilot/` program's, which the session lists at
+ * each run's start, `/goals`), the one its `play` script names where that is among them, else the first. Autoplay
+ * turns the viewed player's bot on with one of those goals and off; the person's own press in its page takes it back.
+ *
+ * THE CLOCK. Pause, step and speed are std's `clock` control, said to every joined player's page, and to each page as
+ * it joins; the viewed player's answer is the run's clock (`model-play.ts`). It holds the pages: a room the game hosts
+ * runs on, as Colyseus has no pause for a room.
+ *
+ * THE AGENT'S DOORS. Each player's frame registers its driver (`@volter/sdk/framed-document-driver`): while it is the
+ * view, `editor.document.key` presses keys in its page through std's `act`, and `editor.document.query` (its screen's
+ * labelled nodes) and `editor.inspect` (its scene's objects and its screen) read its page through std's `inspect`.
+ *
+ * WHAT IS SAID. Each page's trace is the play log, as the dev server's receiver writes it; Capture is the viewed page's
+ * next frame, written by std's receiver and named in the log. A player whose page never joins is taken out and the
+ * failure stands: a run none of whose players joined is not running.
+ */
+import { createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import type { DocumentPlayEditArea, DocumentPlayStage } from '@volter/editor-blender/api';
+import { getCurrentProject, onProjectChange } from '@volter/sdk/active-project';
+import { editorHost } from '@volter/sdk/host';
+import { registerFramedDriver } from '@volter/sdk/framed-document-driver';
+import { beginModelPlayLog, type ModelPlayRun } from './play-log';
+import { modelPlayClock, setModelPlayClock, setModelPlayFailure, setModelPlaySpeed, takeModelPlayArm } from './model-play';
+import { exportMenuOpen } from './std-export';
+import { askPlay, stdAct, stdCapture, stdCaptured, stdClock, stdDrive, stdInspect, type StdClock, type StdClockAction } from './std-controls';
+import { StdGridTiles, StdViewBar } from './std-view-bar';
+
+/** What a std game's Play runs: the game's own dev server (`../serving/std-dev.ts`), its page each player's. */
+export const STD_DEV = 'npm run dev';
+/** How long a page has to join once its frame is made: a first page waits on Vite's optimizer. */
+const JOIN_MS = 60_000;
+const LOOK_MS = 500;
+/** Steps a second of a std trace's clock (std's trace format 3, `s`). */
+const TRACE_STEPS_PER_SECOND = 60;
+/** The players a run starts with: the person's and one bot, the least a multiplayer game is tried with. */
+const FIRST_PLAYERS = 2;
+const MOST_PLAYERS = 8;
+
+export type StdView = 'edit' | 'grid' | number;
+
+export interface StdPlayer {
+  /** Its number in the run (Player 1, 2, …). */
+  readonly number: number;
+  /** Its slot, `?slot=` and the bot's: the run's own, ending in its number. */
+  readonly slot: string;
+  readonly frame: HTMLIFrameElement;
+  /** Its page (std's page id) and that page's device, once its page has joined. */
+  page: string | null;
+  device: string | null;
+  autopilot: boolean;
+  /** The goal its bot plays while it drives: one Autoplay named, or the run's. */
+  goal: string | null;
+  /** How far its page's trace has been read. */
+  traced: number;
+  /** Withdraws its frame's driver (`@volter/sdk/framed-document-driver`). */
+  readonly undrive: () => void;
+}
+
+export interface StdRun {
+  readonly documentId: string;
+  readonly players: readonly StdPlayer[];
+  readonly view: StdView;
+  /** The goal the game's bots play unless Autoplay names another (its `play` script's `--goal`, else its first goal);
+   *  null where it has none. */
+  readonly goal: string | null;
+  /** The game's goals, its `autopilot/` program's, as the session read them at the run's start. */
+  readonly goals: readonly string[];
+  /** The dev server's address, once it answers. */
+  readonly url: string | null;
+  /** The newest error a player's page threw (its trace's `error` line), with its player: the Game panel says it. */
+  readonly lastError: string | null;
+  /** std's headless play of a goal (`playGoalHeadless`): its goal and where it stands, `playing` until std says how it
+   *  ended (`achieved`, or `failed` with why); null before any. */
+  readonly headless: { readonly goal: string; readonly state: 'playing' | 'achieved' | 'failed'; readonly why: string | null } | null;
+}
+
+/** The game's goals as the last run read them, which Autoplay offers while stopped (an arm names one). */
+let knownGoals: readonly string[] = [];
+/** Whether the open project is a std game, as the session answered (undefined while first asked), and when. */
+let game: { readonly root: string; readonly answer: boolean | undefined; readonly goal: string | null; readonly at: number } | null = null;
+/** How long a "not a std game" stands before it is asked again: `cyclotron add-play` makes a project one while its
+ *  editor is open, which needs no reload. */
+const NOT_STD_MS = 2000;
+const listeners = new Set<() => void>();
+const publish = (): void => { for (const listener of [...listeners]) listener(); };
+export function subscribeStdGame(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+onProjectChange(() => { game = null; knownGoals = []; publish(); });
+
+/** Whether the open project is a std game; undefined while the session is first asked (each answer is published). A
+ *  "no" is asked again once it is {@link NOT_STD_MS} old, and stands meanwhile. */
+export function isStdGame(): boolean | undefined {
+  const root = getCurrentProject()?.rootPath;
+  if (root === undefined) return false;
+  if (game?.root === root && (game.answer !== false || Date.now() - game.at < NOT_STD_MS)) return game.answer;
+  void askStdGame(root);
+  return game?.root === root ? game.answer : undefined;
+}
+
+/** The session asked whether the project in `root` is a std game, the answer kept and published when it changed. */
+function askStdGame(root: string): Promise<boolean> {
+  const before = game?.root === root ? game : null;
+  game = { root, answer: before?.answer, goal: before?.goal ?? null, at: Date.now() };
+  return askPlay<{ game: boolean; goal: string | null }>('').then((said) => said, () => ({ game: false, goal: null })).then((said) => {
+    if (game?.root !== root) return said.game;
+    game = { root, answer: said.game, goal: said.goal, at: Date.now() };
+    if (before?.answer !== said.game || before.goal !== said.goal) publish();
+    return said.game;
+  });
+}
+
+/** Whether the open project is a std game, asked of the session now: Play's start asks so. */
+export function stdGameNow(): Promise<boolean> {
+  const root = getCurrentProject()?.rootPath;
+  return root === undefined ? Promise.resolve(false) : askStdGame(root);
+}
+
+/** A run as this module keeps it. */
+type LiveRun = StdRun & { players: StdPlayer[]; view: StdView; url: string | null; goal: string | null; goals: readonly string[];
+  lastError: string | null; readonly errorsSaid: Set<string>; headless: StdRun['headless'];
+  /** How far each headless bot page's trace has been read, by its page (std's play's slots, `server-<n>`, `p2p-<n>`). */
+  readonly headlessTraced: Map<string, { readonly slot: string; traced: number }>;
+  /** How far the dev server's error output has been read (`/errors`): its server's process and the next line, from
+   *  the run's mark on (where the output stood as the run began); null before the mark. */
+  serverErrors: { server: number | null; next: number } | null;
+  readonly tag: string; readonly host: HTMLElement; readonly stage: DocumentPlayStage; readonly log: ModelPlayRun; adding: Promise<void>;
+  failure: string | null; stopped: boolean };
+let run: LiveRun | null = null;
+/** The players each document is asked to play with (Players [-][+]), kept across its Plays and Restarts whatever
+ *  joined. */
+const playerCounts = new Map<string, number>();
+const runListeners = new Set<() => void>();
+let runVersion = 0;
+const publishRun = (): void => { runVersion += 1; for (const listener of [...runListeners]) listener(); };
+export function subscribeStdRun(listener: () => void): () => void {
+  runListeners.add(listener);
+  return () => { runListeners.delete(listener); };
+}
+export const stdRunVersion = (): number => runVersion;
+/** The std game's run of a document, or null while none runs. */
+export function stdRun(documentId?: string): StdRun | null {
+  return run && !run.stopped && (documentId === undefined || run.documentId === documentId) ? run : null;
+}
+
+/** The goal a player's bot plays: the one Autoplay named for it, or the run's. */
+const goalOf = (current: LiveRun, player: StdPlayer): string | null => player.goal ?? current.goal;
+
+/** Says to a player's page who drives it: its bot (`autoplay`, its slot and its goal) or the person (`manual`). */
+function tellDriver(current: LiveRun, player: StdPlayer): void {
+  const goal = goalOf(current, player);
+  if (player.device === null || (player.autopilot && goal === null)) return;
+  void stdDrive(player.device, player.autopilot && goal !== null ? { slot: player.slot, goal } : null)
+    .catch((error: unknown) => current.log.append('play', 'script-error', { phase: 'autoplay', slot: player.slot, message: String(error) }));
+}
+
+/** The bot on or off for one player, said to its page once it has joined, the change in the log. A goal named switches
+ *  a driving bot to it. */
+function drive(player: StdPlayer, autopilot: boolean, by: 'view' | 'panel' | 'cli' | 'takeover', goal?: string): void {
+  const current = run;
+  if (!current) return;
+  const changed = goal !== undefined && goal !== player.goal;
+  if (goal !== undefined) player.goal = goal;
+  if ((autopilot && goalOf(current, player) === null) || (player.autopilot === autopilot && !(autopilot && changed))) return;
+  player.autopilot = autopilot;
+  current.log.append('play', autopilot ? 'autoplay-on' : 'autoplay-off', { slot: player.slot, by, ...(autopilot ? { goal: goalOf(current, player) } : {}) });
+  tellDriver(current, player);
+  publishRun();
+}
+
+/** Who drives each player for the view: the viewed one the person, every other the bot. */
+function driveForView(): void {
+  if (!run) return;
+  run.players.forEach((player, index) => drive(player, index !== run!.view, 'view'));
+}
+
+/**
+ * The grid's tile `tile` of `count` (Edit first, then each player), in fractions of the stage. A tile is its view
+ * whole, at the stage's own proportions scaled down alike (by `width`, which `height` equals), as Unity's Multiplayer
+ * Play Mode shows each player's whole window: centred in its cell, with a short last row centred, so no cell stands
+ * empty.
+ */
+export function stdTile(tile: number, count: number): Exclude<DocumentPlayEditArea, 'live' | 'hidden'> {
+  const columns = Math.ceil(Math.sqrt(count)), rows = Math.ceil(count / columns);
+  const scale = 1 / columns;
+  const row = Math.floor(tile / columns);
+  const inRow = row === rows - 1 ? count - row * columns : columns;
+  const left = (tile % columns + (columns - inRow) / 2) / columns;
+  return { left, top: row / rows + (1 / rows - scale) / 2, width: scale, height: scale };
+}
+
+/** Each frame placed for the view (full size, or tiled), and the document's own area: live, its tile, or hidden. */
+function place(): void {
+  if (!run) return;
+  const { players, view } = run;
+  players.forEach((player, index) => {
+    const box = view === 'grid' ? stdTile(index + 1, players.length + 1) : { left: 0, top: 0, width: 1, height: 1 };
+    Object.assign(player.frame.style, {
+      // (the page lays out at the stage's size in every view, and a tile draws it smaller: its HUD keeps its size
+      // against the game, as in the player's own view)
+      left: `${box.left * 100}%`, top: `${box.top * 100}%`, width: '100%', height: '100%',
+      transform: box.width === 1 ? '' : `scale(${box.width})`, transformOrigin: '0 0',
+      opacity: view === 'grid' || view === index ? '1' : '0',
+      // (a tile is a button: the frame takes no press until it is the view)
+      pointerEvents: view === index ? 'auto' : 'none',
+      zIndex: view === index ? '1' : '0',
+    });
+  });
+  run.stage.edit?.(view === 'edit' ? 'live' : view === 'grid' ? stdTile(0, players.length + 1) : 'hidden');
+}
+
+/** Opens a view: the frames placed, its player the person's and the rest the bot's, the keyboard in its page. */
+export function setStdView(view: StdView): void {
+  if (!run || (typeof view === 'number' && !run.players[view])) return;
+  run.view = view;
+  run.log.append('play', 'view', { view: typeof view === 'number' ? `player ${run.players[view]!.number}` : view });
+  place();
+  driveForView();
+  if (typeof view === 'number') run.players[view]!.frame.focus();
+  publishRun();
+}
+
+/** The views in their Tab order: Edit, each player, Grid. */
+function stdViews(): StdView[] {
+  return run ? ['edit', ...run.players.map((_, index) => index), 'grid'] : [];
+}
+
+/** Why the viewed player's bot cannot be switched on (or off) now, null when it can: a goal of the game's (switching
+ *  on), a player viewed and its page joined. */
+function autoplayUnavailable(player: StdPlayer | undefined, on = true, goal?: string): string | null {
+  if (on && run && run.goals.length === 0 && run.goal === null) return 'No autoplay: the game\'s autopilot/ program offers no goal for its bot.';
+  if (on && run && goal !== undefined && run.goals.length > 0 && !run.goals.includes(goal))
+    return `This game's bot has no goal "${goal}"; its goals are ${run.goals.map((one) => `"${one}"`).join(', ')}.`;
+  if (!player) return 'Autoplay drives the viewed player: open one (1 to 4); the others\' autopilots drive on their own.';
+  return player.device === null ? `Autoplay drives Player ${player.number} once its page has joined.` : null;
+}
+
+/** Whether the viewed player's bot drives (Autoplay's state), the goal it plays, the game's goals, and why it cannot
+ *  be switched on, null when it can. */
+export function stdAutoplay(): { readonly on: boolean; readonly goal: string | null; readonly goals: readonly string[]; readonly unavailable: string | null;
+  readonly headless: StdRun['headless'] } {
+  const player = run && typeof run.view === 'number' ? run.players[run.view] : undefined;
+  return {
+    on: player?.autopilot ?? false,
+    goal: run && player ? goalOf(run, player) : run?.goal ?? null,
+    goals: run?.goals ?? knownGoals,
+    unavailable: autoplayUnavailable(player),
+    headless: run?.headless ?? null,
+  };
+}
+
+/** The game's goals read again (its `autopilot/` program is the author's to change), the run's goal kept among them. */
+async function refreshGoals(current: LiveRun): Promise<void> {
+  const { goals } = await askPlay<{ goals: string[] }>('/goals');
+  current.goals = knownGoals = goals;
+  if (current.goal === null || (goals.length > 0 && !goals.includes(current.goal))) current.goal = goals[0] ?? null;
+  publishRun();
+}
+
+/**
+ * AUTOPLAY ON OR OFF, on with `goal` where one is named, the goals read again first; refused with the reason where it
+ * cannot be. Asked by an agent (`cli`), or while the editor is not seen (a hidden page draws no frames, so its players'
+ * pages run nothing), it is std's own play of the goal on its headless device (`playGoalHeadless`), whose pages play
+ * whether or not the editor is seen; from the panel the person sees, it is the viewed player's bot.
+ */
+export async function setStdAutoplay(on: boolean, by: 'panel' | 'cli', goal?: string): Promise<void> {
+  const current = run;
+  if (on && current) await refreshGoals(current);
+  if (on && current && (by === 'cli' || document.visibilityState === 'hidden')) {
+    const chosen = goal ?? current.goal;
+    if (chosen === null) throw new Error('No autoplay: the game\'s autopilot/ program offers no goal for its bot.');
+    if (current.goals.length > 0 && !current.goals.includes(chosen))
+      throw new Error(`This game's bot has no goal "${chosen}"; its goals are ${current.goals.map((one) => `"${one}"`).join(', ')}.`);
+    playGoalHeadless(current, chosen, by);
+    return;
+  }
+  const player = run && typeof run.view === 'number' ? run.players[run.view] : undefined;
+  // (off from here ends the headless play on from here started, and the viewed player's bot where it drives)
+  if (!on && by === 'cli' && headlessPlay !== null) {
+    endHeadlessPlay(undefined, 'ended by `autoplay off` before std said how it ended');
+    if (player?.autopilot === true) drive(player, false, by);
+    return;
+  }
+  const refused = autoplayUnavailable(player, on, goal);
+  if (refused !== null) throw new Error(refused);
+  drive(player!, on, by, on ? goal : undefined);
+}
+
+/** The session's one headless play of a goal, and the run that started it. */
+let headlessPlay: { readonly run: LiveRun; readonly abort: AbortController } | null = null;
+
+/** The headless play ended where one plays (`run` given: only that run's), its socket to std closed. */
+function endHeadlessPlay(run?: LiveRun, why = 'ended by Play before std said how it ended'): void {
+  if (headlessPlay === null || (run !== undefined && headlessPlay.run !== run)) return;
+  const { run: started, abort } = headlessPlay;
+  headlessPlay = null;
+  abort.abort();
+  if (!started.stopped && started.headless?.state === 'playing') {
+    started.headless = { ...started.headless, state: 'failed', why };
+    started.log.append('play', 'autoplay-end', { goal: started.headless.goal, achieved: false, why: started.headless.why });
+    publishRun();
+  }
+}
+
+/** A bot's line as std's play says it (play.ts `said`): `<slot> (<device>, <mode>): done | failed: <why> | no outcome`,
+ *  then what else it noted. */
+const BOT_LINE = /^(\S+) \(([^,]+), ([^)]+)\): (done|failed: (.*?)|no outcome)(?:; (.*))?$/;
+
+/**
+ * STD'S OWN PLAY OF A GOAL, on its headless device (`../serving/std-dev.ts`'s `/play`, std's `/__std/play`): its bots
+ * play the goal to its end on pages std opens, recorded in the run's folder, then the goal's checks read the
+ * recording. Each line std says is the play log's (`outcome` for a bot's end, `check` for a failed check, `play-line`
+ * otherwise), the bots' own traces too (their intents among them: `follow`), and its end is `autoplay-end` and the
+ * Game panel's line: `<goal>: achieved`, or `<goal>: failed — why`.
+ */
+function playGoalHeadless(current: LiveRun, goal: string, by: 'panel' | 'cli'): void {
+  if (current.url === null) throw new Error('The game\'s dev server is still starting: autoplay once Play is running.');
+  // (one headless play a session at a time: a new one ends the one before, whichever run started it)
+  endHeadlessPlay();
+  const abort = new AbortController();
+  headlessPlay = { run: current, abort };
+  current.headless = { goal, state: 'playing', why: null };
+  current.log.append('play', 'autoplay-on', { goal, device: 'headless', by });
+  publishRun();
+  const failures: string[] = [];
+  // (what std said last: a play that failed before any bot ended, its own error among them, says why there)
+  let lastLine: string | null = null;
+  // (an ended run, or a play another has replaced, hears nothing more of it)
+  const live = (): boolean => !current.stopped && headlessPlay?.abort === abort;
+  const said = (line: string): void => {
+    if (!live()) return;
+    const bot = BOT_LINE.exec(line);
+    if (bot) {
+      const why = bot[5] ?? (bot[4] === 'no outcome' ? 'no outcome' : null);
+      if (bot[4] !== 'done') failures.push(`${bot[1]!}: ${why ?? ''}${bot[6] ? `; ${bot[6]}` : ''}`);
+      current.log.append('play', 'outcome', { slot: bot[1], goal, achieved: bot[4] === 'done', ...(why ? { why } : {}), device: bot[2], mode: bot[3], ...(bot[6] ? { noted: bot[6] } : {}) });
+    } else if (line.startsWith('check failed: ')) {
+      failures.push(line);
+      current.log.append('play', 'check', { goal, ok: false, failure: line.slice('check failed: '.length) });
+    } else {
+      lastLine = line;
+      current.log.append('play', 'play-line', { goal, line });
+    }
+  };
+  const ended = (ok: boolean): void => {
+    if (!live()) return;
+    headlessPlay = null;
+    const why = ok ? null : failures[0] ?? lastLine ?? 'std\'s play ended failed and said nothing';
+    current.headless = { goal, state: ok ? 'achieved' : 'failed', why };
+    current.log.append('play', 'autoplay-end', { goal, achieved: ok, ...(why === null ? {} : { why }) });
+    publishRun();
+  };
+  void (async () => {
+    // (aborted, the route closes its socket to std's play, which ends it)
+    const response = await fetch('/__editor/play/std/play', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ goal }), signal: abort.signal });
+    if (!response.ok || response.body === null) {
+      said(((await response.json().catch(() => ({}))) as { error?: string }).error ?? `std's play answered ${response.status}`);
+      ended(false);
+      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 } };
+        rest = rest.slice(at + 1);
+        if (message.end !== undefined) { ended(message.end.ok === true); return; }
+        if (typeof message.line === 'string') said(message.line);
+      }
+    }
+    said('std\'s play ended before it said how.');
+    ended(false);
+  })().catch((error: unknown) => {
+    said(error instanceof Error ? error.message : String(error));
+    ended(false);
+  });
+}
+
+/** The player whose page answers for the run: the viewed one, else the first joined. */
+function answering(current: LiveRun): StdPlayer | undefined {
+  const viewed = typeof current.view === 'number' ? current.players[current.view] : undefined;
+  return viewed?.device ? viewed : current.players.find((player) => player.device !== null);
+}
+
+/** The viewed player's page's next frame, captured by std's receiver; its file. */
+export async function captureStdView(): Promise<string> {
+  const player = run ? answering(run) : undefined;
+  if (!player?.device) throw new Error('No player\'s page has joined the game yet.');
+  const file = await stdCapture(player.device);
+  run?.log.append('play', 'capture', { slot: player.slot, file });
+  return file;
+}
+
+/**
+ * THE CLOCK SAID TO EVERY JOINED PLAYER'S PAGE (std's `clock` control): the game held, released, stepped `frames` or
+ * set to a speed on each, the answering player's clock kept as the run's. Refused where nothing of the document's
+ * plays, or no page has joined.
+ */
+async function clockAll(documentId: string, asked: StdClockAction): Promise<StdClock> {
+  const current = run && !run.stopped && run.documentId === documentId ? run : null;
+  if (!current) throw new Error(`Nothing is playing in ${documentId}; \`play\` starts it.`);
+  const joined = current.players.filter((player) => player.device !== null);
+  if (joined.length === 0) throw new Error('No player\'s page has joined the game yet.');
+  const answers = await Promise.all(joined.map((player) => stdClock(player.device!, asked).then((clock) => ({ player, clock }))));
+  const said = answers.find(({ player }) => player === answering(current)) ?? answers[0]!;
+  current.log.append('play', asked.action, { ...asked, ...said.clock });
+  setModelPlayClock(documentId, said.clock);
+  return said.clock;
+}
+
+/** Pause or resume every player's page. */
+export function setStdPaused(documentId: string, paused: boolean): Promise<StdClock> {
+  return clockAll(documentId, { action: paused ? 'pause' : 'resume' });
+}
+
+/** Step every player's page `frames` frames of 1/60 s, pausing it first. */
+export function stepStd(documentId: string, frames: number): Promise<StdClock> {
+  return clockAll(documentId, { action: 'step', frames });
+}
+
+/** The person's speed, kept for the page's life, and said to every player's page that has joined. */
+export async function setStdSpeed(documentId: string, speed: number): Promise<void> {
+  setModelPlaySpeed(documentId, speed);
+  if (run && !run.stopped && run.documentId === documentId && run.players.some((player) => player.device !== null))
+    await clockAll(documentId, { action: 'speed', speed });
+}
+
+/** A page that has just joined runs on the run's clock: held where the run is paused, at the person's speed. */
+function keepClock(current: LiveRun, player: StdPlayer): void {
+  const { paused, speed } = modelPlayClock(current.documentId);
+  const device = player.device;
+  if (device === null) return;
+  const said = (asked: StdClockAction): Promise<void> => stdClock(device, asked).then(() => {},
+    (error: unknown) => current.log.append('play', 'script-error', { phase: 'clock', slot: player.slot, message: String(error) }));
+  void (speed !== 1 ? said({ action: 'speed', speed }) : Promise.resolve()).then(() => (paused ? said({ action: 'pause' }) : undefined));
+}
+
+/** How long a page has to answer one of the agent's doors (`act`, `inspect`) before the door says it did not. */
+const FRAMED_MS = 3000;
+/** How long a capture has: the page's next frame drawn, posted and written, then read back. */
+const CAPTURE_MS = 8000;
+
+/** A player's frame's driver: its page's keys, labelled nodes and inspection, through std's `act` and `inspect`. Each
+ *  answer is the page's within {@link FRAMED_MS}, or a refusal saying why not: not joined, refused by std, or slow. */
+function frameDriver(player: StdPlayer): Parameters<typeof registerFramedDriver>[1] {
+  const title = `Player ${player.number}'s page`;
+  const device = (): string => {
+    if (player.device === null) throw new Error(`${title} has not joined the game yet.`);
+    return player.device;
+  };
+  const bounded = <T>(what: string, asked: Promise<T>, ms = FRAMED_MS): Promise<T> => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const late = new Promise<never>((_, fail) => {
+      timer = setTimeout(() => fail(new Error(`${title} did not answer ${what} within ${ms / 1000} s.`)), ms);
+    });
+    return Promise.race([asked.catch((error: unknown) => {
+      throw new Error(`${title} refused ${what}: ${error instanceof Error ? error.message : String(error)}`);
+    }), late]).finally(() => clearTimeout(timer));
+  };
+  return {
+    title: () => title,
+    async key({ code, holdMs }) {
+      const at = device();
+      // (the release goes whatever the press answered: a press that lands late must not leave the key held)
+      try {
+        await bounded(`the key ${code}`, stdAct(at, [{ key: { key: code, down: true } }]));
+        if (holdMs > 0) await new Promise((done) => setTimeout(done, holdMs));
+      } finally {
+        await bounded(`the key ${code}'s release`, stdAct(at, [{ key: { key: code, down: false } }]));
+      }
+    },
+    async press({ x, y }) {
+      const at = device();
+      // (the press and its release, which std's pointer makes a click of, in one act: the release goes with it)
+      await bounded('a press', stdAct(at, [{ pointer: { x, y, button: 0, down: true } }, { pointer: { x, y, button: 0, down: false } }]));
+    },
+    async nodes(limit) {
+      const { screen, truncated } = await bounded('inspect', stdInspect(device()));
+      return { matched: screen.length + (truncated?.screen ?? 0), nodes: screen.slice(0, limit) };
+    },
+    inspect: () => bounded('inspect', stdInspect(device())),
+    // (the page's own frame, written by std's receiver: what its canvas drew, as std's `capture` takes it)
+    capture: () => bounded('capture', (async () => {
+      const file = await stdCapture(device());
+      run?.log.append('play', 'capture', { slot: player.slot, file });
+      return stdCaptured(file);
+    })(), CAPTURE_MS),
+  };
+}
+
+/**
+ * EACH PLAYER BOUND TO ITS PAGE AS IT IS NOW: the device whose page's trace names the player's slot, the
+ * newest where a page that loaded again is still listed beside its old one. A player whose page changed is told who
+ * drives it again (a new page starts with nobody's bot), and its trace is read from the new page's start.
+ */
+async function bind(current: LiveRun): Promise<void> {
+  const [devices, slots] = await Promise.all([
+    askPlay<{ id: string; kind: string }[]>('/devices'),
+    askPlay<Record<string, string>>('/pages'),
+  ]);
+  for (const player of current.players) {
+    const pages = Object.entries(slots).filter(([, slot]) => slot === player.slot).map(([page]) => page);
+    // A page's device is `<kind>-<its id's first 8>` (std-dev's device list), whatever kind the page says it is.
+    const deviceOf = (page: string) => devices.find((device) => device.id === `${device.kind}-${page.slice(0, 8)}`)?.id;
+    const found = pages.map(deviceOf).filter((id) => id !== undefined).at(-1);
+    if (found === undefined || found === player.device) continue;
+    const joined = player.device === null;
+    player.device = found;
+    player.page = pages.find((page) => deviceOf(page) === found)!;
+    player.traced = 0;
+    current.log.append('play', joined ? 'player-joined' : 'player-page-loaded', { slot: player.slot, device: found });
+    tellDriver(current, player);
+    keepClock(current, player);
+    publishRun();
+  }
+}
+
+/** A player taken out of the run: its page unloaded, its client leaving. */
+function retire(current: LiveRun, player: StdPlayer): void {
+  current.players.splice(current.players.indexOf(player), 1);
+  player.undrive();
+  player.frame.remove();
+  if (typeof current.view === 'number' && current.view >= current.players.length) current.view = Math.max(0, current.players.length - 1);
+  place();
+}
+
+/** One more player, as the person asks (Players [+]). */
+export function addStdPlayer(): void {
+  if (!run || run.players.length >= MOST_PLAYERS) return;
+  playerCounts.set(run.documentId, Math.min(MOST_PLAYERS, (playerCounts.get(run.documentId) ?? FIRST_PLAYERS) + 1));
+  join(run);
+}
+
+/** One more player: a page of its own, a real client joining, joined before the next is added. A page that never
+ *  joins, or whose join cannot be read, is taken out again, its failure kept as the run's. */
+function join(current: LiveRun): void {
+  current.adding = current.adding.then(async () => {
+    if (current.stopped || current.url === null || current.players.length >= MOST_PLAYERS) return;
+    const number = Math.max(0, ...current.players.map((player) => player.number)) + 1;
+    const slot = `${current.tag}-${number}`;
+    const frame = document.createElement('iframe');
+    frame.setAttribute('credentialless', '');
+    frame.title = `Player ${number}`;
+    frame.dataset['testid'] = `std-player-${number}`;
+    Object.assign(frame.style, { position: 'absolute', border: '0', background: '#000' });
+    const at = new URL(current.url);
+    at.hostname = location.hostname;
+    at.searchParams.set('slot', slot);
+    frame.src = at.href;
+    const player: StdPlayer = { number, slot, frame, page: null, device: null, autopilot: false, goal: null, traced: 0, undrive: () => {} };
+    Object.assign(player, { undrive: registerFramedDriver(frame, frameDriver(player)) });
+    current.players.push(player);
+    current.host.appendChild(frame);
+    place();
+    publishRun();
+    const bound = Date.now() + JOIN_MS;
+    try {
+      while (player.device === null) {
+        if (current.stopped) return;
+        if (Date.now() > bound) throw new Error(`Player ${number}'s page did not join the game's dev server within ${JOIN_MS / 1000} s.`);
+        await new Promise((done) => setTimeout(done, LOOK_MS));
+        await bind(current);
+      }
+    } catch (error) {
+      if (!current.stopped) retire(current, player);
+      throw error;
+    }
+    driveForView();
+    publishRun();
+  }).catch((error: unknown) => {
+    if (current.stopped) return;
+    const failure = error instanceof Error ? error.message : String(error);
+    current.failure = failure;
+    current.log.append('play', 'script-error', { phase: 'player', message: failure });
+    current.stage.report('A player could not join', failure);
+    publishRun();
+  });
+}
+
+/** One player fewer, as the person asks (Players [-]): the last one's page unloaded, its client leaving. */
+export function removeStdPlayer(): void {
+  const current = run;
+  if (!current) return;
+  playerCounts.set(current.documentId, Math.max(1, (playerCounts.get(current.documentId) ?? FIRST_PLAYERS) - 1));
+  current.adding = current.adding.then(() => {
+    if (current.stopped || current.players.length <= 1) return;
+    const player = current.players.at(-1)!;
+    retire(current, player);
+    current.log.append('play', 'player-left', { slot: player.slot, device: player.device });
+    driveForView();
+    publishRun();
+  });
+}
+
+/**
+ * A PLAYER'S PAGE THREW (its trace's `error` line, std's error fields: `label`, `source`, `stack`; `file`, `line`,
+ * `column` where the page knew them): the game's uncaught error is the editor's to show. Each distinct one (by its
+ * message and where) is an error in the editor's console from Play, naming its player, and the newest is the Game
+ * panel's status.
+ */
+function pageError(current: LiveRun, player: StdPlayer, facts: Record<string, unknown>): void {
+  const label = typeof facts['label'] === 'string' ? facts['label'] : 'an error with no message';
+  const at = typeof facts['file'] === 'string'
+    ? ` (${facts['file'].replace(/^https?:\/\/[^/]+/, '').replace(/\?[^:]*/, '')}${facts['line'] !== undefined ? `:${String(facts['line'])}` : ''}${facts['column'] !== undefined ? `:${String(facts['column'])}` : ''})`
+    : '';
+  const said = `${label}${at}`;
+  current.lastError = `Player ${player.number}: ${said}`;
+  publishRun();
+  if (current.errorsSaid.has(said)) return;
+  current.errorsSaid.add(said);
+  const stack = typeof facts['stack'] === 'string' ? `\n${facts['stack'].split('\n').slice(1, 5).join('\n')}` : '';
+  editorHost().console.error(`The game threw in Player ${player.number}'s page (${player.slot}): ${said}${stack}`, 'play');
+}
+
+/**
+ * WHAT THE DEV SERVER SAID ON ITS ERROR OUTPUT, in blocks (a line and the indented lines under it: an exception and its
+ * stack). The room's own exceptions are Colyseus's to log there, never in a page's trace: a block that names an
+ * `Error` or carries a stack is a `script-error` in the play log (phase `server`), the Game panel's newest error, and,
+ * once each (by its first line, so a handler throwing at every message says it once), an error in the editor's
+ * console from Play. Anything else there (Vite's and Node's warnings, npm's notices) is the play log's `server-output`.
+ */
+function serverSaid(current: LiveRun, lines: readonly string[]): void {
+  const blocks: string[][] = [];
+  for (const line of lines) {
+    if (line.trim() === '') continue;
+    if (/^\s/.test(line) && blocks.length > 0) blocks.at(-1)!.push(line);
+    else blocks.push([line]);
+  }
+  for (const block of blocks) {
+    const said = block.join('\n');
+    // (a block that starts indented is the rest of one a look before read: its error was said there)
+    if (/^\s/.test(block[0]!) || (!/Error\b/.test(block[0]!) && !block.some((line) => /^\s+at\s/.test(line)))) {
+      current.log.append('play', 'server-output', { message: said });
+      continue;
+    }
+    current.log.append('play', 'script-error', { phase: 'server', message: said });
+    current.lastError = `The game's dev server: ${block[0]!}`;
+    publishRun();
+    // (by the error's own words: Vite starts each line with the time it said it, which no two of a repeating error share)
+    const key = `server: ${block[0]!.replace(/^\d{1,2}:\d{2}:\d{2}(?:\s?[AP]M)?\s+/i, '')}`;
+    if (current.errorsSaid.has(key)) continue;
+    current.errorsSaid.add(key);
+    editorHost().console.error(`The game's dev server threw:\n${block.slice(0, 6).join('\n')}`, 'play');
+  }
+}
+
+/** The dev server's error output read on from the run's mark (where it stood as the run began; taken now, where the
+ *  run's start couldn't), into the play log. */
+async function followServer(current: LiveRun): Promise<void> {
+  const read = current.serverErrors;
+  const errors = await askPlay<{ lines: string[]; next: number; server: number | null }>(read === null
+    ? '/errors' : `/errors?${new URLSearchParams({ server: String(read.server ?? ''), from: String(read.next) })}`);
+  current.serverErrors = { server: errors.server, next: errors.next };
+  if (read !== null) serverSaid(current, errors.lines);
+}
+
+/** Each player's page bound again, and its trace read on from where it was, into the play log. */
+async function follow(current: LiveRun): Promise<void> {
+  await bind(current);
+  // (its own failure the play log's, apart from the traces read after it)
+  await followServer(current).catch((error: unknown) => {
+    const said = `server-output: ${String(error)}`;
+    if (current.errorsSaid.has(said)) return;
+    current.errorsSaid.add(said);
+    current.log.append('play', 'server-output', { message: `Play could not read the dev server's error output: ${String(error)}` });
+  });
+  // (std's headless bots' pages, from the run's first headless play on: their slots are std's play's own)
+  if (current.headless !== null) {
+    for (const [page, slot] of Object.entries(await askPlay<Record<string, string>>('/pages')))
+      if (/^(server|p2p)-\d+$/.test(slot) && !current.headlessTraced.has(page)) current.headlessTraced.set(page, { slot, traced: 0 });
+    for (const [page, read] of current.headlessTraced) {
+      const { lines, next } = await askPlay<{ lines: string[]; next: number }>(`/trace?page=${page}&from=${read.traced}`);
+      read.traced = next;
+      for (const line of lines) {
+        const { k, s, ...facts } = JSON.parse(line) as { k?: unknown; s?: unknown } & Record<string, unknown>;
+        current.log.append('script', typeof k === 'string' ? k : 'trace', { slot: read.slot, ...facts },
+          typeof s === 'number' && Number.isFinite(s) ? { simT: s / TRACE_STEPS_PER_SECOND, tick: s } : undefined);
+      }
+    }
+  }
+  for (const player of current.players) {
+    if (player.page === null) continue;
+    const { lines, next } = await askPlay<{ lines: string[]; next: number }>(`/trace?page=${player.page}&from=${player.traced}`);
+    player.traced = next;
+    for (const line of lines) {
+      // (std's trace format 3: `s` the line's step, sixty a second of its page's steady clock)
+      const { k, s, ...facts } = JSON.parse(line) as { k?: unknown; s?: unknown } & Record<string, unknown>;
+      current.log.append('script', typeof k === 'string' ? k : 'trace', { slot: player.slot, ...facts },
+        typeof s === 'number' && Number.isFinite(s) ? { simT: s / TRACE_STEPS_PER_SECOND, tick: s } : undefined);
+      if (k === 'error') pageError(current, player, facts);
+    }
+  }
+}
+
+/** The keys of the view bar, while the editor holds the keyboard: 1 to 4 a player, Tab the next view, Escape Edit. */
+function viewKey(event: KeyboardEvent): void {
+  if (!run || event.defaultPrevented || event.ctrlKey || event.metaKey || event.altKey) return;
+  // (the Export menu's Escape is the menu's)
+  if (event.code === 'Escape' && exportMenuOpen()) return;
+  const target = event.target as HTMLElement | null;
+  if (target && (target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(target.tagName))) return;
+  const views = stdViews();
+  const next: StdView | undefined = /^Digit[1-4]$/.test(event.code) ? Number(event.code.slice(5)) - 1
+    : event.code === 'Tab' ? views[(views.indexOf(run.view) + (event.shiftKey ? views.length - 1 : 1)) % views.length]
+    : event.code === 'Escape' && run.view !== 'edit' ? 'edit' : undefined;
+  if (next === undefined || (typeof next === 'number' && !run.players[next])) return;
+  event.preventDefault();
+  event.stopPropagation();
+  setStdView(next);
+}
+
+/** Run the std game in the stage; the answer stops it (every player's page unloaded, its client leaving). */
+export function runStdGame(stage: DocumentPlayStage, report: (title: string, failure: string) => void, before: Promise<void>): () => void {
+  const { documentId } = stage;
+  const host = document.createElement('div');
+  host.dataset['testid'] = 'std-players';
+  Object.assign(host.style, { position: 'absolute', inset: '0' });
+  // (the bar and the grid's tiles in the stage's overlay, over the document's own area too)
+  const bar = document.createElement('div');
+  const tiles = document.createElement('div');
+  Object.assign(tiles.style, { position: 'absolute', inset: '0', pointerEvents: 'none' });
+  // (the bar stands above the tiles, and its row passes the presses the bar doesn't hold to the tile beneath)
+  Object.assign(bar.style, { position: 'relative', zIndex: '1', pointerEvents: 'none' });
+  stage.container.appendChild(host);
+  (stage.overlay ?? stage.container).append(tiles, bar);
+  const roots: Root[] = [createRoot(bar), createRoot(tiles)];
+  roots[0]!.render(createElement(StdViewBar));
+  roots[1]!.render(createElement(StdGridTiles));
+  const log = beginModelPlayLog(documentId, STD_DEV);
+  const tag = Array.from(crypto.getRandomValues(new Uint8Array(3)), (byte) => byte.toString(16).padStart(2, '0')).join('');
+  const mine: LiveRun = run = { documentId, players: [], view: 0, goal: game?.goal ?? null, goals: knownGoals, url: null, tag, host, stage,
+    log, adding: Promise.resolve(), failure: null, stopped: false, lastError: null, errorsSaid: new Set(), headless: null,
+    headlessTraced: new Map(), serverErrors: null };
+  // (a press in the viewed page is the person's: the editor's window loses the keyboard to it)
+  const tookOver = (): void => {
+    const player = typeof mine.view === 'number' ? mine.players[mine.view] : undefined;
+    if (player && document.activeElement === player.frame) drive(player, false, 'takeover');
+  };
+  window.addEventListener('blur', tookOver);
+  window.addEventListener('keydown', viewKey, true);
+  // (each look after the last has answered, so no two read one trace from the same byte)
+  let looking: ReturnType<typeof setTimeout> | null = null;
+  const lookOn = (): void => {
+    looking = setTimeout(() => {
+      follow(mine).catch((error: unknown) => log.append('play', 'script-error', { phase: 'trace', message: String(error) }))
+        .finally(() => { if (!mine.stopped) lookOn(); });
+    }, LOOK_MS);
+  };
+  // (the level saved first, so the game plays the current edit: its export has run when the pages load)
+  void before.then(async () => {
+    // (the run's mark, before the dev server starts: one started now is read from its first line, one running already
+    // from where its output stands)
+    // (a mark not answered is taken at the run's first look, where the output stands then)
+    const mark = await askPlay<{ next: number; server: number | null }>('/errors').catch(() => null);
+    if (mark !== null) mine.serverErrors = { server: mark.server, next: mark.next };
+  }).then(() => Promise.all([
+    askPlay<{ url: string }>('/start', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' }),
+    // (the game's goals, read again for each run: its autopilot/ program is the author's to change)
+    askPlay<{ goals: string[] }>('/goals').then(({ goals }) => goals, (error: unknown) => {
+      log.append('play', 'script-error', { phase: 'goals', message: error instanceof Error ? error.message : String(error) });
+      return [] as string[];
+    }),
+  ])).then(([{ url }, goals]) => {
+    if (mine.stopped) return;
+    mine.url = url;
+    mine.goals = knownGoals = goals;
+    if (mine.goal === null || (goals.length > 0 && !goals.includes(mine.goal))) mine.goal = goals[0] ?? null;
+    log.append('play', 'running', { url, goals });
+    // (the traces read from the dev server's start, whether or not a player's page joins: std's headless play's bots
+    // play while the editor is not seen, and its players' pages do not)
+    lookOn();
+    for (let n = playerCounts.get(documentId) ?? FIRST_PLAYERS; n > 0; n--) join(mine);
+    void mine.adding.then(() => {
+      if (mine.stopped) return;
+      // (a run with a player who never joined stands with its failure, and draws nothing in front of the document)
+      const failure = mine.failure ?? (mine.players.some((player) => player.device !== null) ? null : 'No player\'s page joined the game.');
+      if (failure !== null) { setModelPlayFailure(documentId, failure); return; }
+      setModelPlayFailure(documentId, null);
+      stage.ready();
+      // (Autoplay armed while stopped drives the viewed player from the run's start, with the goal it was armed with)
+      const arm = takeModelPlayArm(documentId);
+      if (arm !== null)
+        setStdAutoplay(true, 'panel', arm.goal ?? undefined)
+          .catch((error: unknown) => log.append('play', 'autoplay-refused', { message: error instanceof Error ? error.message : String(error) }));
+    });
+    publishRun();
+  }, (error: unknown) => {
+    if (mine.stopped) return;
+    const failure = error instanceof Error ? error.message : String(error);
+    setModelPlayFailure(documentId, failure);
+    report('The game\'s dev server could not be started', failure);
+  });
+  publishRun();
+  return () => {
+    // (Stop, Restart, the document's close and a project change all end here: std's headless play goes with the run)
+    endHeadlessPlay(mine);
+    mine.stopped = true;
+    if (looking !== null) clearTimeout(looking);
+    window.removeEventListener('blur', tookOver);
+    window.removeEventListener('keydown', viewKey, true);
+    for (const root of roots) root.unmount();
+    for (const player of mine.players) player.undrive();
+    host.remove();
+    bar.remove();
+    tiles.remove();
+    log.end();
+    if (run === mine) run = null;
+    publishRun();
+  };
+}