@moku-labs/game 0.10.0 → 0.12.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 import { t as resolveConfig } from "./config-CdARrrhU.mjs";
-import { a as runCli$1, i as compileStrings, n as importStrings, t as exportStrings } from "./assets-BHwTLVta.mjs";
+import { a as runCli$1, i as compileStrings, n as importStrings, t as exportStrings } from "./assets-DYiKxPBX.mjs";
 import { constants, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import path from "node:path";
 import { createBrandConsole } from "@moku-labs/common/cli";
@@ -13,6 +13,17 @@ const SAFE_VALUE = /^[#\w(),.%\s-]+$/;
 /** The files of `tests/scenarios/` that are not scenarios. */
 const NOT_SCENARIO = /\.(?:test|spec|d)\.ts$|^index\.ts$/;
 /**
+* The entry of `@moku-labs/system` each system plugin loads from, in the order the shell composes
+* them.
+*/
+const SYSTEM_ENTRIES = [
+	["lifecycle", "lifecycle"],
+	["back", "back"],
+	["haptics", "haptics"],
+	["keepAwake", "keep-awake"],
+	["store", "store"]
+];
+/**
 * Escapes the five characters HTML reads as markup.
 *
 * @param text - The text.
@@ -133,7 +144,7 @@ function scenarioFiles(files) {
 * Whether the page needs the system shell: a system plugin is named, or the save is the store.
 *
 * @param settings - The resolved `config.ts`.
-* @returns True when `main.ts` imports `systemShell`.
+* @returns True when `main.ts` imports `systemShellOf`.
 * @example
 * ```ts
 * needsShell(resolveConfig({ page: { title: "T" }, save: "store" })); // true
@@ -143,6 +154,26 @@ function needsShell(settings) {
 	return settings.system.length > 0 || settings.save === "store";
 }
 /**
+* The `system` option of `startPage`: `systemShellOf` over the loader of the package and one
+* loader per plugin the shell composes, in the fixed order. The store is one when `config.system`
+* names it or the save is the store. Only these `import()`s are written, so the page bundles no
+* other plugin and never needs its native package.
+*
+* @param settings - The resolved `config.ts`.
+* @returns The option, indented two spaces, with no comma after it.
+* @example
+* ```ts
+* shellOption(resolveConfig({ page: { title: "T" }, system: ["haptics"] })).split("\n")[2]; // '    haptics: () => import("@moku-labs/system/haptics")'
+* ```
+*/
+function shellOption(settings) {
+	return [
+		"  system: systemShellOf({",
+		["    system: () => import(\"@moku-labs/system\")", ...SYSTEM_ENTRIES.filter(([name]) => settings.system.includes(name) || name === "store" && settings.save === "store").map(([name, entry]) => `    ${name}: () => import("@moku-labs/system/${entry}")`)].join(",\n"),
+		"  })"
+	].join("\n");
+}
+/**
 * The imports of `main.ts` every page has: the page entry, the shell when needed, the game and its
 * config.
 *
@@ -157,7 +188,7 @@ function needsShell(settings) {
 function pageImports(settings, toRoot) {
 	return [
 		"import { startPage } from \"@moku-labs/game/app/page\";",
-		...needsShell(settings) ? ["import { systemShell } from \"@moku-labs/game/app/system\";"] : [],
+		...needsShell(settings) ? ["import { systemShellOf } from \"@moku-labs/game/app/system\";"] : [],
 		`import game from "${toRoot}index.ts";`,
 		`import config from "${toRoot}config.ts";`
 	];
@@ -194,34 +225,36 @@ function importLine(binding, specifier) {
 /**
 * The `main.ts` of the dev page: the dev flag first, then the page entry, the game, its config,
 * one import per scenario, and, with agents, one per `.dev` module and one per agent. It calls
-* `startPage` with the scenarios by file stem, the shell when the game needs it, the agents and
-* the `.dev` modules.
+* `startPage` with the scenarios by file stem, the shell with the loaders of the named plugins
+* when the game needs it, the agents and the `.dev` modules.
 *
 * @param settings - The resolved `config.ts`.
 * @param sources - The scenario files, the `.dev` modules and the agents.
+* @param toRoot - The path from `main.ts` to the game folder: `"../"` for `.moku/`, `"../../"`
+*   for the page of `moku-game visual` in `.moku/visual/`.
 * @returns The text of `.moku/main.ts`.
 * @example
 * ```ts
 * devMain(resolveConfig({ page: { title: "T" } }), { scenarios: ["ready.ts"], devModules: [] }).includes('scenarios: { "ready": scenario0 }'); // true
 * ```
 */
-function devMain(settings, sources) {
+function devMain(settings, sources, toRoot = "../") {
 	const scenarios = scenarioFiles(sources.scenarios);
 	const agents = sources.agents ?? [];
 	const devModules = agents.length === 0 ? [] : sources.devModules.toSorted();
 	const keys = scenarios.map((file, index) => `${JSON.stringify(file.slice(0, -3))}: scenario${index}`);
 	const options = [
 		`  scenarios: ${keys.length === 0 ? "{}" : `{ ${keys.join(", ")} }`}`,
-		...needsShell(settings) ? ["  system: systemShell"] : [],
+		...needsShell(settings) ? [shellOption(settings)] : [],
 		...agents.length === 0 ? [] : [`  agents: [${numbered("agent", agents.length)}]`],
 		...devModules.length === 0 ? [] : [`  devModules: [${numbered("devModule", devModules.length)}]`]
 	];
 	return [
 		WRITTEN,
 		"import \"./dev.ts\";",
-		...pageImports(settings, "../"),
-		...scenarios.map((file, index) => importLine(`scenario${index}`, `../tests/scenarios/${file}`)),
-		...devModules.map((file, index) => importLine(`* as devModule${index}`, `../${file}`)),
+		...pageImports(settings, toRoot),
+		...scenarios.map((file, index) => importLine(`scenario${index}`, `${toRoot}tests/scenarios/${file}`)),
+		...devModules.map((file, index) => importLine(`* as devModule${index}`, `${toRoot}${file}`)),
 		...agents.map((agent, index) => importLine(`agent${index}`, agent)),
 		"",
 		"await startPage(game, config, {",
@@ -232,8 +265,8 @@ function devMain(settings, sources) {
 }
 /**
 * The `main.ts` of the production page: the page entry, the game and its config, and the shell
-* when the game needs it. No dev flag, no scenario, no agent, no `.dev` module, no door: none of
-* them ships.
+* with the loaders of the named plugins when the game needs it. No dev flag, no scenario, no
+* agent, no `.dev` module, no door: none of them ships.
 *
 * @param settings - The resolved `config.ts`.
 * @returns The text of the in-memory `.moku/build/main.ts`.
@@ -243,11 +276,15 @@ function devMain(settings, sources) {
 * ```
 */
 function buildMain(settings) {
-	const call = needsShell(settings) ? "await startPage(game, config, { system: systemShell });" : "await startPage(game, config);";
+	const call = needsShell(settings) ? [
+		"await startPage(game, config, {",
+		shellOption(settings),
+		"});"
+	] : ["await startPage(game, config);"];
 	return [
 		...pageImports(settings, "../../"),
 		"",
-		call,
+		...call,
 		""
 	].join("\n");
 }
@@ -479,47 +516,52 @@ function writeIfChanged(file, text) {
 * @param root - The game folder.
 * @param settings - The resolved config.
 * @param agents - The agent modules, when the page has any.
+* @param toRoot - The path from `main.ts` to the game folder.
 * @returns The text.
 */
-function mainOf(root, settings, agents) {
+function mainOf(root, settings, agents, toRoot = "../") {
 	const scenarios = scenarioNamesOf(root);
 	return agents === void 0 || agents.length === 0 ? devMain(settings, {
 		scenarios,
 		devModules: []
-	}) : devMain(settings, {
+	}, toRoot) : devMain(settings, {
 		scenarios,
 		devModules: devModulesOf(root),
 		agents
-	});
+	}, toRoot);
 }
 /**
 * Writes the dev page of a checked game into `<game>/.moku/`: `index.html`, `dev.ts`, `main.ts`
-* and `bunfig.toml`. Every text is made before the first write, so a refused value writes
-* nothing.
+* and `bunfig.toml`. `moku-game visual` writes its own page into `.moku/visual/`, so the page of
+* `dev` or of the editor stays as it is; the links of the page reach the game from its depth.
+* Every text is made before the first write, so a refused value writes nothing.
 *
 * @param root - The game folder, absolute.
 * @param settings - The resolved config.
 * @param options - The agents, the preloads and the extra plugins, absolute.
 * @param resolve - Bun's resolver, to find the hot plugin.
+* @param page - The folder of the page under the game, `/` separated: `.moku` by default.
 * @returns The paths of the HTML and the bunfig.
 * @throws {Error} When the hot plugin does not resolve, a preload or plugin is not a file, or a
 *   page value is refused.
 */
-function writePage(root, settings, options, resolve) {
+function writePage(root, settings, options, resolve, page = ".moku") {
 	const preload = options.preload ?? [];
 	const servePlugins = options.servePlugins ?? [];
 	checkFiles("--preload", preload);
 	checkFiles("--serve-plugin", servePlugins);
-	const folder = path.join(root, ".moku");
+	const segments = page.split("/");
+	const toRoot = "../".repeat(segments.length);
+	const folder = path.join(root, ...segments);
 	const html = path.join(folder, "index.html");
 	const bunfig = path.join(folder, "bunfig.toml");
 	const texts = [
 		[html, pageHtml(settings.page, {
-			toRoot: "../",
+			toRoot,
 			script: "./main.ts"
 		})],
 		[path.join(folder, "dev.ts"), devFlag()],
-		[path.join(folder, "main.ts"), mainOf(root, settings, options.agents)],
+		[path.join(folder, "main.ts"), mainOf(root, settings, options.agents, toRoot)],
 		[bunfig, bunfigText({
 			hotPlugin: hotPluginOf(root, resolve),
 			servePlugins,
@@ -626,8 +668,25 @@ async function serveParent(run, deps) {
 	if (!run.packed && !hasManifest) deps.ui.warn(`[game] dev: no manifest.json in "${run.root}".\n  Run "moku-game keys" first.`);
 	const page = writePage(run.root, settings, run, deps.resolve);
 	if (!ignoresMoku(run.root)) deps.ui.warn("[game] dev: add \".moku/\" to .gitignore. moku-game writes its dev page there.");
-	const child = deps.spawn(devChildCommand(run, page, deps), {
+	return runChild(devChildCommand(run, page, deps), deps, {
 		cwd: run.root,
+		whileRunning: () => watchScenarios(run.root, settings, deps)
+	});
+}
+/**
+* Runs the bin again as a marked child, `MOKU_GAME_CHILD=1`, in its own process group: Ctrl+C
+* reaches the parent, which hands it and the other stop signals on. `dev` and `visual` run their
+* page server this way, under the page's bunfig.
+*
+* @param command - The words of the command: the Bun, its flags, the bin and its arguments.
+* @param deps - The spawn, the signals and the environment.
+* @param child - The working directory, and what lives as long as the child.
+* @returns The exit code of the child.
+* @throws {Error} When the child does not start.
+*/
+async function runChild(command, deps, child) {
+	const started = deps.spawn(command, {
+		cwd: child.cwd,
 		env: {
 			...deps.env,
 			MOKU_GAME_CHILD: "1"
@@ -639,11 +698,11 @@ async function serveParent(run, deps) {
 		],
 		detached: true
 	});
-	const removers = FORWARDED.map((signal) => deps.onSignal(signal, () => child.kill(signal)));
+	const removers = FORWARDED.map((signal) => deps.onSignal(signal, () => started.kill(signal)));
 	let watcher;
 	try {
-		watcher = watchScenarios(run.root, settings, deps);
-		return await child.exited;
+		watcher = child.whileRunning?.();
+		return await started.exited;
 	} finally {
 		watcher?.close();
 		for (const remove of removers) remove();
@@ -696,10 +755,11 @@ function fileResponse(file) {
 }
 /**
 * Starts the dev server on `127.0.0.1` only, never on every interface: the page on `/`, the
-* manifest of the served folder on `/manifest.json`, and its files as static files.
+* manifest of the served folder on `/manifest.json`, and its files as static files. The dev child
+* and `moku-game visual` serve the page with it.
 *
 * @param run - The flags of the run.
-* @param page - The page bundle the child imported.
+* @param page - The page bundle the process imported.
 * @returns The server.
 * @throws {Error} When the port is in use.
 */
@@ -722,6 +782,22 @@ function serveOn(run, page) {
 	}
 }
 /**
+* Watches the parent of a child run: a parent that died hands the child to another process, so
+* its parent id changes. The dev child and the visual child stop their server then.
+*
+* @param onGone - Called once when the parent is gone.
+* @returns Stops watching.
+*/
+function watchParent(onGone) {
+	const parent = process.ppid;
+	const timer = setInterval(() => {
+		if (process.ppid === parent) return;
+		clearInterval(timer);
+		onGone();
+	}, PARENT_CHECK_MS);
+	return () => clearInterval(timer);
+}
+/**
 * Waits until the dev child should stop: Ctrl+C, a stop signal, or a parent that died (its
 * parent id changed). Then stops the server.
 *
@@ -730,17 +806,14 @@ function serveOn(run, page) {
 * @returns Resolves to the exit code `0` once the server stopped.
 */
 function untilStopped(server, deps) {
-	const parent = process.ppid;
 	return new Promise((resolve) => {
 		const removers = [];
-		const timer = setInterval(() => {
-			if (process.ppid !== parent) stop();
-		}, PARENT_CHECK_MS);
 		const stop = () => {
-			clearInterval(timer);
+			unwatch();
 			for (const remove of removers.splice(0)) remove();
 			resolve(server.stop(true).then(() => 0));
 		};
+		const unwatch = watchParent(stop);
 		for (const signal of STOPPING) removers.push(deps.onSignal(signal, stop));
 	});
 }
@@ -1051,13 +1124,188 @@ async function runBuild(run, deps) {
 	return 0;
 }
 //#endregion
+//#region src/app/visual.ts
+/**
+* @file `moku-game visual`: the visual tests of a game from the bin. It imports the tests module,
+* `tests/visual/index.ts` by default, whose default export is `{ app, tests }`, the two arguments
+* of `runVisualTests`: `app` is a `VisualSetup`. The flags of the runner are read by
+* `parseVisualArgv`. When the pixel leg runs without `--url`, the command writes its own dev page
+* into `.moku/visual/`, so the page of `dev` or of the editor stays as it is, runs the bin again
+* under that page's bunfig as `dev` does, and the child serves the page with the server of `dev`
+* on a free port and stops it after. Node and Bun only: the bin bundles it.
+*/
+/** The baselines of a game, under the game folder. */
+const BASELINES = path.join("tests", "visual", "baselines");
+/** The folder of the visual page under the game: its own, beside the page of `dev`. */
+const VISUAL_PAGE = ".moku/visual";
+/**
+* Tells whether a value is a setup of the runner: an object with an `app` function.
+*
+* @param value - The `app` of the module.
+* @returns True for a `VisualSetup`.
+*/
+function isSetup(value) {
+	return typeof value === "object" && value !== null && "app" in value && typeof value.app === "function";
+}
+/**
+* Reads the default export of a tests module: `app` is the setup of the runner, `{ app, page? }`,
+* and `tests` is a list. Each test is checked by the runner.
+*
+* @param value - The default export.
+* @returns The suite, or `undefined` for another shape.
+*/
+function suiteOf(value) {
+	if (typeof value !== "object" || value === null || !("app" in value) || !("tests" in value)) return;
+	const { app, tests } = value;
+	return Array.isArray(tests) && isSetup(app) ? {
+		setup: app,
+		tests
+	} : void 0;
+}
+/**
+* Imports the tests module of the run.
+*
+* @param file - The module, absolute.
+* @param cwd - The working directory, to name the module in the message.
+* @returns The setup and the tests.
+* @throws {Error} When the module is missing or its default export is not `{ app, tests }`.
+*/
+async function loadSuite(file, cwd) {
+	const suite = suiteOf((statSync(file, { throwIfNoEntry: false })?.isFile() === true ? await import(pathToFileURL(file).href) : void 0)?.default);
+	if (suite === void 0) throw new Error(`[game] visual: ${path.relative(cwd, file)} must export default { app, tests }.\n  app is a VisualSetup { app, page? }: export default { app: { app: () => game.screen().app }, tests }.`);
+	return suite;
+}
+/**
+* Writes the visual page of the game into `.moku/visual/`: `index.html`, `dev.ts`, `main.ts` and
+* `bunfig.toml`, the hot plugin, the serve plugins and the preloads in it, as `dev` writes its page.
+*
+* @param page - The game folder, the preloads and the serve plugins.
+* @param resolve - Bun's resolver, to find the hot plugin.
+* @returns The paths of the HTML and the bunfig.
+* @throws {Error} The errors of `moku-game dev` before its server starts, and a game without
+*   `manifest.json`.
+*/
+async function writeVisualPage(page, resolve) {
+	const settings = await loadGame(page.root);
+	const manifest = path.join(page.root, "manifest.json");
+	if (statSync(manifest, { throwIfNoEntry: false })?.isFile() !== true) throw new Error(`[game] visual: no manifest.json in "${page.root}".\n  Run "moku-game keys" first.`);
+	return writePage(page.root, settings, {
+		preload: page.preload,
+		servePlugins: page.servePlugins
+	}, resolve, VISUAL_PAGE);
+}
+/**
+* Writes the visual page and serves it in this process on a free port, as the dev child serves
+* its page. It runs in the child that runs under the page's bunfig, so the hot plugin, the serve
+* plugins and the preloads apply.
+*
+* @param page - The game folder, the preloads and the serve plugins.
+* @param deps - Bun's resolver and the page loader.
+* @returns The running server.
+* @throws {Error} The errors of `writeVisualPage`.
+*/
+async function serveVisualPage(page, deps) {
+	const files = await writeVisualPage(page, deps.resolve);
+	const loaded = await deps.loadPage(files.html);
+	return serveOn({
+		root: page.root,
+		port: 0,
+		packed: false,
+		preload: page.preload,
+		servePlugins: page.servePlugins
+	}, loaded.default);
+}
+/**
+* Runs the bin again for a run that has to: under the visual page's bunfig when the page is
+* served, so it is bundled as `dev` bundles its page; with Bun's preloads otherwise.
+*
+* @param command - The run.
+* @param serves - True when the page is served for the run.
+* @param deps - The process seams.
+* @returns The exit code of the child.
+* @throws {Error} The errors of `writeVisualPage`.
+*/
+async function rerun(command, serves, deps) {
+	const page = serves ? await writeVisualPage(command, deps.resolve) : void 0;
+	const bun = page === void 0 ? command.preload.map((file) => `--preload=${file}`) : [`--config=${page.bunfig}`];
+	return runChild([
+		deps.execPath,
+		...bun,
+		...deps.self,
+		...command.argv
+	], deps, { cwd: deps.cwd });
+}
+/**
+* Plays the tests in this process: the headless leg, then the pixel leg against `--url` or the
+* page served here, which stops when the run ends or the parent of the run is gone.
+*
+* @param command - The run.
+* @param run - The runner, its flags, and whether the pixel leg runs.
+* @param deps - The process seams.
+* @returns `0` when the report is ok, `1` otherwise.
+* @throws {Error} When the tests module is refused, the page cannot be served, or the runner
+*   throws.
+*/
+async function play(command, run, deps) {
+	const suite = await loadSuite(command.tests, deps.cwd);
+	const dir = path.resolve(deps.cwd, run.flags.dir ?? path.join(command.root, BASELINES));
+	const server = run.serves ? await serveVisualPage(command, deps) : void 0;
+	const unwatch = server === void 0 ? void 0 : watchParent(() => server.stop(true));
+	const url = command.url ?? server?.url.href;
+	try {
+		const setup = url === void 0 ? suite.setup : {
+			...suite.setup,
+			page: {
+				...suite.setup.page,
+				url
+			}
+		};
+		return (await run.visual.runVisualTests(setup, suite.tests, {
+			...run.flags,
+			pixels: run.pixels,
+			dir,
+			argv: []
+		})).ok ? 0 : 1;
+	} finally {
+		unwatch?.();
+		await server?.stop(true);
+	}
+}
+/**
+* Runs `moku-game visual`: the headless leg, then the pixel leg on a Mac (or with `--pixels`)
+* against `--url` or the page served for the run. A run that serves the page runs the bin again
+* under `.moku/visual/bunfig.toml`, as `dev` does, and a run with `--preload` with the preloads;
+* the marked child plays the tests. The baselines live in `<game>/tests/visual/baselines/` unless
+* `--dir` names another folder.
+*
+* @param command - The run.
+* @param deps - The process seams.
+* @returns `0` when the report is ok, `1` otherwise, or the exit code of the child.
+* @throws {Error} When the tests module is refused, a flag misses its value, the page cannot be
+*   served, or the runner throws.
+*/
+async function runVisual(command, deps) {
+	const visual = await deps.visual();
+	const flags = visual.parseVisualArgv(command.flags);
+	const pixels = flags.pixels ?? process.platform === "darwin";
+	const serves = pixels && command.url === void 0;
+	if (!(deps.env.MOKU_GAME_CHILD === "1") && (serves || command.preload.length > 0)) return rerun(command, serves, deps);
+	return play(command, {
+		visual,
+		flags,
+		pixels,
+		serves
+	}, deps);
+}
+//#endregion
 //#region src/app/cli.ts
 /**
 * @file The command line of `moku-game`: the arguments read per command with `node:util`
-* `parseArgs`, then one of `dev`, `build`, `native <verb>`, `keys`, `pack` or `help`. Every seam
-* of the process (the console, the environment, spawning, signals, the watcher, the asset
-* scanner, native, Bun's resolver) comes in as `deps`, so a test runs a command with stubs. It
-* returns the exit code and never exits itself. A plain function, on no API.
+* `parseArgs`, then one of `dev`, `build`, `native <verb>`, `keys`, `pack`, `visual` or `help`.
+* Every seam of the process (the console, the environment, spawning, signals, the watcher, the
+* asset scanner, native, Bun's resolver, the visual test runner) comes in as `deps`, so a test
+* runs a command with stubs. It returns the exit code and never exits itself. A plain function,
+* on no API.
 */
 /** The flags every command takes. */
 const GLOBAL_OPTIONS = [
@@ -1086,15 +1334,38 @@ const ALL_OPTIONS = {
 	out: { type: "string" },
 	simulator: { type: "boolean" },
 	check: { type: "boolean" },
-	"no-cache": { type: "boolean" }
+	"no-cache": { type: "boolean" },
+	tests: { type: "string" },
+	url: { type: "string" },
+	update: { type: "boolean" },
+	only: {
+		type: "string",
+		multiple: true
+	},
+	"no-pixels": { type: "boolean" },
+	pixels: { type: "boolean" },
+	dir: { type: "string" },
+	webgl: { type: "boolean" }
 };
+/** The flags of `visual` that `parseVisualArgv` reads, in the runner's words. */
+const VISUAL_FLAGS = /^(?:update|only|no-pixels|pixels|dir|webgl)$/;
 /** The flags of one command besides the global ones. */
 const COMMAND_OPTIONS = {
 	dev: ["port", "packed"],
 	build: ["out"],
 	native: ["simulator"],
 	keys: ["check"],
-	pack: ["no-cache"]
+	pack: ["no-cache"],
+	visual: [
+		"tests",
+		"url",
+		"update",
+		"only",
+		"no-pixels",
+		"pixels",
+		"dir",
+		"webgl"
+	]
 };
 /** The native verbs, in the order the messages name them. */
 const NATIVE_VERBS = [
@@ -1103,6 +1374,10 @@ const NATIVE_VERBS = [
 	"doctor",
 	"clean"
 ];
+/** The command words, in the order the messages name them. */
+const COMMAND_NAMES = "dev, build, native, keys, pack, visual, help";
+/** The tests module of a game, under the game folder. */
+const VISUAL_TESTS = path.join("tests", "visual", "index.ts");
 /** The port of `moku-game dev` without `--port`. */
 const DEFAULT_PORT = "3000";
 /** The highest port number. */
@@ -1118,6 +1393,9 @@ const USAGE = [
 	"  native doctor | native clean          check or remove the native project",
 	"  keys [--check]                        write generated/assets.ts and manifest.json",
 	"  pack [--no-cache]                     pack the assets into dist/assets",
+	"  visual [--update] [--only <name>]     run tests/visual/index.ts: headless, pixels on a Mac",
+	"    [--no-pixels | --pixels] [--webgl] [--dir tests/visual/baselines]",
+	"    [--tests tests/visual/index.ts] [--url <url>]",
 	"  help                                  print this text",
 	"",
 	"Every command: --root <dir> (default .), --preload <path>, --serve-plugin <path>."
@@ -1126,7 +1404,7 @@ const USAGE = [
 * Tells whether a word is a command of the line that runs something.
 *
 * @param word - The first positional argument.
-* @returns True for `dev`, `build`, `native`, `keys` and `pack`.
+* @returns True for `dev`, `build`, `native`, `keys`, `pack` and `visual`.
 */
 function isCommand(word) {
 	return Object.hasOwn(COMMAND_OPTIONS, word);
@@ -1203,7 +1481,7 @@ function parseCommand(argv, cwd) {
 	const word = loose.positionals[0];
 	if (loose.values.help === true || word === "help") return "help";
 	if (word === void 0) return void 0;
-	if (!isCommand(word)) throw new Error(`[game] moku-game: no command "${word}". Name one of dev, build, native, keys, pack, help.`);
+	if (!isCommand(word)) throw new Error(`[game] moku-game: no command "${word}". Name one of ${COMMAND_NAMES}.`);
 	checkTokens(word, loose.tokens);
 	const { values, positionals } = parseStrict(argv);
 	const resolveAll = (files) => (files ?? []).map((file) => path.resolve(cwd, file));
@@ -1319,6 +1597,41 @@ async function runScan(parsed, deps) {
 	return deps.assets(argv);
 }
 /**
+* The flags of `visual` that `parseVisualArgv` reads, in the order given, each value after its
+* flag: `--dir=shots` becomes `--dir shots`.
+*
+* @param argv - The arguments after the bin, their flags checked.
+* @returns The flags of the runner.
+*/
+function visualFlags(argv) {
+	return parseLoose(argv).tokens.flatMap((token) => {
+		if (token.kind !== "option" || !VISUAL_FLAGS.test(token.name)) return [];
+		return token.value === void 0 ? [`--${token.name}`] : [`--${token.name}`, token.value];
+	});
+}
+/**
+* Runs `moku-game visual` with the tests module and the baselines of the game.
+*
+* @param argv - The arguments after the bin.
+* @param parsed - The command line.
+* @param deps - The process seams.
+* @returns `0` when every checkpoint passed, else `1`.
+*/
+function runVisualCommand(argv, parsed, deps) {
+	refuseExtra(parsed, 0);
+	const tests = parsed.values.tests ?? path.join(parsed.root, VISUAL_TESTS);
+	const url = parsed.values.url;
+	return runVisual({
+		argv,
+		root: parsed.root,
+		tests: path.resolve(deps.cwd, tests),
+		...url === void 0 ? {} : { url },
+		flags: visualFlags(argv),
+		preload: parsed.preload,
+		servePlugins: parsed.servePlugins
+	}, deps);
+}
+/**
 * Runs the bin once more with every `--preload` as a Bun preload, so the preload runs before the
 * engine loads. The re-run is marked, so it does not hop again.
 *
@@ -1357,7 +1670,7 @@ async function runParsed(argv, parsed, deps) {
 	const usesPlugins = parsed.command !== "keys" && parsed.command !== "pack";
 	checkFiles("--preload", parsed.preload);
 	if (usesPlugins) checkFiles("--serve-plugin", parsed.servePlugins);
-	if (parsed.command !== "dev" && parsed.preload.length > 0 && deps.env.MOKU_GAME_CHILD !== "1") return hop(argv, parsed, deps);
+	if (parsed.command !== "dev" && parsed.command !== "visual" && parsed.preload.length > 0 && deps.env.MOKU_GAME_CHILD !== "1") return hop(argv, parsed, deps);
 	switch (parsed.command) {
 		case "dev": return runServe(parsed, deps);
 		case "build": {
@@ -1372,6 +1685,7 @@ async function runParsed(argv, parsed, deps) {
 		case "native": return runNativeVerb(parsed, deps);
 		case "keys":
 		case "pack": return runScan(parsed, deps);
+		case "visual": return runVisualCommand(argv, parsed, deps);
 	}
 }
 /**
@@ -1384,8 +1698,8 @@ function printUsage(ui) {
 }
 /**
 * Runs one `moku-game` command line: reads the command and its flags, then runs `dev`, `build`,
-* `native <verb>`, `keys`, `pack` or `help`. Every failure is printed through the console as a
-* `[game] …` message; nothing exits the process.
+* `native <verb>`, `keys`, `pack`, `visual` or `help`. Every failure is printed through the
+* console as a `[game] …` message; nothing exits the process.
 *
 * @param argv - The arguments after the bin.
 * @param deps - The process seams.
@@ -1400,7 +1714,7 @@ async function runCommand(argv, deps) {
 		}
 		if (parsed === void 0) {
 			printUsage(deps.ui);
-			deps.ui.error("[game] moku-game: name a command: dev, build, native, keys, pack, help.");
+			deps.ui.error(`[game] moku-game: name a command: ${COMMAND_NAMES}.`);
 			return 1;
 		}
 		return await runParsed(argv, parsed, deps);
@@ -1558,15 +1872,15 @@ async function runNative(verb, settings, where, options) {
 //#region src/cli.ts
 /**
 * @file The `@moku-labs/game/cli` door, node and bun only: the `moku-game` bin and the editor's
-* seam. `runCli` runs one command line of `moku-game` (dev, build, native, keys, pack, help) in
-* this process; `preparePage` writes a game's dev page into `<game>/.moku/` for a server the
+* seam. `runCli` runs one command line of `moku-game` (dev, build, native, keys, pack, visual,
+* help) in this process; `preparePage` writes a game's dev page into `<game>/.moku/` for a server the
 * caller starts itself, as the editor does. It imports no Pixi, and the root entry never imports
 * it. The code lives in `app/`; this file wires the real process into it.
 */
 /**
 * The real process behind the command line: the branded console, the environment the bin
 * started with, Bun's spawn and resolver, the signals, `fs.watch`, the asset scanner with the
-* string tools, and native.
+* string tools, native, and the visual test runner, loaded only by `moku-game visual`.
 *
 * @returns The seams of this process.
 */
@@ -1599,13 +1913,14 @@ function processDeps() {
 		}, ui),
 		native: runNative,
 		resolve: (specifier, from) => Bun.resolveSync(specifier, from),
-		loadPage: (file) => import(file)
+		loadPage: (file) => import(file),
+		visual: () => import("./visual.mjs")
 	};
 }
 /**
 * Runs one `moku-game` command line in this process: `dev`, `build`, `native <verb>`, `keys`,
-* `pack` or `help`, with `--root`, `--preload` and `--serve-plugin` before or after the command
-* word. Every line goes through the branded console; nothing exits the process.
+* `pack`, `visual` or `help`, with `--root`, `--preload` and `--serve-plugin` before or after the
+* command word. Every line goes through the branded console; nothing exits the process.
 *
 * @param argv - The arguments after the bin.
 * @returns The exit code.
@@ -1613,6 +1928,7 @@ function processDeps() {
 * ```ts
 * // bin/moku-game.mjs in a game folder:
 * await runCli(["dev", "--port", "0"]); // 0 after Ctrl+C; stdout had "http://localhost:<port>/"
+* await runCli(["visual", "--no-pixels"]); // 0 when every checkpoint of tests/visual/index.ts is the same
 * await runCli(["help"]); // 0
 * ```
 */