@volter/play 0.5.211 → 0.5.212

package/serving/std-dev.ts

@@ -0,0 +1,514 @@
+/**
+ * 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` and `POST /__editor/play/std/devices/<id>/control` — std's own endpoints
+ *   (`/__std/devices`, `/__std/devices/<id>/control`), 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 <glb> --description <its
+ *   .level.json>` in the game's folder, 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? }` — std's own play of the game's bots to the goal's end
+ *   (`/__std/play`, std-dev's std-endpoints.ts) on the 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 } }`. Its pages are std's, headless, so it
+ *   plays whether or not the editor is seen.
+ * - `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/errors?server=<pid>&from=<line>` — `{ lines, next, server }`: the error output (stderr) of
+ *   the dev server this session started, from a line on (every line, where `server` names another), or with no `from`
+ *   none and where it ends: the room's own exceptions are Colyseus's to log there, never 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', glb, '--description', glb.replace(/\.glb$/, '.level.json')], { 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 a dev server's error output kept, in lines. */
+const ERRORS_KEPT = 500;
+
+/** The dev servers this session started, by project, with the last of what each said, why its launch failed, and its
+ *  error output (stderr, where Colyseus logs a room's exceptions and Vite its errors and warnings) as lines, the first
+ *  kept one being line `dropped`. */
+interface OwnedServer {
+  readonly child: ChildProcess;
+  said: string;
+  failed: string | null;
+  readonly errors: string[];
+  dropped: number;
+  partial: string;
+  readonly decoder: StringDecoder;
+}
+
+/** 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 a dev server's stderr taken into its lines, whole lines only (`null`, its output's end: the last one
+ *  too), terminal escapes left out. */
+function heardError(server: OwnedServer, chunk: Buffer | null): void {
+  const text = chunk === null ? server.decoder.end() : server.decoder.write(chunk);
+  const lines = stripVTControlCharacters(server.partial + text).split(/\r?\n/);
+  server.partial = chunk === null ? '' : (lines.pop() ?? '').slice(-LINE_MOST);
+  server.errors.push(...lines.filter((line, at) => chunk !== null || at < lines.length - 1 || line !== ''));
+  const over = server.errors.length - ERRORS_KEPT;
+  if (over > 0) {
+    server.errors.splice(0, over);
+    server.dropped += over;
+  }
+}
+
+/** The session's dev server's error output from line `from` of the server `server` (its process) on, every line of
+ *  another server's, or none and where it ends (`from` null: a run's mark); and the server and the line after them.
+ *  None where this session didn't start the game's dev server (one already running is its own terminal's). */
+function errorsFrom(root: string, server: number | null, from: number | null): {
+  readonly lines: readonly string[]; readonly next: number; readonly server: number | null;
+} {
+  const mine = owned.get(root);
+  const pid = mine?.child.pid ?? null;
+  if (!mine || pid === null) return { lines: [], next: 0, server: null };
+  const next = mine.dropped + mine.errors.length;
+  if (from === null) return { lines: [], next, server: pid };
+  const start = server === pid ? from : 0;
+  return { lines: mine.errors.slice(Math.max(0, start - mine.dropped)), next, server: pid };
+}
+
+/** 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'] });
+    mine = { child, said: '', failed: null, errors: [], dropped: 0, partial: '', decoder: new StringDecoder('utf8') };
+    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);
+    child.stderr?.on('data', (chunk: Buffer) => heardError(kept, chunk));
+    child.stderr?.on('end', () => heardError(kept, 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 } | undefined;
+  if (typeof asked?.goal !== 'string' || asked.goal === '' || (asked.bots !== undefined && !(Number.isInteger(asked.bots) && Number(asked.bots) >= 1)))
+    return answer(response, 400, { error: `A play is { goal, bots? }: a goal of the game's bot, and a whole number of bots; 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: '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 response = await fetch(`${running.url}${path}?token=${running.token}`, 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')
+          : 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 === '/errors' && request.method === 'GET'
+            ? Promise.resolve({ status: 200, body: errorsFrom(root,
+              url.searchParams.has('server') ? Number(url.searchParams.get('server')) : null,
+              url.searchParams.has('from') ? Number(url.searchParams.get('from')) || 0 : null) })
+          : 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) }));
+      });
+    },
+  };
+}

package/serving/std-scene-runtime.js

@@ -0,0 +1,119 @@
+/**
+ * THE SCENE VIEW'S RUNTIME, served from the std game's own module graph (`./std-scene.ts`, the id
+ * `\0volter-std-scene-runtime`): its imports resolve as the game's, so the fiber root, react-three-rapier and std's
+ * effects are the game's own instances, the very ones the level's components use. A level's module (`./std-scene.ts`'s
+ * `sceneModule`) names its files and hands them here. It is a browser module, not part of play's page bundle, because
+ * play's page carries none of the game's libraries.
+ */
+import { Component, createElement as h } from 'react';
+import * as THREE from 'three';
+import { advance, createPortal, createRoot, extend, useFrame } from '@react-three/fiber';
+import { Physics } from '@react-three/rapier';
+import { EffectPass, LUT3DEffect } from 'postprocessing';
+import { LUTCubeLoader } from 'three/addons/loaders/LUTCubeLoader.js';
+import { ViewShaperEffect } from '@volter-ai/std/level/client';
+
+// (a root made by createRoot knows no three.js element until it is told, as <Canvas> tells its own)
+extend(THREE);
+
+/**
+ * THE TREES' LOADS STAY THE GAME'S. The level's components load through fiber's `useLoader`, whose loaders and cache are
+ * fiber's own, shared by every fiber root on the page; nothing here changes them. A file the level's modules import by
+ * URL (`?url`: the glb, the sky, the terrain) carries the game's content version (`./std-scene.ts`), so a new version
+ * is a new URL and a new cache entry. A URL the game's code passes as a plain string, and a glTF's external files, keep
+ * their URL: they show a change on a page reload (`docs/adr/std-scene-view.md`, decision 5).
+ */
+
+/** A frame subscriber of priority 1 takes the render over from fiber, so the stage's own draw is the only one. */
+function StageDraws() {
+  useFrame(() => {}, 1);
+  return null;
+}
+
+/** What the level throws as it renders or loads, the view's to show. */
+class Failed extends Component {
+  state = { error: null };
+  static getDerivedStateFromError(error) { return { error }; }
+  componentDidCatch(error) { this.props.onError(error); }
+  render() { return this.state.error === null ? this.props.children : null; }
+}
+
+/**
+ * The stage's renderer as fiber holds it. Fiber's unmount releases a renderer it was given (9.8.2's `releaseRenderer`:
+ * for a renderer it did not make, it still calls `forceContextLoss`); the stage's renderer and its context are the
+ * stage's, so fiber holds it through this view, whose `forceContextLoss` and `dispose` leave it to the stage. Every
+ * other member is the renderer's own.
+ */
+function lent(renderer) {
+  return new Proxy(renderer, {
+    get(target, key) {
+      if (key === 'forceContextLoss' || key === 'dispose') return () => {};
+      const value = Reflect.get(target, key, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+    set: (target, key, value) => Reflect.set(target, key, value, target),
+  });
+}
+
+/**
+ * A fiber root for `level` on the stage's renderer and camera, its children portalled into the document: the level's
+ * environment into `world`, the document's own scene, whose sky, environment light and fog the stage draws by, and
+ * `<Physics paused debug={overlays}><Level /></Physics>` into `root`. Fiber keeps a scene of its own, as its unmount
+ * disposes what that scene holds. It draws nothing until `draw` is asked; `advance` runs a frame of the level's own
+ * `useFrame`s (the stage draws the picture); `unmount` ends it.
+ */
+export async function mountScene(level, { renderer, world, camera, root, onError }) {
+  const { Level, Environment, canvas } = level;
+  const fiber = createRoot(renderer.domElement);
+  const size = renderer.getSize(new THREE.Vector2());
+  const { width, height } = renderer.domElement.style;
+  try {
+    await fiber.configure({ gl: lent(renderer), camera, frameloop: 'never', shadows: canvas.shadows ?? false, flat: true,
+      dpr: renderer.getPixelRatio(), size: { width: size.x, height: size.y, top: 0, left: 0 } });
+  } catch (error) {
+    fiber.unmount();
+    throw error;
+  }
+  // (fiber sizes the canvas's style in pixels; the stage sizes it by its box)
+  Object.assign(renderer.domElement.style, { width, height });
+  let store = null;
+  const draw = (shown) => {
+    store = fiber.render(h(Failed, { onError }, h(StageDraws),
+      Environment === null ? null : createPortal(h(Environment), world),
+      createPortal(h(Physics, { paused: true, debug: shown }, h(Level)), root)));
+  };
+  return {
+    draw,
+    // (this root's frame alone: another view's level is its own root)
+    advance: (seconds) => { if (store !== null) advance(seconds, true, store.getState()); },
+    unmount: () => { fiber.unmount(); },
+  };
+}
+
+/**
+ * A level's view transform as the stage's display transform: std's `ViewShaperEffect`, then postprocessing's
+ * `LUT3DEffect` on the LUT std baked, read by three's `LUTCubeLoader` as std reads it. Its `dispose` frees the pass, its
+ * effects and the LUT.
+ */
+export async function viewTransform({ lut: url, min, max, exposure }) {
+  const lut = (await new LUTCubeLoader().loadAsync(url)).texture3D;
+  const shaper = new ViewShaperEffect(min, max, exposure);
+  const look = new LUT3DEffect(lut, { tetrahedralInterpolation: true });
+  look.inputColorSpace = THREE.LinearSRGBColorSpace;
+  const pass = new EffectPass(new THREE.PerspectiveCamera(), shaper, look);
+  let initialized = false;
+  return {
+    render(renderer, input, output) {
+      if (!initialized) {
+        pass.initialize(renderer, false, THREE.HalfFloatType);
+        initialized = true;
+      }
+      pass.renderToScreen = output === null;
+      pass.render(renderer, input, output, 0, false);
+    },
+    dispose() {
+      pass.dispose();
+      lut.dispose();
+    },
+  };
+}