@volter/play 0.5.211 → 0.5.213

package/serving/std-dev.ts

@@ -0,0 +1,547 @@
+/**
+ * A STD GAME'S DEV SERVER, AS PLAY REACHES IT (volter-ai/std, design/circle-1.md, "Devices"). A project is a std game
+ * when it has `std.json` and depends on `@volter-ai/std-dev`. Play hosts its players as the game's own dev pages, each
+ * a device of the dev server (`src/std-game.ts`); this half is the session's side of that:
+ *
+ * - `GET  /__editor/play/std` — `{ game, goal, targets }`: whether the open project is a std game, the goal its bot
+ *   plays, and the engines it ships to besides the web (std's targets: each engine whose package it depends on).
+ * - `POST /__editor/play/std/export` `{ target, add? }` — the game exported: `web` built by `std build` (Vite's, into
+ *   `dist/`), an engine by `std export --target <engine>` after `std target add <engine>`, which makes it one of the
+ *   game's targets where `add` asks (an engine the game doesn't target is refused, 409, otherwise) and completes a
+ *   target half added; each by the game's own std, in its folder, one export a project at a time (409), answered as it
+ *   goes, one JSON object a line (`application/x-ndjson`): each `{ line }` std prints, then `{ end: { ok, added, out }
+ *   }` (whether the target was added, and where the export is). The request gone, the session ending or 30 minutes
+ *   passing ends std's whole process tree.
+ * - `POST /__editor/play/std/start` — `{ url }`: the game's dev server, started where none runs (`npm run dev --
+ *   --no-open`, in the project's folder, owned by this session and ended with it), found by the record std's dev server
+ *   writes in Vite's cacheDir (`node_modules/.vite/std-dev.json`: its address, its process and its endpoints' token).
+ * - `GET  /__editor/play/std/devices`, `POST /__editor/play/std/devices/<id>/control` and `GET
+ *   /__editor/play/std/scene` — std's own endpoints (`/__std/devices`, `/__std/devices/<id>/control`, and the game's
+ *   running scene, `/__std/scene`), asked with the record's token, which stays in this process.
+ * - `GET  /__editor/play/std/goals` — `{ goals }`: the goals of the game's bot, its `autopilot/index.ts` program's
+ *   (`autopilot({ goals })`, std-driver's `program`), read by Node in the game's folder as std reads the game's
+ *   `autopilot/checks.ts` (std-dev's play-checks.ts: Node's own type stripping), each read a process of its own so an
+ *   edited program is read afresh.
+ *
+ * - `GET  /__editor/play/std/level` — `{ blenderHalf }`: the level export's Blender half as the game installed it
+ *   (std-dev's `blender/blend-to-scene.py`), which the page runs in the document's Blender (`../src/std-level.ts`).
+ * - `POST /__editor/play/std/level` `{ glb }` — `{ code, output }`: its Node half, `std level-scene <glb>` in the
+ *   game's folder (from the glb and the `.level.json` the Blender half wrote beside it), by the game's own std
+ *   (std-dev's `bin/std.js`, under the session's Node), for a level's glb or a prefab's (`prefabs/<name>/<name>.glb`,
+ *   whose component std writes as `<Name>.tsx`).
+ *
+ * Every route is the machine owner's alone (`requireLocalOwner`), and a mutating one takes the editor's own origin
+ * (the router's check on `/__editor`); a body is the JSON the router has parsed.
+ * - `GET  /__editor/play/std/pages` — each page of the dev server's newest run folder (`build/runs/<stamp>/`) by its
+ *   id, with the slot its address named (its trace's first line): how Play tells its own players' pages apart.
+ * - `GET  /__editor/play/std/trace?page=<page id>&from=<byte>` — `{ lines, next }`: the page's trace (`<page>.jsonl`
+ *   in that folder) from a byte on, whole lines only.
+ * - `POST /__editor/play/std/play` `{ goal, bots?, device? }` — std's own play of the game's bots to the goal's end
+ *   (`/__std/play`, std-dev's std-endpoints.ts) on `device` (one of std's devices by its id: a player's page in the
+ *   Game view, which std drives as it is) or, where none is named, std's headless device, one bot unless asked,
+ *   recorded in the run's folder and checked by the goal's checks (`autopilot/checks.ts`): answered as it goes, one JSON
+ *   object a line (`application/x-ndjson`), each `{ line }` std says, then `{ end: { ok } }`.
+ * - `GET  /__editor/play/std/capture?file=<page id>-capture-<n>.png` — a page's captured frame, the PNG std's receiver
+ *   wrote in that folder for a `capture` control.
+ * - `GET  /__editor/play/std/output?server=<pid>&stdout=<line>&stderr=<line>` — `{ server, stdout, stderr }`, each
+ *   stream's `{ lines, next }`: what the dev server this session started wrote on each, whole lines, from a line on
+ *   (every line, where `server` names another), or with no lines asked none and where each ends: the room runs in that
+ *   process, so its `console.log` is on stdout and the exceptions Colyseus logs on stderr, never in a page's trace.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { open, readdir, readFile } from 'node:fs/promises';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { join } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { pathToFileURL } from 'node:url';
+import { stripVTControlCharacters } from 'node:util';
+import { npmProcess } from '@volter/sdk/npm-process';
+import { signalProcessTree } from '@volter/sdk/process-tree';
+import type { ProjectServingServices } from '@volter/sdk/session/project-serving';
+import type { Plugin } from 'vite';
+
+const STD_ROUTE = '/__editor/play/std';
+
+/** How long a started dev server has to write its record: a first start optimizes the game's dependencies. */
+const START_MS = 120_000;
+const LOOK_MS = 250;
+/** The most of a trace one read carries. */
+const TRACE_READ_BYTES = 256 * 1024;
+/** The most of a trace's first line read for its head (std's `trace` line: its session, its game, its slot). */
+const TRACE_HEAD_BYTES = 4096;
+/** A page's id as std names it (recording/client page-trace.ts `PAGE_ID`), its trace's file name. */
+const PAGE_ID = /^[0-9a-f]{32}(-rerun)?$/;
+/** A page's captured frame as std's receiver names it (trace-receiver.ts: `<page>-capture-<n>.png`). */
+const CAPTURE_FILE = /^[0-9a-f]{32}(-rerun)?-capture-\d+\.png$/;
+
+/** std-dev as the game installed it, and its level export's Blender half. */
+const stdDev = (root: string): string => join(root, 'node_modules', '@volter-ai', 'std-dev');
+const blenderHalfOf = (root: string): string => join(stdDev(root), 'blender', 'blend-to-scene.py');
+
+/** A level's glb or a prefab's, by its path from the game's folder: under `levels/`, or a prefab's own
+ *  (`prefabs/<name>/<name>.glb`, std's), with no empty, `.` or `..` segment. */
+const isLevelGlb = (path: string): boolean =>
+  (/^levels\/.+\.glb$/.test(path) || /^prefabs\/([^/]+)\/\1\.glb$/.test(path))
+  && !path.includes('\\') && path.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
+
+/** The level export's Node half: its exit code and everything it printed, in order. */
+function runStdLevel(root: string, glb: string): Promise<{ readonly code: number | null; readonly output: string }> {
+  return new Promise((resolve) => {
+    const run = spawn(process.execPath, [join(stdDev(root), 'bin', 'std.js'), 'level-scene', glb], { cwd: root, windowsHide: true });
+    let output = '';
+    run.stdout.on('data', (chunk: Buffer) => { output += chunk.toString(); });
+    run.stderr.on('data', (chunk: Buffer) => { output += chunk.toString(); });
+    run.on('error', (error) => resolve({ code: null, output: `${output}${error.message}` }));
+    run.on('close', (code) => resolve({ code, output }));
+  });
+}
+
+/** How long the read of the bot's goals may take: Node loading the program and the driver it imports. */
+const GOALS_MS = 10_000;
+/** The bot program's module, as std's convention names it (std-dev's page-modules.ts `BOT_ENTRY`, `/autopilot/index`). */
+const BOT_ENTRIES = ['index.ts', 'index.js', 'index.mjs'];
+
+/** Prints the goals of the program the module at `process.argv[1]` exports as `program`, one JSON line. */
+const READ_GOALS = [
+  'const program = (await import(process.argv[1])).program;',
+  "if (typeof program?.goals !== 'object' || program.goals === null) throw new Error('autopilot/index exports no program with goals (autopilot({ goals }))');",
+  'console.log(JSON.stringify(Object.keys(program.goals)));',
+].join('\n');
+
+/** The goals of the game's bot: its `autopilot/` program's, in their order; none where the game has no bot. */
+function botGoals(root: string): Promise<{ readonly status: number; readonly body: unknown }> {
+  const entry = BOT_ENTRIES.map((name) => join(root, 'autopilot', name)).find((file) => existsSync(file));
+  if (entry === undefined) return Promise.resolve({ status: 200, body: { goals: [] } });
+  return new Promise((resolve) => {
+    const read = spawn(process.execPath, ['--input-type=module', '--eval', READ_GOALS, pathToFileURL(entry).href],
+      { cwd: root, windowsHide: true, timeout: GOALS_MS });
+    let output = '';
+    let said = '';
+    read.stdout.on('data', (chunk: Buffer) => { output += chunk.toString(); });
+    read.stderr.on('data', (chunk: Buffer) => { said += chunk.toString(); });
+    read.on('error', (error) => resolve({ status: 500, body: { error: `The game's goals could not be read: ${error.message}` } }));
+    read.on('close', (code) => {
+      let goals: unknown = null;
+      try { if (code === 0) goals = JSON.parse(output.trim().split('\n').at(-1) ?? '[]'); } catch { /* not the line READ_GOALS prints */ }
+      resolve(Array.isArray(goals) && goals.every((goal) => typeof goal === 'string')
+        ? { status: 200, body: { goals } }
+        : { status: 500, body: { error: `The game's goals could not be read from ${entry} (exit ${String(code)}): ${said.trim() || output.trim()}` } });
+    });
+  });
+}
+
+/** The level route's answer: the Blender half's source (GET), or the Node half's run on a level's glb (POST). */
+async function levelAnswer(root: string, method: string | undefined, body: unknown): Promise<{ readonly status: number; readonly body: unknown }> {
+  if (!stdGame(root).game || !existsSync(blenderHalfOf(root)))
+    return { status: 404, body: { error: 'The project is not a std game with @volter-ai/std-dev installed: no std.json, or no blender/blend-to-scene.py in its std-dev.' } };
+  if (method === 'GET') return { status: 200, body: { blenderHalf: await readFile(blenderHalfOf(root), 'utf8') } };
+  const glb = (body as { glb?: unknown } | undefined)?.glb;
+  if (typeof glb !== 'string' || !isLevelGlb(glb))
+    return { status: 400, body: { error: `A level's glb is a path under levels/ ending .glb, a prefab's prefabs/<name>/<name>.glb; it was given ${JSON.stringify(glb)}.` } };
+  return { status: 200, body: await runStdLevel(root, glb) };
+}
+
+/** std's record of a running dev server (std-dev's running-server.ts `RunningServer`). */
+interface RunningServer {
+  readonly url: string;
+  readonly pid: number;
+  readonly token: string;
+}
+
+/** Each engine a std game may ship to, and its package: the game's target where it depends on it (std's own reading,
+ *  std-dev's engines.ts `ENGINES` and `enginesOf`). */
+const ENGINE_PACKAGES = { roblox: '@volter-ai/std-roblox', unreal: '@volter-ai/std-unreal' } as const;
+type Engine = keyof typeof ENGINE_PACKAGES;
+const ENGINE_LABELS: Readonly<Record<Engine, string>> = { roblox: 'Roblox', unreal: 'Unreal' };
+const isEngine = (value: unknown): value is Engine => typeof value === 'string' && Object.hasOwn(ENGINE_PACKAGES, value);
+
+/** Whether the project in `root` is a std game (`std.json`, and `@volter-ai/std-dev` among its packages), the goal its
+ *  bot plays (the one its `play` script names, `std play … --goal <goal>`, null where it names none), and its targets. */
+function stdGame(root: string): { readonly game: boolean; readonly goal: string | null; readonly targets: readonly Engine[] } {
+  if (!existsSync(join(root, 'std.json'))) return { game: false, goal: null, targets: [] };
+  const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as Record<string, Record<string, string> | undefined>;
+  const named = (name: string): boolean => manifest.dependencies?.[name] !== undefined || manifest.devDependencies?.[name] !== undefined;
+  const targets = (Object.keys(ENGINE_PACKAGES) as Engine[]).filter((engine) => named(ENGINE_PACKAGES[engine]));
+  return { game: named('@volter-ai/std-dev'), goal: /--goal[ =](\S+)/.exec(manifest.scripts?.play ?? '')?.[1] ?? null, targets };
+}
+
+/** How long an export may take before the route ends it: a Roblox export uploads the game's models first. */
+const EXPORT_MS = 30 * 60_000;
+/** Where each export is, from the game's folder. */
+const EXPORTED: Readonly<Record<'web' | Engine, string>> = { web: 'dist', roblox: 'build/roblox', unreal: 'build/unreal/StdGame' };
+
+/** The most of one line std prints that an export passes on (a progress bar's line can run long). */
+const EXPORT_LINE_MOST = 2000;
+/** Each project's export while it runs: its abort, which ends std's process tree, as the session's end does too. */
+const exporting = new Map<string, AbortController>();
+
+/** Every running export ended, as the session ends: std's process trees with them. */
+function endExports(): void {
+  for (const ended of exporting.values()) ended.abort();
+  exporting.clear();
+}
+
+/** The game's own std run in its folder, each line it prints told as it comes; its exit code, null where it could not
+ *  run or was ended. It runs in a process group of its own (detached, as the dev server does), so ending it ends what
+ *  it started: pnpm, Rojo, an engine's tools. */
+function runStd(root: string, args: readonly string[], line: (text: string) => void, ended: AbortSignal): Promise<number | null> {
+  return new Promise((resolve) => {
+    const run = spawn(process.execPath, [join(stdDev(root), 'bin', 'std.js'), ...args],
+      { cwd: root, windowsHide: true, detached: process.platform !== 'win32' });
+    const lines = (): ((chunk: Buffer | null) => void) => {
+      const decoder = new StringDecoder('utf8');
+      let held = '';
+      return (chunk) => {
+        held += chunk === null ? decoder.end() : decoder.write(chunk);
+        const parts = held.split(/\r\n|\r|\n/);
+        held = chunk === null ? '' : parts.pop() ?? '';
+        if (held.length > EXPORT_LINE_MOST) { parts.push(held); held = ''; }
+        for (const part of parts) if (part.trim() !== '') line(stripVTControlCharacters(part).slice(0, EXPORT_LINE_MOST));
+      };
+    };
+    const out = lines();
+    const err = lines();
+    run.stdout.on('data', out);
+    run.stdout.on('end', () => out(null));
+    run.stderr.on('data', err);
+    run.stderr.on('end', () => err(null));
+    const end = (): void => { if (run.pid !== undefined && run.exitCode === null) signalProcessTree(run.pid, 'SIGTERM'); };
+    ended.addEventListener('abort', end, { once: true });
+    run.on('error', (error) => { line(error.message); resolve(null); });
+    run.on('close', (code) => { ended.removeEventListener('abort', end); resolve(code); });
+  });
+}
+
+/** THE GAME EXPORTED to `target`: the web, or an engine, made one of the game's targets first where `add` asks. */
+async function exportGame(root: string, body: unknown, response: ServerResponse): Promise<void> {
+  const asked = body as { target?: unknown; add?: unknown } | undefined;
+  const target = asked?.target;
+  if ((target !== 'web' && !isEngine(target)) || (asked?.add !== undefined && typeof asked.add !== 'boolean'))
+    return answer(response, 400, { error: `An export is { target, add? }: web, roblox or unreal, and whether to add an engine as the game's target; it was given ${JSON.stringify(body)}.` });
+  const game = stdGame(root);
+  if (!game.game) return answer(response, 404, { error: 'The project is not a std game: no std.json, or no @volter-ai/std-dev among its packages.' });
+  const added = target !== 'web' && !game.targets.includes(target);
+  if (added && asked?.add !== true)
+    return answer(response, 409, { error: `${ENGINE_LABELS[target]} isn't a target of this game: Export's "Add ${ENGINE_LABELS[target]} and export" adds it (std target add ${target}).` });
+  if (exporting.has(root)) return answer(response, 409, { error: 'An export of this game is running: wait for it to end.' });
+  const ended = new AbortController();
+  exporting.set(root, ended);
+  response.statusCode = 200;
+  response.setHeader('content-type', 'application/x-ndjson');
+  const said = (message: unknown): void => { if (!response.writableEnded && !response.destroyed) response.write(`${JSON.stringify(message)}\n`); };
+  response.on('close', () => ended.abort());
+  const limit = setTimeout(() => { said({ line: `Play ended the export: it ran ${EXPORT_MS / 60_000} minutes.` }); ended.abort(); }, EXPORT_MS);
+  // (an engine's `target add` every time: it adds the target where asked, completes one half added, and is quiet where
+  // the target is whole)
+  const steps = target === 'web' ? [['build']] : [['target', 'add', target], ['export', '--target', target]];
+  let ok = true;
+  try {
+    for (const step of steps) {
+      if (ended.signal.aborted) { ok = false; break; }
+      said({ line: `std ${step.join(' ')}` });
+      if ((await runStd(root, step, (line) => said({ line }), ended.signal)) !== 0) { ok = false; break; }
+    }
+  } finally {
+    clearTimeout(limit);
+    if (exporting.get(root) === ended) exporting.delete(root);
+  }
+  said({ end: { ok, added: added && stdGame(root).targets.includes(target), out: EXPORTED[target] } });
+  response.end();
+}
+
+const alive = (pid: number): boolean => {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+};
+
+/** The game's running dev server by its record, or null where none runs (no record, or its process gone). */
+async function runningServer(root: string): Promise<RunningServer | null> {
+  const text = await readFile(join(root, 'node_modules', '.vite', 'std-dev.json'), 'utf8').catch(() => null);
+  if (text === null) return null;
+  const record = JSON.parse(text) as RunningServer;
+  return alive(record.pid) ? record : null;
+}
+
+/** The most of each of a dev server's streams kept, in lines. */
+const OUTPUT_KEPT = 500;
+
+/** One of a dev server's output streams as lines (the first kept one being line `dropped`), the line not yet ended,
+ *  and its decoder. Each stream is kept apart, so a room logging at every tick never pushes out an exception. */
+interface OutputStream {
+  readonly lines: string[];
+  dropped: number;
+  partial: string;
+  readonly decoder: StringDecoder;
+}
+
+/** The dev servers this session started, by project, with the last of what each said, why its launch failed, and its
+ *  two streams: stdout, where a room's `console.log` and Vite's notices go, and stderr, where Colyseus logs a room's
+ *  exceptions and Vite its errors and warnings. */
+interface OwnedServer {
+  readonly child: ChildProcess;
+  said: string;
+  failed: string | null;
+  readonly streams: { readonly stdout: OutputStream; readonly stderr: OutputStream };
+}
+
+/** The most of a line kept before it ends (a progress line redrawn with `\r` never does). */
+const LINE_MOST = 4000;
+const owned = new Map<string, OwnedServer>();
+
+/** A chunk of one of a dev server's streams taken into its lines, whole lines only (`null`, the stream's end: the last
+ *  one too), terminal escapes left out. */
+function heardOutput(stream: OutputStream, chunk: Buffer | null): void {
+  const text = chunk === null ? stream.decoder.end() : stream.decoder.write(chunk);
+  const lines = stripVTControlCharacters(stream.partial + text).split(/\r?\n/);
+  stream.partial = chunk === null ? '' : (lines.pop() ?? '').slice(-LINE_MOST);
+  stream.lines.push(...lines.filter((line, at) => chunk !== null || at < lines.length - 1 || line !== ''));
+  const over = stream.lines.length - OUTPUT_KEPT;
+  if (over > 0) {
+    stream.lines.splice(0, over);
+    stream.dropped += over;
+  }
+}
+
+/** Where each of a dev server's streams has been read to; null, none asked of it (its end, a run's mark). */
+interface StreamsFrom { readonly stdout: number | null; readonly stderr: number | null }
+
+/** A stream's line as a query names it, or null where it names none. */
+const lineOf = (asked: string | null): number | null => (asked === null ? null : Number(asked) || 0);
+
+/** One stream's lines from line `from` on (none where `from` is null), and the line after them. */
+function streamFrom(stream: OutputStream, from: number | null): { readonly lines: readonly string[]; readonly next: number } {
+  const next = stream.dropped + stream.lines.length;
+  return { lines: from === null ? [] : stream.lines.slice(Math.max(0, from - stream.dropped)), next };
+}
+
+/** The session's dev server's two streams, each from its line in `from` on where `server` is its process, every line
+ *  of another server's, or none and where it ends (its line null: a run's mark); and the server. None where this
+ *  session didn't start the game's dev server (one already running is its own terminal's). */
+function outputFrom(root: string, server: number | null, from: StreamsFrom): {
+  readonly server: number | null;
+  readonly stdout: ReturnType<typeof streamFrom>;
+  readonly stderr: ReturnType<typeof streamFrom>;
+} {
+  const mine = owned.get(root);
+  const pid = mine?.child.pid ?? null;
+  if (!mine || pid === null) return { server: null, stdout: { lines: [], next: 0 }, stderr: { lines: [], next: 0 } };
+  const start = (line: number | null): number | null => (line === null ? null : server === pid ? line : 0);
+  return {
+    server: pid,
+    stdout: streamFrom(mine.streams.stdout, start(from.stdout)),
+    stderr: streamFrom(mine.streams.stderr, start(from.stderr)),
+  };
+}
+
+/** Ends the dev servers this session started, each `npm run dev` with everything it started. */
+function endOwned(): void {
+  for (const { child } of owned.values()) if (child.pid !== undefined && child.exitCode === null) signalProcessTree(child.pid, 'SIGTERM');
+  owned.clear();
+}
+
+/** The game's dev server, started where none runs, once it has written its record. */
+async function startedServer(root: string): Promise<RunningServer> {
+  const running = await runningServer(root);
+  if (running) return running;
+  let mine = owned.get(root);
+  if (!mine || mine.child.exitCode !== null || mine.failed !== null) {
+    const npm = npmProcess(['run', 'dev', '--', '--no-open'], root);
+    // (a group of its own on POSIX, so its whole tree ends with it: `signalProcessTree`)
+    const child = spawn(npm.program, npm.args, { cwd: root, detached: process.platform !== 'win32', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const stream = (): OutputStream => ({ lines: [], dropped: 0, partial: '', decoder: new StringDecoder('utf8') });
+    mine = { child, said: '', failed: null, streams: { stdout: stream(), stderr: stream() } };
+    const kept = mine;
+    const hear = (chunk: Buffer): void => { kept.said = (kept.said + chunk.toString('utf8')).slice(-4000); };
+    child.stdout?.on('data', hear);
+    child.stderr?.on('data', hear);
+    for (const name of ['stdout', 'stderr'] as const) {
+      child[name]?.on('data', (chunk: Buffer) => heardOutput(kept.streams[name], chunk));
+      child[name]?.on('end', () => heardOutput(kept.streams[name], null));
+    }
+    child.on('error', (error) => { kept.failed = error.message; });
+    owned.set(root, mine);
+  }
+  const bound = Date.now() + START_MS;
+  for (;;) {
+    const record = await runningServer(root);
+    if (record) return record;
+    if (mine.failed !== null) throw new Error(`The game's dev server (npm run dev) could not be started: ${mine.failed}`);
+    if (mine.child.exitCode !== null) throw new Error(`The game's dev server (npm run dev) ended with code ${mine.child.exitCode}:\n${mine.said.trim()}`);
+    if (Date.now() > bound) throw new Error(`The game's dev server (npm run dev) wrote no record in ${START_MS / 1000} s:\n${mine.said.trim()}`);
+    await new Promise((done) => setTimeout(done, LOOK_MS));
+  }
+}
+
+/** The dev server's newest run folder (`build/runs/<stamp>/`), where its pages' traces are; null before it has one. */
+async function newestRun(root: string): Promise<string | null> {
+  const runs = join(root, 'build', 'runs');
+  const newest = (await readdir(runs).catch(() => [])).sort().at(-1);
+  return newest === undefined ? null : join(runs, newest);
+}
+
+/** Each page of the newest run whose trace has begun, by its id: the slot its address named (its trace's first
+ *  line, std's `trace` head). */
+async function pageSlots(root: string): Promise<Record<string, string>> {
+  const run = await newestRun(root);
+  if (run === null) return {};
+  const slots: Record<string, string> = {};
+  for (const name of await readdir(run)) {
+    const page = name.replace(/\.jsonl$/, '');
+    if (page === name || !PAGE_ID.test(page)) continue;
+    const handle = await open(join(run, name), 'r');
+    try {
+      const buffer = Buffer.alloc(TRACE_HEAD_BYTES);
+      const { bytesRead } = await handle.read(buffer, 0, TRACE_HEAD_BYTES, 0);
+      const first = buffer.subarray(0, bytesRead).toString('utf8').split('\n')[0] ?? '';
+      if (!first.endsWith('}')) continue;
+      const head = JSON.parse(first) as { k?: unknown; slot?: unknown };
+      if (head.k === 'trace' && typeof head.slot === 'string') slots[page] = head.slot;
+    } finally {
+      await handle.close();
+    }
+  }
+  return slots;
+}
+
+/** The newest run's trace of the page `page`: its lines from byte `from`, whole lines only. */
+async function traceFrom(root: string, page: string, from: number): Promise<{ readonly lines: readonly string[]; readonly next: number }> {
+  const run = await newestRun(root);
+  if (run === null || !existsSync(join(run, `${page}.jsonl`))) return { lines: [], next: from };
+  const handle = await open(join(run, `${page}.jsonl`), 'r');
+  try {
+    const buffer = Buffer.alloc(TRACE_READ_BYTES);
+    const { bytesRead } = await handle.read(buffer, 0, TRACE_READ_BYTES, from);
+    const text = buffer.subarray(0, bytesRead).toString('utf8');
+    const end = text.lastIndexOf('\n') + 1;
+    return { lines: text.slice(0, end).split('\n').filter(Boolean), next: from + Buffer.byteLength(text.slice(0, end)) };
+  } finally {
+    await handle.close();
+  }
+}
+
+/** How long std's play of a goal may take before the route ends it: std's own goal limit is its bots'. */
+const PLAY_MS = 15 * 60_000;
+
+/**
+ * STD'S PLAY OF A GOAL (`/__std/play`, its WebSocket behind the dev server's token: the play asked, then `{ line }`
+ * messages, then `{ end: { ok } }`), its messages passed on as they come, one JSON line each.
+ */
+async function playGoal(root: string, body: unknown, response: ServerResponse): Promise<void> {
+  const asked = body as { goal?: unknown; bots?: unknown; device?: unknown } | undefined;
+  if (typeof asked?.goal !== 'string' || asked.goal === '' || (asked.bots !== undefined && !(Number.isInteger(asked.bots) && Number(asked.bots) >= 1))
+    || (asked.device !== undefined && (typeof asked.device !== 'string' || asked.device === '')))
+    return answer(response, 400, { error: `A play is { goal, bots?, device? }: a goal of the game's bot, a whole number of bots, and one of std's devices by its id; it was given ${JSON.stringify(body)}.` });
+  const running = await runningServer(root);
+  if (!running) return answer(response, 409, { error: "The game's dev server is not running: press Play." });
+  response.statusCode = 200;
+  response.setHeader('content-type', 'application/x-ndjson');
+  const said = (message: unknown): void => { response.write(`${JSON.stringify(message)}\n`); };
+  const socket = new WebSocket(`${running.url.replace(/^http/, 'ws').replace(/\/$/, '')}/__std/play?token=${running.token}`);
+  let ended = false;
+  const end = (ok: boolean, why?: string): void => {
+    if (ended) return;
+    ended = true;
+    clearTimeout(limit);
+    if (why !== undefined) said({ line: why });
+    said({ end: { ok } });
+    response.end();
+    if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) socket.close();
+  };
+  const limit = setTimeout(() => end(false, `Play ended std's play of ${asked.goal}: it ran ${PLAY_MS / 60_000} minutes.`), PLAY_MS);
+  socket.addEventListener('open', () => socket.send(JSON.stringify({ goal: asked.goal, bots: asked.bots ?? 1, device: asked.device ?? 'headless' })));
+  socket.addEventListener('message', (event) => {
+    const message = JSON.parse(String(event.data)) as { line?: unknown; end?: { ok?: unknown } };
+    if (message.end !== undefined) end(message.end.ok === true);
+    else said(message);
+  });
+  socket.addEventListener('error', () => end(false, "std's play could not be reached on the game's dev server."));
+  socket.addEventListener('close', () => end(false, "std's play closed before it said how it ended."));
+  response.on('close', () => { if (!ended) { ended = true; clearTimeout(limit); socket.close(); } });
+}
+
+/** A request's JSON body, as the editor's router parsed it before any serving plugin is reached. */
+const bodyOf = (request: IncomingMessage): unknown => (request as IncomingMessage & { body?: unknown }).body;
+
+function answer(response: ServerResponse, status: number, value: unknown): void {
+  response.statusCode = status;
+  response.setHeader('content-type', 'application/json');
+  response.end(JSON.stringify(value));
+}
+
+/** std's endpoint on the running dev server, its answer passed on as it came. */
+async function askStd(root: string, path: string, init?: RequestInit): Promise<{ readonly status: number; readonly body: unknown }> {
+  const running = await runningServer(root);
+  if (!running) return { status: 409, body: { error: "The game's dev server is not running: press Play." } };
+  const at = new URL(path, running.url);
+  at.searchParams.set('token', running.token);
+  const response = await fetch(at, init);
+  return { status: response.status, body: await response.json() };
+}
+
+export function stdDevPlugin(services: Pick<ProjectServingServices, 'currentProjectRoot' | 'requireLocalOwner'>): Plugin {
+  return {
+    name: 'volter-play-std-dev',
+    configureServer(server) {
+      server.httpServer?.once('close', endOwned);
+      process.once('exit', endOwned);
+      server.httpServer?.once('close', endExports);
+      process.once('exit', endExports);
+      server.middlewares.use(STD_ROUTE, (request, response, next) => {
+        const root = services.currentProjectRoot();
+        if (!root) return next();
+        // (owner-local: it starts the game's dev server and speaks to its pages with the server's token)
+        if (!services.requireLocalOwner(request, response)) return;
+        const url = new URL(request.url ?? '/', 'http://session');
+        // (a captured frame is the one answer that is not JSON: the PNG itself)
+        const captured = url.pathname === '/capture' && request.method === 'GET' ? url.searchParams.get('file') ?? '' : null;
+        if (captured !== null) {
+          void newestRun(root).then(async (run) => {
+            if (run === null || !CAPTURE_FILE.test(captured) || !existsSync(join(run, captured)))
+              return answer(response, 404, { error: `No captured frame ${JSON.stringify(captured)} in the dev server's newest run.` });
+            response.statusCode = 200;
+            response.setHeader('content-type', 'image/png');
+            response.end(await readFile(join(run, captured)));
+          }).catch((error: unknown) => answer(response, 500, { error: error instanceof Error ? error.message : String(error) }));
+          return;
+        }
+        if (url.pathname === '/export' && request.method === 'POST') {
+          void exportGame(root, bodyOf(request), response).catch((error: unknown) => {
+            if (!response.headersSent) answer(response, 500, { error: error instanceof Error ? error.message : String(error) });
+            else response.end();
+          });
+          return;
+        }
+        if (url.pathname === '/play' && request.method === 'POST') {
+          void playGoal(root, bodyOf(request), response).catch((error: unknown) => {
+            if (!response.headersSent) answer(response, 500, { error: error instanceof Error ? error.message : String(error) });
+            else response.end();
+          });
+          return;
+        }
+        const control = /^\/devices\/([^/]+)\/control$/.exec(url.pathname)?.[1];
+        const asked: Promise<{ readonly status: number; readonly body: unknown }> =
+          url.pathname === '/' && request.method === 'GET' ? Promise.resolve({ status: 200, body: stdGame(root) })
+          : url.pathname === '/start' && request.method === 'POST' ? startedServer(root).then(({ url: at }) => ({ status: 200, body: { url: at } }))
+          : url.pathname === '/devices' && request.method === 'GET' ? askStd(root, '/__std/devices')
+          // (the game's running scene, read where it runs: the level document draws the playing world from it)
+          : url.pathname === '/scene' && request.method === 'GET' ? askStd(root, `/__std/scene${url.search}`)
+          : control !== undefined && request.method === 'POST'
+            ? askStd(root, `/__std/devices/${encodeURIComponent(decodeURIComponent(control))}/control`,
+              { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(bodyOf(request)) })
+          : url.pathname === '/level' && (request.method === 'GET' || request.method === 'POST')
+            ? levelAnswer(root, request.method, bodyOf(request))
+          : url.pathname === '/goals' && request.method === 'GET' ? botGoals(root)
+          : url.pathname === '/pages' && request.method === 'GET' ? pageSlots(root).then((body) => ({ status: 200, body }))
+          : url.pathname === '/trace' && request.method === 'GET' && PAGE_ID.test(url.searchParams.get('page') ?? '')
+            ? traceFrom(root, url.searchParams.get('page')!, Number(url.searchParams.get('from') ?? 0)).then((body) => ({ status: 200, body }))
+          : url.pathname === '/output' && request.method === 'GET'
+            ? Promise.resolve({ status: 200, body: outputFrom(root,
+              url.searchParams.has('server') ? Number(url.searchParams.get('server')) : null,
+              { stdout: lineOf(url.searchParams.get('stdout')), stderr: lineOf(url.searchParams.get('stderr')) }) })
+          : Promise.resolve({ status: 404, body: { error: `${STD_ROUTE}${url.pathname} is not a route of Play's` } });
+        asked.then(({ status, body }) => answer(response, status, body),
+          (error: unknown) => answer(response, 500, { error: error instanceof Error ? error.message : String(error) }));
+      });
+    },
+  };
+}