@moku-labs/game 0.0.2 → 0.0.3

package/dist/testing.mjs

@@ -1,5 +1,9 @@
 import { n as saveOf, t as memory } from "./memory-CvgdnsQO.mjs";
-import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-CvamCUcR.mjs";
+import { a as stepFrames, i as runRepro, n as commands, r as createHeadless, t as run } from "./run-tlcn1w7y.mjs";
+import { n as read, t as sources } from "./sources-BooL2MsX.mjs";
+import { createBrandConsole } from "@moku-labs/common/cli";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 //#region src/plugins/clock/fake.ts
 /**
 * Removes and returns the timer that is due first, up to and including `until`.
@@ -86,4 +90,2054 @@ function fakeClock(start = 0) {
 	};
 }
 //#endregion
-export { createHeadless, fakeClock, memory, runRepro, saveOf, stepFrames };
+//#region src/visual/steps.ts
+/**
+* @file visual — the steps of a visual test: each one is checked at definition and run through
+* the `/control` catalogue, by its short name, with `run`, so the dev guard, the journal of a
+* cheat and the envelope are the ones an editor gets. The step names come from the catalogue: a
+* command it gains is a step with no change here.
+*/
+/** The catalogue seen as step runners. */
+const stepCommands = commands;
+/**
+* Tells the three commands of the catalogue that are not steps: `bookmark` only reads, `capture`
+* is what the runner does by itself, and `debug` drawing would enter a baseline.
+*
+* @param name - A short name of the catalogue.
+* @returns True for `bookmark`, `capture` and `debug`.
+* @example
+* ```ts
+* isLeftOut("capture"); // true
+* ```
+*/
+function isLeftOut(name) {
+	return name === "bookmark" || name === "capture" || name === "debug";
+}
+/**
+* Tells whether a name is a step command: in the catalogue and not one of the three left out.
+*
+* @param name - The key of a step.
+* @returns True for `answer`, `tap`, `walk` and the other step commands.
+* @example
+* ```ts
+* isStepCommand("tap"); // true
+* isStepCommand("capture"); // false
+* ```
+*/
+function isStepCommand(name) {
+	return Object.hasOwn(commands, name) && !isLeftOut(name);
+}
+/**
+* Tells whether the value of a command step is an input object.
+*
+* @param value - The value under the command's name.
+* @returns True for an object that is neither `null` nor an array.
+* @example
+* ```ts
+* isInputObject({ key: "play" }); // true
+* ```
+*/
+function isInputObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Names the step commands, for a message: the catalogue's order minus the three left out.
+*
+* @returns `answer, tap, drag, ...`.
+*/
+function stepNames() {
+	return Object.keys(commands).filter((name) => isStepCommand(name)).join(", ");
+}
+/**
+* Takes one step apart and checks its shape: exactly one key, either `checkpoint` or a step
+* command with an input object. The checkpoint name is checked by the caller.
+*
+* @param test - The test name, for the message.
+* @param step - The step.
+* @param index - Its index in the steps, from 0.
+* @returns The checkpoint or the command with its input.
+* @throws {Error} When the step holds no key or more than one, names something that is not a
+*   step, gives a command no input object, or a checkpoint no string.
+* @example
+* ```ts
+* stepEntry("reward-popup", { tap: { key: "play" } }, 0); // { kind: "command", name: "tap", input: { key: "play" } }
+* ```
+*/
+function stepEntry(test, step, index) {
+	const fields = step;
+	const [name, ...others] = Object.keys(fields);
+	const at = `[game] Visual test "${test}", step ${index + 1}`;
+	if (name === void 0 || others.length > 0) throw new Error(`${at} is not one command.\n  Write one command by its short name, or { checkpoint: "name" }.`);
+	const value = fields[name];
+	if (name === "checkpoint") {
+		if (typeof value === "string") return {
+			kind: "checkpoint",
+			name: value
+		};
+		throw new Error(`${at}: the checkpoint name is not a string.\n  Write the checkpoint as { checkpoint: "name" }.`);
+	}
+	if (!isStepCommand(name)) throw new Error(`${at} names "${name}", which is not a step.\n  Use a checkpoint or one of: ${stepNames()}.`);
+	if (!isInputObject(value)) throw new Error(`${at} (${name}) has no input object.\n  Pass the input of the command, like { tap: { key: "play" } }.`);
+	return {
+		kind: "command",
+		name,
+		input: value
+	};
+}
+/**
+* Runs a command step through `run`, the way an editor does.
+*
+* @param app - The running app.
+* @param name - The short name of the command.
+* @param input - Its input.
+* @returns What `run` resolves with.
+* @throws {Error} Whatever the command throws.
+*/
+function runStep(app, name, input) {
+	return run(app, stepCommands[name], input);
+}
+//#endregion
+//#region src/visual/define.ts
+/**
+* @file visual — `defineVisualTest`: a name, where the test starts and its steps, checked and
+* frozen. Nothing runs at definition.
+*/
+/** A file name: lowercase letters and digits, words joined by single dashes. */
+const fileName = /^[\da-z]+(?:-[\da-z]+)*$/u;
+/** The second line of every file name message. */
+const FILE_NAME_RULE = "Use lowercase letters, digits and dashes.";
+/**
+* Freezes a value and everything it holds.
+*
+* @param value - A copy nobody else holds.
+* @returns The same value, frozen all the way down.
+* @example
+* ```ts
+* Object.isFrozen(freezeDeep({ steps: [{ checkpoint: "open" }] }).steps[0]); // true
+* ```
+*/
+function freezeDeep(value) {
+	if (typeof value === "object" && value !== null) {
+		for (const child of Object.values(value)) freezeDeep(child);
+		Object.freeze(value);
+	}
+	return value;
+}
+/**
+* Checks the steps: each holds one command or one checkpoint, and every checkpoint name is a
+* file name used once in the test.
+*
+* @param test - The test name.
+* @param steps - The steps.
+* @throws {Error} When a step is not one command, or a checkpoint name is not a file name or
+*   is used twice.
+*/
+function checkSteps(test, steps) {
+	const checkpoints = [];
+	for (const [index, step] of steps.entries()) {
+		const entry = stepEntry(test, step, index);
+		if (entry.kind === "command") continue;
+		const at = `[game] Visual test "${test}", step ${index + 1}`;
+		if (!fileName.test(entry.name)) throw new Error(`${at}: the checkpoint name "${entry.name}" is not a file name.\n  ${FILE_NAME_RULE}`);
+		if (checkpoints.includes(entry.name)) throw new Error(`${at}: the checkpoint "${entry.name}" is already a step.\n  Give every checkpoint of a test its own name.`);
+		checkpoints.push(entry.name);
+	}
+}
+/**
+* Checks a visual test: its name and its checkpoint names are file names, no checkpoint name is
+* used twice, and every step is one step command. `defineVisualTest` checks at definition, and
+* the runner checks again, so a descriptor written by hand cannot reach outside its folder.
+*
+* @param name - The test name.
+* @param steps - The steps.
+* @throws {Error} When a name is not a file name, a checkpoint name is used twice, or a step is
+*   not one step command.
+*/
+function checkVisualTest(name, steps) {
+	if (!fileName.test(name)) throw new Error(`[game] The visual test name "${name}" is not a file name.\n  ${FILE_NAME_RULE}`);
+	checkSteps(name, steps);
+}
+/**
+* Defines a visual test: where it starts, what `game.restore` loads, and its steps. A step is a
+* `/control` command by its short name with that command's input, or `{ checkpoint: name }`,
+* where the runner saves `state.json` and `describe.json` next to the test. `walk` runs fast: a
+* popup its last node opens never mounts, so the step before a checkpoint that shows a node's
+* result is `answer` or `tap`. The answer is a frozen copy; nothing runs here.
+*
+* @param name - The test name, also its folder: lowercase letters, digits and dashes.
+* @param test - Where it starts and its steps.
+* @param test.start - The player, and optionally the session, the rng and the checkpoint.
+* @param test.steps - The commands and the checkpoints, in order.
+* @returns The test, frozen.
+* @throws {Error} When the name or a checkpoint name is not a file name, a checkpoint name is
+*   used twice, or a step is not one step command.
+* @example
+* ```ts
+* // tests/visual/reward-popup.visual.ts: Play, deliver the first order, claim the reward.
+* export const rewardPopup = defineVisualTest("reward-popup", {
+*   start: { player: fixtures.ready, checkpoint: "home" },
+*   steps: [{ tap: { key: "play" } }, { answer: { intent: "deliver", payload: { orderId: "o1" } } },
+*     { checkpoint: "open" }, { tap: { key: "claim" } }, { checkpoint: "claimed" }]
+* });
+* ```
+*/
+function defineVisualTest(name, test) {
+	checkVisualTest(name, test.steps);
+	return freezeDeep(structuredClone({
+		name,
+		start: test.start,
+		steps: test.steps
+	}));
+}
+//#endregion
+//#region src/visual/compare.ts
+/** The path `compareJson` names when the two values differ at the top. */
+const ROOT = "(root)";
+/** A key that can follow a dot in a path: an identifier. */
+const identifier = /^[A-Za-z_$][\w$]*$/u;
+/**
+* Tells a JSON object from the other JSON values.
+*
+* @param value - A JSON value.
+* @returns True for an object that is neither `null` nor an array.
+* @example
+* ```ts
+* isJsonObject({ coins: 3 }); // true
+* ```
+*/
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Adds a key to a path: after a dot when it is an identifier, in brackets otherwise.
+*
+* @param path - The path so far, empty at the top.
+* @param key - The key.
+* @returns The longer path.
+* @example
+* ```ts
+* keyPath("views", "board.items"); // 'views["board.items"]'
+* ```
+*/
+function keyPath(path, key) {
+	if (!identifier.test(key)) return `${path}[${JSON.stringify(key)}]`;
+	return path === "" ? key : `${path}.${key}`;
+}
+/**
+* Finds the first difference of two arrays, element by element: past the shorter array, the
+* missing element is the difference.
+*
+* @param expected - The array of the baseline.
+* @param actual - The array read now.
+* @param path - The path of the two arrays.
+* @returns The path of the first difference, or `undefined` when they are equal.
+*/
+function compareArrays(expected, actual, path) {
+	const length = Math.max(expected.length, actual.length);
+	for (let index = 0; index < length; index += 1) {
+		const found = compareAt(expected[index], actual[index], `${path}[${index}]`);
+		if (found !== void 0) return found;
+	}
+}
+/**
+* Finds the first difference of two objects, key by key in sorted order: a key only one side
+* has, or a value that differs.
+*
+* @param expected - The object of the baseline.
+* @param actual - The object read now.
+* @param path - The path of the two objects.
+* @returns The path of the first difference, or `undefined` when they are equal.
+*/
+function compareObjects(expected, actual, path) {
+	const keys = [.../* @__PURE__ */ new Set([...Object.keys(expected), ...Object.keys(actual)])].toSorted();
+	for (const key of keys) {
+		const found = compareAt(expected[key], actual[key], keyPath(path, key));
+		if (found !== void 0) return found;
+	}
+}
+/**
+* Finds the first difference of two JSON values at a path. `undefined` stands for a key or an
+* element only the other side has.
+*
+* @param expected - The value of the baseline.
+* @param actual - The value read now.
+* @param path - The path of the two values, empty at the top.
+* @returns The path of the first difference, or `undefined` when they are equal.
+*/
+function compareAt(expected, actual, path) {
+	const here = path === "" ? ROOT : path;
+	if (expected === void 0 || actual === void 0) return here;
+	if (Array.isArray(expected) || Array.isArray(actual)) {
+		if (!Array.isArray(expected) || !Array.isArray(actual)) return here;
+		return compareArrays(expected, actual, path);
+	}
+	if (isJsonObject(expected) || isJsonObject(actual)) {
+		if (!isJsonObject(expected) || !isJsonObject(actual)) return here;
+		return compareObjects(expected, actual, path);
+	}
+	return expected === actual ? void 0 : here;
+}
+/**
+* Compares two JSON values exactly and names the first difference: keys in sorted order, the
+* way the baseline file lists them, and array elements in order. A key only one side has, a
+* changed type and a changed value are each a difference.
+*
+* @param expected - The value of the baseline.
+* @param actual - The value read now.
+* @returns The JSON path of the first difference, `"(root)"` for the top, or `undefined` when
+*   the two are equal.
+* @example
+* ```ts
+* compareJson({ ui: { children: [{ rect: { y: 1 } }] } }, { ui: { children: [{ rect: { y: 2 } }] } });
+* // "ui.children[0].rect.y"
+* ```
+*/
+function compareJson(expected, actual) {
+	return compareAt(expected, actual, "");
+}
+/**
+* Rebuilds a value with the keys of every object in sorted order, so `JSON.stringify` writes
+* them sorted.
+*
+* @param value - The value to write.
+* @returns The same value with sorted objects.
+* @example
+* ```ts
+* Object.keys(sortKeys({ b: 1, a: 2 }) as object); // ["a", "b"]
+* ```
+*/
+function sortKeys(value) {
+	if (Array.isArray(value)) return value.map((item) => sortKeys(item));
+	if (typeof value !== "object" || value === null) return value;
+	const entries = Object.entries(value).toSorted(([left], [right]) => left < right ? -1 : 1);
+	return Object.fromEntries(entries.map(([key, item]) => [key, sortKeys(item)]));
+}
+/**
+* Writes a value as the text of a baseline file: JSON with sorted keys, a two-space indent and
+* a final newline. A field that is `undefined` is left out, as `JSON.stringify` does.
+*
+* @param value - What a reader answered: plain data.
+* @returns The text.
+* @example
+* ```ts
+* stableJson({ b: 1, a: true }); // '{\n  "a": true,\n  "b": 1\n}\n'
+* ```
+*/
+function stableJson(value) {
+	return `${JSON.stringify(sortKeys(value), void 0, 2)}\n`;
+}
+/**
+* Reads the text of a baseline file as JSON.
+*
+* @param text - The text.
+* @param file - The file it came from, for the message.
+* @returns The JSON value.
+* @throws {Error} When the text is not JSON, say a merge conflict left markers in it.
+* @example
+* ```ts
+* parseJson('{ "path": "home" }', "tests/visual/home/rest/state.json"); // { path: "home" }
+* ```
+*/
+function parseJson(text, file) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new Error(`[game] The baseline "${file}" is not JSON.\n  Fix the file, or write it again with --update.`);
+	}
+}
+//#endregion
+//#region src/visual/files.ts
+/**
+* @file visual — the baseline files next to the tests: `<dir>/<test>/<checkpoint>/state.json`,
+* `describe.json` and `screen.webp`, with `screen.actual.webp` and `screen.diff.webp` beside them
+* on a pixel difference. The pictures are lossless WebP, encoded in the page. The only module of
+* the runner that touches the disk, so `node:fs/promises` and `node:path` are imported here and
+* nowhere else; the `./testing` entry is node and bun only.
+*/
+/**
+* Names a baseline file of a checkpoint.
+*
+* @param dir - The folder of the visual tests, `"tests/visual"` by default.
+* @param test - The test name.
+* @param checkpoint - The checkpoint name.
+* @param file - The file name, such as `"state.json"`.
+* @returns The path.
+* @example
+* ```ts
+* baselineFile("tests/visual", "reward-popup", "open", "state.json"); // "tests/visual/reward-popup/open/state.json"
+* ```
+*/
+function baselineFile(dir, test, checkpoint, file) {
+	return path.join(dir, test, checkpoint, file);
+}
+/** What every picture of the leg starts with: the page encodes the capture as lossless WebP. */
+const WEBP_URL = "data:image/webp;base64,";
+/**
+* Tells a missing file from the other errors of a read.
+*
+* @param error - What the read threw.
+* @returns True when the file does not exist.
+*/
+function isMissing(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+/**
+* Reads a baseline file as bytes.
+*
+* @param file - The path.
+* @returns Its bytes, or `undefined` when there is no such file.
+* @throws {Error} Any read error other than a missing file.
+*/
+async function readBytes(file) {
+	try {
+		return await readFile(file);
+	} catch (error) {
+		if (isMissing(error)) return void 0;
+		throw error;
+	}
+}
+/**
+* Writes a baseline file, its folders included.
+*
+* @param file - The path.
+* @param data - The text or the bytes.
+*/
+async function writeBaseline(file, data) {
+	await mkdir(path.dirname(file), { recursive: true });
+	await writeFile(file, data);
+}
+/**
+* Compares the text of a baseline file with what a checkpoint read, as JSON.
+*
+* @param file - The path of the baseline, for the message.
+* @param baseline - The text of the file.
+* @param text - What the checkpoint read, as `stableJson` wrote it.
+* @returns `"same"`, or `"different"` with the path of the first difference.
+* @throws {Error} When the baseline is not JSON.
+*/
+function compareText(file, baseline, text) {
+	const first = compareJson(parseJson(baseline, file), parseJson(text, file));
+	return first === void 0 ? { outcome: "same" } : {
+		outcome: "different",
+		first
+	};
+}
+/**
+* Compares what a checkpoint read with its baseline file. A missing file is written and
+* answered `"written"`, never a failure; `update` rewrites the file whatever it holds. A
+* difference leaves the baseline as it is.
+*
+* @param file - The path of the baseline.
+* @param text - What the checkpoint read, as `stableJson` wrote it.
+* @param update - Whether to rewrite the baseline.
+* @returns The outcome, and the path of the first difference for `"different"`.
+* @throws {Error} When the baseline is not JSON, or the disk refused.
+*/
+async function checkBaseline(file, text, update) {
+	const baseline = update ? void 0 : await readBytes(file);
+	if (baseline === void 0) {
+		await writeBaseline(file, text);
+		return { outcome: "written" };
+	}
+	return compareText(file, baseline.toString("utf8"), text);
+}
+/**
+* Compares what the page read with a baseline file the headless leg owns, and never writes it.
+* The browser leg checks `state.json` this way.
+*
+* @param file - The path of the baseline.
+* @param text - What the page read, as `stableJson` wrote it.
+* @returns The outcome, or `undefined` when there is no baseline to compare with.
+* @throws {Error} When the baseline is not JSON, or the disk refused.
+*/
+async function compareBaseline(file, text) {
+	const baseline = await readBytes(file);
+	return baseline === void 0 ? void 0 : compareText(file, baseline.toString("utf8"), text);
+}
+/**
+* Reads a picture of a checkpoint, such as `screen.webp`, the way the page hands one over: a
+* WebP data URL.
+*
+* @param file - The path.
+* @returns The data URL, or `undefined` when there is no such file.
+* @throws {Error} Any read error other than a missing file.
+*/
+async function readScreen(file) {
+	const bytes = await readBytes(file);
+	return bytes === void 0 ? void 0 : `${WEBP_URL}${bytes.toString("base64")}`;
+}
+/**
+* Writes a picture of a checkpoint: the bytes of the lossless WebP data URL the page encoded, its
+* folders included.
+*
+* @param file - The path: `screen.webp`, `screen.actual.webp` or `screen.diff.webp`.
+* @param url - The WebP data URL.
+* @throws {Error} When the URL is not a WebP data URL, or the disk refused.
+*/
+async function writeScreen(file, url) {
+	if (!url.startsWith(WEBP_URL)) throw new Error("[game] The page gave a picture that is not a WebP data URL.\n  Run the pixel leg in Chrome: the baselines are lossless WebP.");
+	await writeBaseline(file, Buffer.from(url.slice(23), "base64"));
+}
+//#endregion
+//#region src/visual/capture.ts
+/**
+* @file visual — the two readers of a checkpoint. Both read through the `/inspect` sources only,
+* never a plugin internal: `stateOf` the graph position and the committed model, `describeOf`
+* the ui tree and the keyed views. Entity ids and skipped components (the renderer's `Display`)
+* are dropped and a `Parent` names its entity by address, so the entity numbering never enters a
+* baseline.
+*/
+/**
+* Orders two views by projection, then by key, in code unit order.
+*
+* @param left - One view.
+* @param right - The other view.
+* @returns A negative number when `left` comes first, a positive one otherwise.
+* @example
+* ```ts
+* byAddress({ projection: "hud", key: "a" }, { projection: "board", key: "z" }); // 1
+* ```
+*/
+function byAddress(left, right) {
+	if (left.projection !== right.projection) return left.projection < right.projection ? -1 : 1;
+	return left.key < right.key ? -1 : 1;
+}
+/**
+* Turns the projection keys of the world into a lookup from entity to address.
+*
+* @param keys - What the projections source reads: projection, key, entity.
+* @returns The address of every keyed entity.
+*/
+function addressesOf(keys) {
+	const addresses = /* @__PURE__ */ new Map();
+	for (const [projection, byKey] of Object.entries(keys)) for (const [key, entity] of Object.entries(byKey)) addresses.set(entity, {
+		projection,
+		key
+	});
+	return addresses;
+}
+/**
+* Reads the entity a `Parent` component points at.
+*
+* @param parent - The JSON of the component, if the view has one.
+* @returns The parent entity, or `undefined` when there is no `Parent` of the usual shape.
+* @example
+* ```ts
+* parentOf({ entity: 1048614 }); // 1048614
+* ```
+*/
+function parentOf(parent) {
+	if (typeof parent !== "object" || parent === null || Array.isArray(parent)) return void 0;
+	return typeof parent.entity === "number" ? parent.entity : void 0;
+}
+/**
+* Names the parent of a view by its projection and key instead of its entity id, which depends
+* on the order the world spawned and freed its entities. A parent no projection names is `{}`.
+*
+* @param components - The JSON components of the view.
+* @param addresses - The address of every keyed entity.
+* @returns The components, with `Parent` as an address.
+*/
+function withParentAddress(components, addresses) {
+	const parent = parentOf(components.Parent);
+	if (parent === void 0) return components;
+	const address = addresses.get(parent);
+	return {
+		...components,
+		Parent: address === void 0 ? {} : { ...address }
+	};
+}
+/**
+* Reads the state a checkpoint saves: where the graph rests, then the committed player,
+* session and rng.
+*
+* @param app - The running app.
+* @returns `{ path, player, session, rng }`.
+*/
+function stateOf(app) {
+	return {
+		path: read(app, sources.position).path,
+		...read(app, sources.model)
+	};
+}
+/**
+* Reads the screen a checkpoint saves: the ui tree, and every entity a projection names as
+* `{ projection, key, components }`, sorted by projection then key. Ui parts, rings and unkeyed
+* views appear through the tree only, or not at all.
+*
+* @param app - The running app.
+* @returns `{ ui, views }`.
+*/
+function describeOf(app) {
+	const addresses = addressesOf(read(app, sources.projections));
+	const views = [];
+	for (const entity of read(app, sources.entities)) {
+		const address = addresses.get(entity.id);
+		if (address !== void 0) views.push({
+			...address,
+			components: withParentAddress(entity.components, addresses)
+		});
+	}
+	return {
+		ui: read(app, sources.ui),
+		views: views.toSorted(byAddress)
+	};
+}
+//#endregion
+//#region src/visual/settle.ts
+/** The length of one frame at 60 fps. */
+const FRAME_MS = 1e3 / 60;
+/**
+* Yields the task queue once: a timer of 0 ms.
+*
+* @returns A promise that settles in the next task.
+*/
+function nextTask() {
+	return new Promise((resolve) => {
+		setTimeout(resolve, 0);
+	});
+}
+/**
+* Runs frames by hand, each followed by one task.
+*
+* @param app - The started app.
+* @param count - How many frames.
+*/
+async function frames(app, count) {
+	for (let frame = 0; frame < count; frame += 1) {
+		app.time.step(FRAME_MS);
+		await nextTask();
+	}
+}
+/**
+* Runs frames until the graph rests at a gate or stops: at least one, at most `limit`. One more
+* frame follows, because a screen the gate opened builds its ui in the frame after it.
+*
+* @param app - The started app.
+* @param limit - The most frames to run, `settleFrames` of the run.
+* @param place - The test and the step, for the message.
+* @throws {Error} When the graph neither rests at a gate nor stops within `limit` frames.
+*/
+async function settle(app, limit, place) {
+	for (let frame = 0; frame < limit; frame += 1) {
+		await frames(app, 1);
+		const state = app.flow.state();
+		if (state.pending.gate !== void 0 || !state.running) {
+			await frames(app, 1);
+			return;
+		}
+	}
+	throw new Error(`[game] Visual test "${place.test}", ${place.where} did not settle in ${limit} frames.\n  The graph stands at "${app.flow.state().path}"; add a step that answers what it waits for.`);
+}
+//#endregion
+//#region src/visual/leg-headless.ts
+/**
+* @file visual — the headless leg: plain Bun, the renderer inert, the mode `live`. Each test gets
+* a fresh app: start, restore its start through `game.restore`, play its steps through the
+* `/control` commands, and at each checkpoint land every motion and compare `state.json` and
+* `describe.json` with their baselines, or write them.
+*/
+/** The frames run after `finishAll`, so the landed pose is laid out and synced. */
+const REST_FRAMES = 2;
+/**
+* Sets the dev flag for a run: the `/control` commands run in dev builds only, and this is a test
+* tool a game calls on purpose.
+*
+* @returns Puts the flag back as it was.
+*/
+function enableDevelopment() {
+	const had = Object.hasOwn(globalThis, "__MOKU_GAME_DEV__");
+	const before = globalThis.__MOKU_GAME_DEV__;
+	globalThis.__MOKU_GAME_DEV__ = true;
+	return () => {
+		if (had) globalThis.__MOKU_GAME_DEV__ = before;
+		else Reflect.deleteProperty(globalThis, "__MOKU_GAME_DEV__");
+	};
+}
+/**
+* Reads the message of whatever a test threw.
+*
+* @param error - What was thrown.
+* @returns The message of an error, the value as text otherwise.
+* @example
+* ```ts
+* messageOf(new Error("[game] Boom.\n  Fix it.")); // "[game] Boom.\n  Fix it."
+* ```
+*/
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Turns the message of a failure into the second line of the test's error: one sentence or
+* more, without the `[game]` mark, ending with a period.
+*
+* @param error - What the command threw.
+* @returns The reason.
+* @example
+* ```ts
+* reasonOf(new Error("[game] No element.\n  Read sources.ui.")); // "No element. Read sources.ui."
+* ```
+*/
+function reasonOf(error) {
+	const text = messageOf(error).replace(/^\[game\] /u, "").replaceAll(/\n\s*/gu, " ").trim();
+	return text.endsWith(".") ? text : `${text}.`;
+}
+/**
+* Builds the error of a step that failed: the test, the step and the reason. Both legs use it.
+*
+* @param test - The test name.
+* @param where - The step, such as `step 2 (tap)`.
+* @param error - What the step threw, or the message of it.
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* stepFailure("reward-popup", "step 1 (tap)", "Target crashed").message;
+* // '[game] Visual test "reward-popup", step 1 (tap) failed.\n  Target crashed.'
+* ```
+*/
+function stepFailure(test, where, error) {
+	return /* @__PURE__ */ new Error(`[game] Visual test "${test}", ${where} failed.\n  ${reasonOf(error)}`);
+}
+/**
+* Runs `work`, and turns its rejection into the error of a step.
+*
+* @param test - The test name.
+* @param where - The step, such as `step 2 (tap)`.
+* @param work - What the step does.
+* @throws {Error} `[game] Visual test "<test>", <where> failed.` with the reason below it.
+*/
+async function failing(test, where, work) {
+	try {
+		await work();
+	} catch (error) {
+		throw stepFailure(test, where, error);
+	}
+}
+/**
+* Starts the one loop unless the app's own `onStart` did, keeping its rejection.
+*
+* @param app - The started app.
+* @returns Where the rejection waits.
+*/
+function startLoop(app) {
+	const loop = { error: void 0 };
+	if (app.flow.state().running) return loop;
+	app.flow.run().catch((error) => {
+		loop.error = error;
+	});
+	return loop;
+}
+/**
+* Settles, then throws the rejection of the loop if it came.
+*
+* @param play - The test being played.
+* @param where - The step, for the message.
+* @throws {Error} When the graph does not settle, or the loop failed.
+*/
+async function settleAt(play, where) {
+	await settle(play.app, play.run.settleFrames, {
+		test: play.test.name,
+		where
+	});
+	if (play.loop.error !== void 0) throw play.loop.error;
+}
+/**
+* Plays a checkpoint: settle, land every track and loop, two frames, then read and compare.
+*
+* @param play - The test being played.
+* @param name - The checkpoint name.
+* @param where - The step, for the message.
+* @returns The outcome of the checkpoint; `pixels` is skipped in this leg.
+*/
+async function checkpoint$1(play, name, where) {
+	const { app, test, run: options } = play;
+	await settleAt(play, where);
+	app.anim.finishAll();
+	await frames(app, REST_FRAMES);
+	const file = (kind) => baselineFile(options.dir, test.name, name, kind);
+	const state = await checkBaseline(file("state.json"), stableJson(stateOf(app)), options.update);
+	const describe = await checkBaseline(file("describe.json"), stableJson(describeOf(app)), options.update);
+	const first = state.first ?? describe.first;
+	const result = {
+		name,
+		state: state.outcome,
+		describe: describe.outcome,
+		pixels: "skipped"
+	};
+	return first === void 0 ? result : {
+		...result,
+		first
+	};
+}
+/**
+* Plays the start and the steps of a test on a started app.
+*
+* @param play - The test being played.
+* @param checkpoints - Where each checkpoint's outcome goes, as soon as it is known.
+*/
+async function playSteps$1(play, checkpoints) {
+	const { app, test } = play;
+	const repro = {
+		...test.start,
+		route: []
+	};
+	await settleAt(play, "the start");
+	await failing(test.name, "the start", () => run(app, commands.restore, { repro }));
+	await settleAt(play, "the start");
+	for (const [index, step] of test.steps.entries()) {
+		const entry = stepEntry(test.name, step, index);
+		const where = `step ${index + 1} (${entry.kind === "checkpoint" ? "checkpoint" : entry.name})`;
+		if (entry.kind === "checkpoint") {
+			checkpoints.push(await checkpoint$1(play, entry.name, where));
+			continue;
+		}
+		await failing(test.name, where, () => runStep(app, entry.name, entry.input));
+		await settleAt(play, where);
+	}
+}
+/**
+* Plays one test on a fresh app, live, and stops the app at the end.
+*
+* @param setup - How the runner builds a game.
+* @param test - The test.
+* @param options - The run options.
+* @param checkpoints - Where each checkpoint's outcome goes.
+*/
+async function playTest(setup, test, options, checkpoints) {
+	const app = setup.app();
+	app.flow.setMode("live");
+	await app.start();
+	try {
+		await playSteps$1({
+			app,
+			test,
+			run: options,
+			loop: startLoop(app)
+		}, checkpoints);
+	} finally {
+		await app.stop();
+	}
+}
+/**
+* Plays one test and turns its outcome into a result. A test that fails keeps the checkpoints it
+* reached and carries the error instead of throwing it.
+*
+* @param setup - How the runner builds a game.
+* @param test - The test to play.
+* @param options - The run options.
+* @returns The result of the test.
+*/
+async function playOne(setup, test, options) {
+	const checkpoints = [];
+	try {
+		await playTest(setup, test, options, checkpoints);
+		return {
+			name: test.name,
+			checkpoints
+		};
+	} catch (error) {
+		return {
+			name: test.name,
+			checkpoints,
+			error: messageOf(error)
+		};
+	}
+}
+/**
+* Runs the headless leg over the selected tests, one after the other. The dev flag is on for the
+* run and put back after it. A test that fails keeps the checkpoints it reached and carries the
+* error; the next test still runs.
+*
+* @param setup - How the runner builds a game.
+* @param tests - The selected tests.
+* @param options - The run options.
+* @returns One result per test, in order.
+*/
+async function runHeadlessLeg(setup, tests, options) {
+	const restore = enableDevelopment();
+	const results = [];
+	try {
+		for (const test of tests) results.push(await playOne(setup, test, options));
+	} finally {
+		restore();
+	}
+	return results;
+}
+//#endregion
+//#region src/visual/page-script.ts
+/**
+* Tells whether the dev page exposes both handles yet. The leg waits on it after `goto`.
+*
+* @returns True once `globalThis.game` and `globalThis.doors` are set.
+*/
+function pageReady() {
+	return Reflect.get(globalThis, "game") !== void 0 && Reflect.get(globalThis, "doors") !== void 0;
+}
+/**
+* Tells the game of the page contract from any other value: an object with a graph, motions and
+* a renderer.
+*
+* @param value - What `globalThis.game` holds.
+* @returns True for the app the dev page set.
+*/
+function isPageGame(value) {
+	return typeof value === "object" && value !== null && "flow" in value && "anim" in value && "renderer" in value;
+}
+/**
+* Tells the doors of the page contract from any other value.
+*
+* @param value - What `globalThis.doors` holds.
+* @returns True for an object with `read`, `run`, `sources` and `commands`.
+*/
+function isPageDoors(value) {
+	return typeof value === "object" && value !== null && "read" in value && "run" in value && "sources" in value && "commands" in value;
+}
+/**
+* Reads the two handles of the page contract.
+*
+* @returns The game and the doors.
+* @throws {Error} When the page set either of them to something else, or not at all.
+*/
+function pageHandles() {
+	const game = Reflect.get(globalThis, "game");
+	const doors = Reflect.get(globalThis, "doors");
+	if (isPageGame(game) && isPageDoors(doors)) return {
+		game,
+		doors
+	};
+	throw new Error("[game] The page exposes no game and doors.\n  Set globalThis.game and globalThis.doors in the dev page.");
+}
+/**
+* Waits for the next frame of the browser. It moves no game time while the leg holds the pause.
+*
+* @returns A promise that settles in the next `requestAnimationFrame`.
+*/
+function pageFrame() {
+	return new Promise((resolve) => {
+		requestAnimationFrame(() => {
+			resolve();
+		});
+	});
+}
+/**
+* Yields the task queue once, so every promise chain that can move does.
+*
+* @returns A promise that settles in the next task.
+*/
+function pageTask() {
+	return new Promise((resolve) => {
+		setTimeout(resolve, 0);
+	});
+}
+/**
+* Reads the message of whatever a page call threw.
+*
+* @param error - What was thrown.
+* @returns The message of an error, the value as text otherwise.
+* @example
+* ```ts
+* pageMessage(new Error("The source image could not be decoded.")); // "The source image could not be decoded."
+* ```
+*/
+function pageMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Runs one frame of the game through the `step` command: the six phases, the render included,
+* also while the game is paused.
+*
+* @param handles - The game and the doors.
+* @param deltaMs - The game time of the frame; 1000/60 ms when omitted, the frame of the
+*   headless leg.
+*/
+async function pageStepFrame(handles, deltaMs) {
+	await handles.doors.run(handles.game, handles.doors.commands.step, {
+		frames: 1,
+		deltaMs: deltaMs ?? 1e3 / 60
+	});
+}
+/**
+* Runs one frame of a test: a stepped frame of 1000/60 ms, then the browser's next frame, so a
+* load and a promise chain progress before the graph is read.
+*
+* @param handles - The game and the doors.
+*/
+async function pageTick(handles) {
+	await pageStepFrame(handles);
+	await pageFrame();
+}
+/**
+* Runs frames until the graph rests at a gate or stops: at least one frame, at most `limit`, then
+* one frame more so the ui of a screen the gate opened is built. The settle of the headless leg,
+* on the same stepped frames.
+*
+* @param handles - The game and the doors.
+* @param limit - The most frames to run, `settleFrames` of the run.
+* @param place - The test and the step, for the message.
+* @returns The error message when the graph did not rest, `undefined` when it did.
+*/
+async function pageSettle(handles, limit, place) {
+	const { game } = handles;
+	for (let frame = 0; frame < limit; frame += 1) {
+		await pageTick(handles);
+		const state = game.flow.state();
+		if (state.pending.gate !== void 0 || !state.running) {
+			await pageTick(handles);
+			return;
+		}
+	}
+	return `[game] Visual test "${place.test}", ${place.where} did not settle in ${limit} frames.\n  The graph stands at "${game.flow.state().path}"; add a step that answers what it waits for.`;
+}
+/**
+* Runs one `/control` command through the doors, the way an editor does, and runs frames while it
+* waits for them: a `restore` resolves only once the graph rests, and that takes frames. A
+* command that waits for no frame is done before the first one.
+*
+* @param handles - The game and the doors.
+* @param command - The command by its short name, and its input.
+* @param command.name - The short name of the command.
+* @param command.input - Its input.
+* @param limit - The most frames to run, `settleFrames` of the run.
+* @param place - The test and the step, for the message.
+* @returns The error message when the command did not finish, `undefined` when it did.
+* @throws {unknown} Whatever the command threw.
+*/
+async function pageRun(handles, command, limit, place) {
+	const { game, doors } = handles;
+	const runners = doors.commands;
+	const ran = {
+		done: false,
+		failure: void 0
+	};
+	const finished = doors.run(game, runners[command.name], command.input).then(() => {
+		ran.done = true;
+	}, (error) => {
+		ran.done = true;
+		ran.failure = { error };
+	});
+	let frames = 0;
+	await pageTask();
+	while (!ran.done) {
+		if (frames === limit) return `[game] Visual test "${place.test}", ${place.where} did not finish in ${limit} frames.\n  The graph stands at "${game.flow.state().path}"; the command waits for something the stepped frames never bring.`;
+		await pageTick(handles);
+		frames += 1;
+	}
+	await finished;
+	if (ran.failure !== void 0) throw ran.failure.error;
+}
+/**
+* Waits until the page's own graph runs and rests at a gate, the way the dev page starts it, and
+* reads the backend the renderer chose. The game runs on the browser's frames here: the leg
+* pauses it later, before the start of a test.
+*
+* @param argument - The page URL, for the message, and the most frames to wait.
+* @param argument.url - The URL of the dev page.
+* @param argument.settleFrames - The most frames to wait.
+* @returns The renderer kind, or why the page did not start.
+*/
+async function pageStart(argument) {
+	try {
+		const { game } = pageHandles();
+		for (let frame = 0; frame < argument.settleFrames; frame += 1) {
+			const state = game.flow.state();
+			if (state.running && state.pending.gate !== void 0) return {
+				ok: true,
+				value: game.renderer.host.kind()
+			};
+			await pageFrame();
+		}
+		return {
+			ok: false,
+			error: `[game] The page at ${argument.url} did not rest at a gate in ${argument.settleFrames} frames.\n  The graph stands at "${game.flow.state().path}"; start the app and run its graph in the dev page.`
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			reason: pageMessage(error)
+		};
+	}
+}
+/**
+* Holds the game for a test: the `pause` command, the editor's pause, so the browser's frames no
+* longer move game time; then stepped frames up to the start time, 1000/60 ms each and the last
+* one shorter, so the game lands on it to the last bit. The page's own start took a different
+* time on every run; from here on every test starts at the same game time.
+*
+* @param argument - The test and the step, and the game time a test starts at.
+* @param argument.startMs - The game time a test starts at, in milliseconds; a page whose clock
+*   is already past it starts at the next multiple of it.
+* @returns The game time the test starts at, or why the page refused the pause.
+*/
+async function pagePause(argument) {
+	try {
+		const handles = pageHandles();
+		const { game, doors } = handles;
+		const { startMs } = argument;
+		const frameMs = 1e3 / 60;
+		await doors.run(game, doors.commands.pause);
+		const start = Math.max(startMs, Math.ceil(game.time.snapshot().elapsed / startMs) * startMs);
+		for (let left = start - game.time.snapshot().elapsed; left > 0; left = start - game.time.snapshot().elapsed) await pageStepFrame(handles, Math.min(left, frameMs));
+		return {
+			ok: true,
+			value: game.time.snapshot().elapsed
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			reason: pageMessage(error)
+		};
+	}
+}
+/**
+* Runs one `/control` command through the doors of the page, the way an editor does, with frames
+* stepped while it waits for them, then settles. The leg restores the start of a test with it
+* too, as the command `restore`.
+*
+* @param argument - The test and the step, the command by its short name, its input, and the most
+*   frames to settle.
+* @param argument.name - The short name of the command.
+* @param argument.input - Its input.
+* @param argument.settleFrames - The most frames to settle.
+* @returns Nothing, or why the command or the settle failed.
+*/
+async function pageStep(argument) {
+	try {
+		const handles = pageHandles();
+		const unsettled = await pageRun(handles, argument, argument.settleFrames, argument) ?? await pageSettle(handles, argument.settleFrames, argument);
+		return unsettled === void 0 ? {
+			ok: true,
+			value: void 0
+		} : {
+			ok: false,
+			error: unsettled
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			reason: pageMessage(error)
+		};
+	}
+}
+/**
+* Plays a checkpoint in the page: settle, land every track and loop, two stepped frames, then the
+* picture of the whole canvas as lossless WebP and the state through the doors. The game is
+* paused, so the picture is the stage after the last stepped frame.
+*
+* @param argument - The test and the step, and the most frames to settle.
+* @param argument.settleFrames - The most frames to settle.
+* @returns The state and the picture, or why the checkpoint failed.
+*/
+async function pageCheckpoint(argument) {
+	try {
+		const handles = pageHandles();
+		const { game, doors } = handles;
+		const unsettled = await pageSettle(handles, argument.settleFrames, argument);
+		if (unsettled !== void 0) return {
+			ok: false,
+			error: unsettled
+		};
+		game.anim.finishAll();
+		await pageTick(handles);
+		await pageTick(handles);
+		const captured = await game.renderer.capture();
+		const screen = captured === void 0 ? void 0 : await pageWebp(captured);
+		return {
+			ok: true,
+			value: {
+				state: {
+					path: doors.read(game, doors.sources.position).path,
+					...doors.read(game, doors.sources.model)
+				},
+				screen
+			}
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			reason: pageMessage(error)
+		};
+	}
+}
+/**
+* Measures how far apart two pixels are: the largest delta of their four channels.
+*
+* @param expected - The bytes of the baseline.
+* @param actual - The bytes of the capture.
+* @param at - The index of the pixel's first byte.
+* @returns The largest channel delta, from 0 to 255.
+* @example
+* ```ts
+* channelDelta(new Uint8ClampedArray([10, 20, 30, 255]), new Uint8ClampedArray([12, 20, 0, 255]), 0); // 30
+* ```
+*/
+function channelDelta(expected, actual, at) {
+	let delta = 0;
+	for (let channel = at; channel < at + 4; channel += 1) delta = Math.max(delta, Math.abs((expected[channel] ?? 0) - (actual[channel] ?? 0)));
+	return delta;
+}
+/**
+* Compares two pictures pixel by pixel. A pixel differs when the largest delta of its channels
+* exceeds `threshold`. The diff picture is red where a pixel differs and the baseline faded
+* three quarters towards white elsewhere. Two sizes are not compared.
+*
+* @param expected - The baseline.
+* @param actual - The capture.
+* @param threshold - The largest channel delta that still counts as the same pixel.
+* @returns The counts and the diff picture.
+* @example
+* ```ts
+* const black = { width: 1, height: 1, data: new Uint8ClampedArray([0, 0, 0, 255]) };
+* comparePixels(black, { ...black, data: new Uint8ClampedArray([30, 0, 0, 255]) }, 24).differing; // 1
+* ```
+*/
+function comparePixels(expected, actual, threshold) {
+	if (expected.width !== actual.width || expected.height !== actual.height) return {
+		sameSize: false,
+		differing: 0,
+		total: 0,
+		diff: /* @__PURE__ */ new Uint8ClampedArray(0)
+	};
+	const total = expected.width * expected.height;
+	const diff = new Uint8ClampedArray(total * 4);
+	const threeQuartersWhite = 765;
+	let differing = 0;
+	for (let at = 0; at < diff.length; at += 4) {
+		if (channelDelta(expected.data, actual.data, at) > threshold) {
+			differing += 1;
+			diff.set([
+				255,
+				0,
+				0,
+				255
+			], at);
+			continue;
+		}
+		for (let channel = at; channel < at + 3; channel += 1) diff[channel] = ((expected.data[channel] ?? 0) + threeQuartersWhite) / 4;
+		diff[at + 3] = 255;
+	}
+	return {
+		sameSize: true,
+		differing,
+		total,
+		diff
+	};
+}
+/**
+* Gets a 2D context of an `OffscreenCanvas`, the one canvas the compare draws on.
+*
+* @param width - Pixels across.
+* @param height - Pixels down.
+* @returns The canvas and its context.
+* @throws {Error} When the browser gives no 2D context.
+*/
+function pageCanvas(width, height) {
+	const canvas = new OffscreenCanvas(width, height);
+	const context = canvas.getContext("2d", { willReadFrequently: true });
+	if (context === null) throw new Error("The browser gave no 2D context for an OffscreenCanvas.");
+	return {
+		canvas,
+		context
+	};
+}
+/**
+* Decodes a PNG or WebP data URL into its pixels, with no colour conversion.
+*
+* @param url - The data URL.
+* @returns The pixels.
+*/
+async function pageDecode(url) {
+	const blob = await (await fetch(url)).blob();
+	const bitmap = await createImageBitmap(blob, {
+		colorSpaceConversion: "none",
+		premultiplyAlpha: "none"
+	});
+	const { context } = pageCanvas(bitmap.width, bitmap.height);
+	context.drawImage(bitmap, 0, 0);
+	const image = context.getImageData(0, 0, bitmap.width, bitmap.height);
+	return {
+		width: image.width,
+		height: image.height,
+		data: image.data
+	};
+}
+/**
+* Encodes pixels as a lossless WebP data URL: Chrome encodes WebP at quality 1 losslessly, so an
+* opaque picture decodes to the same bytes.
+*
+* @param pixels - The pixels.
+* @returns The data URL.
+* @throws {Error} When the browser answers another type: it encodes no WebP.
+*/
+async function pageEncode(pixels) {
+	const { canvas, context } = pageCanvas(pixels.width, pixels.height);
+	context.putImageData(new ImageData(pixels.data, pixels.width, pixels.height), 0, 0);
+	const blob = await canvas.convertToBlob({
+		type: "image/webp",
+		quality: 1
+	});
+	if (blob.type !== "image/webp") throw new Error(`The browser does not encode WebP: it answered ${blob.type}.`);
+	const bytes = new Uint8Array(await blob.arrayBuffer());
+	const chunkBytes = 32768;
+	let binary = "";
+	for (let start = 0; start < bytes.length; start += chunkBytes) binary += String.fromCodePoint(...bytes.subarray(start, start + chunkBytes));
+	return `data:image/webp;base64,${btoa(binary)}`;
+}
+/**
+* Turns the PNG data URL of `renderer.capture()` into the lossless WebP of the baselines.
+*
+* @param url - The PNG data URL.
+* @returns The WebP data URL of the same pixels.
+*/
+async function pageWebp(url) {
+	return pageEncode(await pageDecode(url));
+}
+/**
+* Compares the baseline picture with the capture inside the page, on an `OffscreenCanvas`, so
+* the Bun side needs no image library. The diff picture comes back only when a pixel differs.
+*
+* @param argument - The test and the step, the two WebP data URLs and the channel threshold.
+* @param argument.expected - The baseline `screen.webp`.
+* @param argument.actual - The capture.
+* @param argument.threshold - The largest channel delta that still counts as the same pixel.
+* @returns The counts and the diff picture, or why the pictures could not be compared.
+*/
+async function pageCompare(argument) {
+	try {
+		const [expected, actual] = await Promise.all([pageDecode(argument.expected), pageDecode(argument.actual)]);
+		const found = comparePixels(expected, actual, argument.threshold);
+		const counts = {
+			sameSize: found.sameSize,
+			differing: found.differing,
+			total: found.total
+		};
+		if (found.differing === 0) return {
+			ok: true,
+			value: counts
+		};
+		const diff = await pageEncode({
+			width: expected.width,
+			height: expected.height,
+			data: found.diff
+		});
+		return {
+			ok: true,
+			value: {
+				...counts,
+				diff
+			}
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			reason: pageMessage(error)
+		};
+	}
+}
+/** Every function of the page script, in the order the page gets them. */
+const pageFunctions = [
+	pageReady,
+	isPageGame,
+	isPageDoors,
+	pageHandles,
+	pageFrame,
+	pageTask,
+	pageMessage,
+	pageStepFrame,
+	pageTick,
+	pageSettle,
+	pageRun,
+	pageStart,
+	pagePause,
+	pageStep,
+	pageCheckpoint,
+	channelDelta,
+	comparePixels,
+	pageCanvas,
+	pageDecode,
+	pageEncode,
+	pageWebp,
+	pageCompare
+];
+/**
+* Writes the script that installs the page functions in the dev page, each under its own name on
+* `globalThis`. The leg adds it as an init script, so it runs before the page's own code, on
+* every load.
+*
+* @returns The source of the script.
+*/
+function pageScript() {
+	return `(() => {\n${pageFunctions.flatMap((fn) => [String(fn), `globalThis[${JSON.stringify(fn.name)}] = ${fn.name};`]).join("\n")}\n})();\n`;
+}
+//#endregion
+//#region src/visual/leg-browser.ts
+/** The Chrome flags of `.planning/e2e/run.mjs`: WebGPU on Metal, on any GPU. */
+const WEBGPU_FLAGS = [
+	"--enable-unsafe-webgpu",
+	"--use-angle=metal",
+	"--enable-gpu",
+	"--ignore-gpu-blocklist"
+];
+/** The page width in CSS px when the setup names none: a phone. */
+const DEFAULT_WIDTH = 390;
+/** The device scale when the setup names none. */
+const DEFAULT_SCALE = 2;
+/** How long the page may take to expose `game` and `doors`, and to stop loading, in milliseconds. */
+const READY_MS = 15e3;
+/**
+* The game time every test starts at, in milliseconds: the page reaches it on stepped frames after
+* the pause, whatever its own start took. A page whose clock is past it starts at the next
+* multiple.
+*/
+const START_MS = 5e3;
+/** The baseline picture of a checkpoint, and the two the leg leaves beside it on a difference. */
+const SCREEN = {
+	baseline: "screen.webp",
+	actual: "screen.actual.webp",
+	diff: "screen.diff.webp"
+};
+/**
+* Reads the first line of a Playwright error, without the name of the call that failed.
+*
+* @param error - What Playwright threw.
+* @returns The line, without a final period.
+* @example
+* ```ts
+* firstLine(new Error("page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:3000/\nCall log:")); // "net::ERR_CONNECTION_REFUSED at http://localhost:3000/"
+* ```
+*/
+function firstLine(error) {
+	const [line = ""] = messageOf(error).split("\n");
+	return line.replace(/^[\w.]+: /u, "").replace(/\.$/u, "");
+}
+/**
+* Loads `chromium` from `playwright-core`, the optional peer, with a dynamic import: the package
+* never reaches a bundle that does not run the pixel leg.
+*
+* @returns The `chromium` of Playwright.
+* @throws {Error} When `playwright-core` is not installed.
+*/
+async function loadChromium() {
+	try {
+		return (await import("playwright-core")).chromium;
+	} catch {
+		throw new Error("[game] The pixel leg needs playwright-core.\n  Add it: bun add -d playwright-core, or run with --no-pixels.");
+	}
+}
+/**
+* Launches one Chrome, keeping why it did not start.
+*
+* @param chromium - The `chromium` of Playwright.
+* @param options - The launch options.
+* @returns The browser, or the reason.
+*/
+async function attempt(chromium, options) {
+	try {
+		return { browser: await chromium.launch(options) };
+	} catch (error) {
+		return { reason: firstLine(error) };
+	}
+}
+/**
+* Launches Chrome with the four WebGPU flags: the Chrome of `page.browser` when the setup names
+* one, else Playwright's own Chromium, else the system Chrome. Playwright's Chromium comes first
+* because its version is pinned by `playwright-core`, so the baselines do not move with a Chrome
+* update.
+*
+* @param chromium - The `chromium` of Playwright.
+* @param browser - The `browser` of the page, if any.
+* @returns The browser.
+* @throws {Error} When the named Chrome, or every default one, does not launch.
+*/
+async function launchChrome(chromium, browser) {
+	const args = [...WEBGPU_FLAGS];
+	if (browser !== void 0) {
+		const given = await attempt(chromium, {
+			...browser,
+			args
+		});
+		if ("browser" in given) return given.browser;
+		throw new Error(`[game] Chrome did not launch from page.browser: ${given.reason}.\n  Fix page.browser, or run with --no-pixels.`);
+	}
+	const own = await attempt(chromium, { args });
+	if ("browser" in own) return own.browser;
+	const system = await attempt(chromium, {
+		channel: "chrome",
+		args
+	});
+	if ("browser" in system) return system.browser;
+	throw new Error(`[game] No Chrome launched: ${own.reason}.\n  Install Playwright's Chromium (bunx playwright-core install chromium), set page.browser, or run with --no-pixels.`);
+}
+/**
+* Sizes the page: `page.width` CSS px wide (390), as tall as the inert frame of the game is at
+* that width, so the reference frame of the page equals the one of the headless leg; a phone
+* with touch at `page.deviceScaleFactor` (2). Builds one app of the setup, never started, to read
+* its inert frame.
+*
+* @param setup - The setup, for a fresh app.
+* @param page - The page.
+* @returns The options of the browser context.
+*/
+function pageSize(setup, page) {
+	const width = page.width ?? DEFAULT_WIDTH;
+	const frame = setup.app().renderer.viewport.size();
+	return {
+		viewport: {
+			width,
+			height: Math.round(width * frame.height / frame.width)
+		},
+		deviceScaleFactor: page.deviceScaleFactor ?? DEFAULT_SCALE,
+		isMobile: true,
+		hasTouch: true
+	};
+}
+/**
+* Decides the pixel outcome of a checkpoint: two sizes are `"different"` at `"size"`; else the
+* share of differing pixels is `"different"` over `tolerance.ratio`, `"same"` at or under it.
+*
+* @param compared - What the page counted.
+* @param tolerance - The tolerance of the run.
+* @returns The outcome, with `pixelRatio` or `first` on a difference.
+* @example
+* ```ts
+* pixelOutcome({ sameSize: true, differing: 2, total: 1000 }, { ratio: 0.001, threshold: 24 }); // { outcome: "different", pixelRatio: 0.002 }
+* ```
+*/
+function pixelOutcome(compared, tolerance) {
+	if (!compared.sameSize) return {
+		outcome: "different",
+		first: "size"
+	};
+	const pixelRatio = compared.differing / compared.total;
+	return pixelRatio > tolerance.ratio ? {
+		outcome: "different",
+		pixelRatio
+	} : { outcome: "same" };
+}
+/**
+* Adds what the browser leg found to the checkpoint result of the headless leg. A state the page
+* reached differently is a state difference. `first` stays the state's before the describe's,
+* then names `"size"`. A pixel difference gets a verdict: `"rendering"` when the state and the
+* describe were the same in this run, the regression a renderer change makes, `"behaviour"`
+* otherwise.
+*
+* @param result - The checkpoint result of the headless leg.
+* @param found - What the browser leg found there.
+* @returns The checkpoint result with its pixel fields.
+* @example
+* ```ts
+* const headless = { name: "open", state: "same", describe: "same", pixels: "skipped" } as const;
+* withPixels(headless, { state: { outcome: "same" }, pixels: { outcome: "different", pixelRatio: 0.004 } });
+* // { name: "open", state: "same", describe: "same", pixels: "different", pixelRatio: 0.004, verdict: "rendering" }
+* ```
+*/
+function withPixels(result, found) {
+	const state = found.state?.outcome === "different" ? "different" : result.state;
+	const stateFirst = result.state === "different" ? result.first : found.state?.first;
+	const describeFirst = result.state === "different" ? void 0 : result.first;
+	const first = stateFirst ?? describeFirst ?? found.pixels.first;
+	const merged = {
+		name: result.name,
+		state,
+		describe: result.describe,
+		pixels: found.pixels.outcome
+	};
+	if (first !== void 0) merged.first = first;
+	if (found.pixels.outcome !== "different") return merged;
+	if (found.pixels.pixelRatio !== void 0) merged.pixelRatio = found.pixels.pixelRatio;
+	merged.verdict = state === "same" && result.describe === "same" ? "rendering" : "behaviour";
+	return merged;
+}
+/**
+* Runs one page function and takes its answer. A page that breaks, and a failure the function
+* answered as a reason, become the error of the step; a whole message is thrown as it is.
+*
+* @param page - The page.
+* @param fn - The page function.
+* @param argument - Its argument, with the test and the step.
+* @returns The value the function answered.
+* @throws {Error} When the page broke or the function failed.
+*/
+async function callPage(page, fn, argument) {
+	const answer = await page.evaluate(fn, argument).catch((error) => {
+		throw stepFailure(argument.test, argument.where, firstLine(error));
+	});
+	if (answer.ok) return answer.value;
+	throw "error" in answer ? new Error(answer.error) : stepFailure(argument.test, argument.where, answer.reason);
+}
+/**
+* Waits in the page for its graph to rest at its first gate, and reads the renderer kind.
+*
+* @param page - The page, its handles exposed.
+* @param url - The URL of the dev page, for the message.
+* @param run - The run options, for `settleFrames`.
+* @returns The renderer kind.
+* @throws {Error} When the graph does not rest at a gate, or the page breaks.
+*/
+async function startPage(page, url, run) {
+	const settleFrames = run.settleFrames;
+	const started = await page.evaluate(pageStart, {
+		url,
+		settleFrames
+	}).catch((error) => ({
+		ok: false,
+		reason: firstLine(error)
+	}));
+	if (started.ok) return started.value;
+	throw new Error("error" in started ? started.error : `[game] The page at ${url} did not start.\n  ${reasonOf(started.reason)}`);
+}
+/**
+* Opens the dev page for one test: the page script first, then the URL, then the wait for
+* `game` and `doors`, for the graph at its first gate, the check that it draws with WebGPU, and
+* the wait until no request ran for half a second, so no load is left for the stepped frames.
+*
+* @param context - The browser context.
+* @param url - The URL of the dev page.
+* @param run - The run options, for `settleFrames`.
+* @returns The open page.
+* @throws {Error} When the page does not open, never exposes `game` and `doors`, does not start,
+*   does not draw with WebGPU or never stops loading. The page is closed then.
+*/
+async function openPage(context, url, run) {
+	const page = await context.newPage();
+	try {
+		await page.addInitScript({ content: pageScript() });
+		await page.goto(url).catch((error) => {
+			throw new Error(`[game] The page at ${url} did not open: ${firstLine(error)}.\n  Serve the dev page (bun ./web/serve.ts), or run with --no-pixels.`);
+		});
+		await page.waitForFunction(pageReady, void 0, { timeout: READY_MS }).catch(() => {
+			throw new Error(`[game] The page at ${url} exposes no game and doors.\n  Serve the dev page (bun ./web/serve.ts) and set globalThis.game and globalThis.doors in it.`);
+		});
+		const kind = await startPage(page, url, run);
+		if (kind !== "webgpu") throw new Error(`[game] The page at ${url} draws with ${kind}, not WebGPU.\n  The pixel baselines are WebGPU only: use a Chrome with WebGPU on a Mac, or run with --no-pixels.`);
+		await page.waitForLoadState("networkidle", { timeout: READY_MS }).catch(() => {
+			throw new Error(`[game] The page at ${url} did not stop loading in ${READY_MS / 1e3} s.\n  Let it finish its requests: the leg pauses the game once nothing loads.`);
+		});
+		return page;
+	} catch (error) {
+		await page.close();
+		throw error;
+	}
+}
+/**
+* Checks the picture of a checkpoint against `screen.webp`: a missing baseline, or `--update`,
+* writes it; a difference writes `screen.actual.webp`, and `screen.diff.webp` when the sizes
+* match.
+*
+* @param play - The test being played.
+* @param file - Names a file of the checkpoint.
+* @param where - The step, for the message.
+* @param screen - The picture the page took.
+* @returns The pixel outcome.
+*/
+async function checkScreen(play, file, where, screen) {
+	const { run } = play;
+	const baseline = run.update ? void 0 : await readScreen(file(SCREEN.baseline));
+	if (baseline === void 0) {
+		await writeScreen(file(SCREEN.baseline), screen);
+		return { outcome: "written" };
+	}
+	const compared = await callPage(play.page, pageCompare, {
+		test: play.test.name,
+		where,
+		expected: baseline,
+		actual: screen,
+		threshold: run.tolerance.threshold
+	});
+	const found = pixelOutcome(compared, run.tolerance);
+	if (found.outcome === "different") {
+		await writeScreen(file(SCREEN.actual), screen);
+		if (compared.diff !== void 0) await writeScreen(file(SCREEN.diff), compared.diff);
+	}
+	return found;
+}
+/**
+* Plays a checkpoint in the page and checks what it found: the state against `state.json` the
+* headless leg wrote, the picture against `screen.webp`.
+*
+* @param play - The test being played.
+* @param name - The checkpoint name.
+* @param where - The step, for the message.
+* @returns What the browser leg found there.
+* @throws {Error} When the page did not settle, gave no picture, or broke.
+*/
+async function checkpoint(play, name, where) {
+	const { test, run } = play;
+	const shot = await callPage(play.page, pageCheckpoint, {
+		test: test.name,
+		where,
+		settleFrames: run.settleFrames
+	});
+	if (shot.screen === void 0) throw new Error(`[game] Visual test "${test.name}", ${where}: the page gave no picture.\n  Serve a dev build with WebGPU: renderer.capture() answers only there.`);
+	const file = (kind) => baselineFile(run.dir, test.name, name, kind);
+	return {
+		state: await compareBaseline(file("state.json"), stableJson(shot.state)),
+		pixels: await checkScreen(play, file, where, shot.screen)
+	};
+}
+/**
+* Plays the start and the steps of a test in the open page, the way the headless leg does: pause
+* the game and step it to the start time, restore the start, run each command and settle on
+* stepped frames, and check each checkpoint.
+*
+* @param play - The test being played.
+* @param found - Where what each checkpoint found goes, as soon as it is known.
+*/
+async function playSteps(play, found) {
+	const { test, run } = play;
+	const repro = {
+		...test.start,
+		route: []
+	};
+	const base = {
+		test: test.name,
+		settleFrames: run.settleFrames
+	};
+	await callPage(play.page, pagePause, {
+		test: test.name,
+		where: "the start",
+		startMs: START_MS
+	});
+	await callPage(play.page, pageStep, {
+		...base,
+		where: "the start",
+		name: "restore",
+		input: { repro }
+	});
+	for (const [index, step] of test.steps.entries()) {
+		const entry = stepEntry(test.name, step, index);
+		const where = `step ${index + 1} (${entry.kind === "checkpoint" ? "checkpoint" : entry.name})`;
+		if (entry.kind === "checkpoint") {
+			found.set(entry.name, await checkpoint(play, entry.name, where));
+			continue;
+		}
+		await callPage(play.page, pageStep, {
+			...base,
+			where,
+			name: entry.name,
+			input: entry.input
+		});
+	}
+}
+/**
+* Plays one test in a page of its own and adds the pixel fields to its headless result. A test
+* that fails keeps what the checkpoints it reached found, and carries the error.
+*
+* @param context - The browser context.
+* @param play - The test and the run options; the page is opened here.
+* @param play.test - The test.
+* @param play.run - The run options.
+* @param url - The URL of the dev page.
+* @param headless - The result of the test in the headless leg.
+* @returns The result of the test with its pixel fields.
+* @throws {Error} When the page fails to open: that fails the leg.
+*/
+async function browserTest(context, play, url, headless) {
+	const page = await openPage(context, url, play.run);
+	const found = /* @__PURE__ */ new Map();
+	let failed;
+	try {
+		await playSteps({
+			...play,
+			page
+		}, found);
+	} catch (error) {
+		failed = messageOf(error);
+	} finally {
+		await page.close();
+	}
+	const checkpoints = headless.checkpoints.map((result) => {
+		const there = found.get(result.name);
+		return there === void 0 ? result : withPixels(result, there);
+	});
+	return failed === void 0 ? {
+		name: headless.name,
+		checkpoints
+	} : {
+		name: headless.name,
+		checkpoints,
+		error: failed
+	};
+}
+/**
+* Runs the browser leg over the tests the headless leg played, one page per test, and answers
+* their results with the pixel fields. A test the headless leg failed is left as it is. The
+* browser closes at the end, also after an error.
+*
+* @param setup - The setup: its `page`, and its app for the size of the page.
+* @param tests - The selected tests.
+* @param run - The run options.
+* @param headless - The results of the headless leg, in the order of `tests`.
+* @param load - Loads `chromium`; `playwright-core` by default.
+* @returns One result per test, in order.
+* @throws {Error} When the setup has no page, `playwright-core` or Chrome is missing, or the page
+*   does not open, expose `game` and `doors`, start, draw with WebGPU or stop loading.
+*/
+async function runBrowserLeg(setup, tests, run, headless, load = loadChromium) {
+	const page = setup.page;
+	if (page === void 0) throw new Error("[game] The pixel leg needs the dev page.\n  Pass page: { url } in the setup, or run with --no-pixels.");
+	const chromium = await load();
+	const options = pageSize(setup, page);
+	const browser = await launchChrome(chromium, page.browser);
+	try {
+		const context = await browser.newContext(options);
+		const results = [];
+		for (const test of tests) {
+			const before = headless.find((result) => result.name === test.name) ?? {
+				name: test.name,
+				checkpoints: []
+			};
+			results.push(before.error === void 0 ? await browserTest(context, {
+				test,
+				run
+			}, page.url, before) : before);
+		}
+		return results;
+	} finally {
+		await browser.close();
+	}
+}
+//#endregion
+//#region src/visual/run.ts
+/**
+* @file visual — `runVisualTests`, the runner a game's script calls, and `parseVisualArgv`, its
+* command line. It resolves the options, selects the tests, runs the headless leg and then, with
+* `pixels` on, the browser leg, prints one line per checkpoint through the branded console of
+* `@moku-labs/common/cli` and answers one report. The game's script sets the exit code.
+*/
+/** The folder of the visual tests, relative to where the script runs. */
+const DEFAULT_DIR = "tests/visual";
+/** The most frames a settle runs: ten seconds at 60 fps. */
+const DEFAULT_SETTLE_FRAMES = 600;
+/** A pixel differs above a channel delta of 24; one in a thousand may. */
+const DEFAULT_TOLERANCE = {
+	ratio: .001,
+	threshold: 24
+};
+/**
+* Reads the value after a flag that takes one.
+*
+* @param argv - The arguments.
+* @param index - The index of the flag.
+* @param placeholder - What the value is, for the message: `<name>`.
+* @returns The value.
+* @throws {Error} When the flag is last, or another flag follows it.
+*/
+function valueAfter(argv, index, placeholder) {
+	const value = argv[index + 1];
+	if (value !== void 0 && !value.startsWith("--")) return value;
+	const flag = argv[index];
+	throw new Error(`[game] The flag ${flag} needs a value.\n  Write it as ${flag} ${placeholder}.`);
+}
+/**
+* Reads the flags of the visual tests from a command line: `--update`, `--no-pixels`,
+* `--only <name>` (repeatable) and `--dir <path>`. An argument it does not know is left to the
+* script that got it, so a test runner's own arguments pass through.
+*
+* @param argv - The arguments after the script name.
+* @returns The flags that were given, and nothing else.
+* @throws {Error} When `--only` or `--dir` has no value.
+* @example
+* ```ts
+* // `bun tests/visual/run.ts --update --only reward-popup`
+* parseVisualArgv(["--update", "--only", "reward-popup"]); // { update: true, only: ["reward-popup"] }
+* parseVisualArgv(["--no-pixels", "--dir", "shots"]); // { pixels: false, dir: "shots" }
+* ```
+*/
+function parseVisualArgv(argv) {
+	const flags = {};
+	const only = [];
+	for (const [index, argument] of argv.entries()) {
+		if (argument === "--update") flags.update = true;
+		if (argument === "--no-pixels") flags.pixels = false;
+		if (argument === "--only") only.push(valueAfter(argv, index, "<name>"));
+		if (argument === "--dir") flags.dir = valueAfter(argv, index, "<path>");
+	}
+	return only.length === 0 ? flags : {
+		...flags,
+		only
+	};
+}
+/**
+* Fills in the options of a run: an explicit option wins over a flag of `argv`, a flag over the
+* default. `pixels` is on by default only with a `page` on a Mac.
+*
+* @param setup - The setup, for its `page`.
+* @param options - The options the script passed.
+* @returns The options with every default filled in.
+* @throws {Error} When a flag of `argv` misses its value.
+*/
+function resolveVisualOptions(setup, options = {}) {
+	const flags = parseVisualArgv(options.argv ?? process.argv.slice(2));
+	const only = options.only ?? flags.only;
+	const run = {
+		dir: options.dir ?? flags.dir ?? DEFAULT_DIR,
+		update: options.update ?? flags.update ?? false,
+		pixels: options.pixels ?? flags.pixels ?? (setup.page !== void 0 && process.platform === "darwin"),
+		settleFrames: options.settleFrames ?? DEFAULT_SETTLE_FRAMES,
+		tolerance: options.tolerance ?? { ...DEFAULT_TOLERANCE }
+	};
+	return only === void 0 ? run : {
+		...run,
+		only
+	};
+}
+/**
+* Picks the tests a run plays: all of them, or the ones `only` names, in the order given.
+*
+* @param tests - Every test of the script.
+* @param only - The names to run, if any.
+* @returns The selected tests.
+* @throws {Error} When a test is not well formed, two tests share a name, or `only` names no
+*   test.
+*/
+function selectTests(tests, only) {
+	for (const test of tests) checkVisualTest(test.name, test.steps);
+	const names = tests.map((test) => test.name);
+	const twice = names.find((name, index) => names.indexOf(name) !== index);
+	if (twice !== void 0) throw new Error(`[game] Two visual tests are named "${twice}".\n  Give every visual test its own name.`);
+	const unknown = only?.find((name) => !names.includes(name));
+	if (unknown !== void 0) throw new Error(`[game] No visual test is named "${unknown}".\n  Use one of: ${names.join(", ")}.`);
+	return only === void 0 ? [...tests] : tests.filter((test) => only.includes(test.name));
+}
+/**
+* Writes one comparison of a checkpoint for its line.
+*
+* @param kind - `state`, `describe` or `pixels`.
+* @param outcome - What the comparison found.
+* @param first - The path of the first difference, for `state` and `describe`.
+* @returns `state same`, or `state different at player.coins`.
+* @example
+* ```ts
+* outcomeText("state", "different", "player.coins"); // "state different at player.coins"
+* ```
+*/
+function outcomeText(kind, outcome, first) {
+	return outcome === "different" && first !== void 0 ? `${kind} ${outcome} at ${first}` : `${kind} ${outcome}`;
+}
+/**
+* Writes the pixel comparison of a checkpoint for its line: on a difference, the share of
+* differing pixels, or `at size`, and the verdict.
+*
+* @param result - The checkpoint's outcome.
+* @returns `pixels same`, or `pixels different 0.42% (rendering)`.
+* @example
+* ```ts
+* pixelText({ name: "open", state: "same", describe: "same", pixels: "different", pixelRatio: 0.0042, verdict: "rendering" });
+* // "pixels different 0.42% (rendering)"
+* ```
+*/
+function pixelText(result) {
+	if (result.pixels !== "different") return `pixels ${result.pixels}`;
+	return `pixels different ${result.pixelRatio === void 0 ? "at size" : `${(result.pixelRatio * 100).toFixed(2)}%`} (${result.verdict ?? "behaviour"})`;
+}
+/**
+* Writes the line of one checkpoint. The first difference is the state's when the state
+* differs, the describe's otherwise.
+*
+* @param test - The test name.
+* @param result - The checkpoint's outcome.
+* @returns `reward-popup/open: state same · describe same · pixels skipped`.
+*/
+function checkpointLine(test, result) {
+	const stateFirst = result.state === "different" ? result.first : void 0;
+	const describeFirst = result.state === "different" ? void 0 : result.first;
+	return [
+		`${test}/${result.name}:`,
+		outcomeText("state", result.state, stateFirst),
+		"·",
+		outcomeText("describe", result.describe, describeFirst),
+		"·",
+		pixelText(result)
+	].join(" ");
+}
+/**
+* Tells whether a checkpoint passed: no comparison found a difference.
+*
+* @param result - The checkpoint's outcome.
+* @returns True when nothing is `"different"`.
+*/
+function passed(result) {
+	return [
+		result.state,
+		result.describe,
+		result.pixels
+	].every((outcome) => outcome !== "different");
+}
+/**
+* Prints one line per checkpoint, and the error of a test that ended early.
+*
+* @param ui - Where the lines go.
+* @param results - The results of the run.
+*/
+function printResults(ui, results) {
+	for (const result of results) {
+		for (const checkpoint of result.checkpoints) ui.check(passed(checkpoint), checkpointLine(result.name, checkpoint));
+		if (result.error !== void 0) ui.error(result.error);
+	}
+}
+/**
+* Runs the browser leg after the headless one. When the leg fails as a whole, the lines of the
+* headless leg are printed before its error is thrown, so they are not lost.
+*
+* @param ui - Where the lines go.
+* @param setup - How to build a game, and the dev page.
+* @param tests - The selected tests.
+* @param run - The run options.
+* @param headless - The results of the headless leg.
+* @returns The results with their pixel fields.
+* @throws {Error} Whatever fails the browser leg.
+*/
+async function withPixelLeg(ui, setup, tests, run, headless) {
+	try {
+		return await runBrowserLeg(setup, tests, run, headless);
+	} catch (error) {
+		printResults(ui, headless);
+		throw error;
+	}
+}
+/**
+* Runs visual tests: the headless leg over every selected test, then the browser leg over the
+* same tests when `pixels` is on (by default only with a `page` on a Mac). A checkpoint saves
+* `state.json` and `describe.json` in `<dir>/<test>/<checkpoint>/`, and the browser leg
+* `screen.webp`, lossless: a missing file is written, `--update` rewrites every file of the tests
+* run, a JSON file is compared exactly. The browser leg opens the dev page in Chrome with WebGPU
+* through `playwright-core`, pauses its game, plays each test there on stepped frames of 1000/60
+* ms, so two runs see the same game time, checks the page's state against `state.json` and
+* compares the picture in the page: a pixel differs above `tolerance.threshold`, and the screen
+* differs when more than `tolerance.ratio` of its pixels do; `screen.actual.webp` and
+* `screen.diff.webp` are written beside the baseline then. A pixel difference over the same state
+* and describe is a rendering regression (`verdict: "rendering"`). One line per checkpoint goes
+* to the branded console; the script sets the exit code from `ok`.
+*
+* @param setup - How to build a game: a fresh, unstarted app per test, and the dev page.
+* @param tests - Every visual test of the game.
+* @param options - Overrides of the flags of `argv` and of the defaults.
+* @returns The report: `ok` when no test failed and nothing is `"different"`.
+* @throws {Error} When a test is not well formed, two tests share a name, `only` names no test,
+*   a flag misses its value, or the browser leg fails as a whole: no `page`, no
+*   `playwright-core`, no Chrome, or a page that does not open, expose `game` and `doors`, start,
+*   draw with WebGPU or stop loading.
+* @example
+* ```ts
+* // tests/visual/run.ts of a game, `bun tests/visual/run.ts --update` on a Mac
+* const report = await runVisualTests(
+*   { app: () => createScreenGame().app, page: { url: "http://localhost:3000/" } },
+*   [rewardPopup]
+* );
+* report.tests[0]?.checkpoints[0]; // { name: "open", state: "written", describe: "written", pixels: "written" }
+* ```
+*/
+async function runVisualTests(setup, tests, options = {}) {
+	const run = resolveVisualOptions(setup, options);
+	const selected = selectTests(tests, run.only);
+	const ui = createBrandConsole();
+	const headless = await runHeadlessLeg(setup, selected, run);
+	const results = run.pixels ? await withPixelLeg(ui, setup, selected, run, headless) : headless;
+	printResults(ui, results);
+	return {
+		ok: results.every((result) => result.error === void 0 && result.checkpoints.every((checkpoint) => passed(checkpoint))),
+		tests: results
+	};
+}
+//#endregion
+export { createHeadless, defineVisualTest, fakeClock, memory, parseVisualArgv, runRepro, runVisualTests, saveOf, stepFrames };