@moku-labs/game 0.11.0 → 0.13.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";
@@ -230,13 +230,15 @@ function importLine(binding, specifier) {
 *
 * @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();
@@ -250,9 +252,9 @@ function devMain(settings, sources) {
 	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, {",
@@ -353,6 +355,11 @@ const FORWARDED = [
 const STOPPING = ["SIGINT", "SIGTERM"];
 /** How often the dev child checks that its parent still runs. */
 const PARENT_CHECK_MS = 1e3;
+/**
+* The dev manifest `moku-game keys` writes, relative to the game folder, next to
+* `generated/assets.ts`. The dev server answers `/manifest.json` with it.
+*/
+const DEV_MANIFEST = "generated/manifest.json";
 /** The folders a `.dev.ts` module is never looked for in. */
 const NO_DEV_MODULES = /^(?:node_modules|dist|generated|tests|__tests__)$/;
 /** A `.gitignore` line that keeps `.moku/` of its own folder out. */
@@ -514,47 +521,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,
@@ -656,13 +668,30 @@ function devChildCommand(run, page, deps) {
 async function serveParent(run, deps) {
 	const settings = await loadGame(run.root);
 	const hasPack = isFile(path.join(run.root, "dist", "assets", "manifest.json"));
-	const hasManifest = isFile(path.join(run.root, "manifest.json"));
+	const hasManifest = isFile(path.join(run.root, DEV_MANIFEST));
 	if (run.packed && !hasPack) throw new Error(`[game] dev: no packed build in "${path.join(run.root, "dist", "assets")}".\n  Run "moku-game pack" first.`);
-	if (!run.packed && !hasManifest) deps.ui.warn(`[game] dev: no manifest.json in "${run.root}".\n  Run "moku-game keys" first.`);
+	if (!run.packed && !hasManifest) deps.ui.warn(`[game] dev: no ${DEV_MANIFEST} 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"
@@ -674,11 +703,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();
@@ -731,15 +760,19 @@ 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 on `/manifest.json`, and the files of the served folder as static files. The manifest
+* is the dev manifest `generated/manifest.json` of the game, or `manifest.json` of `dist/assets`
+* with `--packed`; its paths are relative to the served folder. 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.
 */
 function serveOn(run, page) {
 	const base = run.packed ? path.join(run.root, "dist", "assets") : run.root;
+	const manifest = path.join(base, run.packed ? "manifest.json" : DEV_MANIFEST);
 	try {
 		return Bun.serve({
 			hostname: "127.0.0.1",
@@ -747,7 +780,7 @@ function serveOn(run, page) {
 			development: true,
 			routes: {
 				"/": page,
-				"/manifest.json": () => fileResponse(path.join(base, "manifest.json"))
+				"/manifest.json": () => fileResponse(manifest)
 			},
 			fetch: (request) => fileResponse(staticPath(base, new URL(request.url).pathname))
 		});
@@ -757,6 +790,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.
 *
@@ -765,17 +814,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));
 	});
 }
@@ -853,7 +899,7 @@ function hasEnglishStrings(root, settings) {
 	return [...featureFolders, ...layerFolders].some((folder) => statSync(path.join(folder, "strings", "en.json"), { throwIfNoEntry: false })?.isFile() === true);
 }
 /**
-* The flags of the asset scan for `moku-game keys`: the dev manifest beside the game, the
+* The flags of the asset scan for `moku-game keys`: the dev manifest in `generated/`, the
 * pseudo-locale when the game has an English string file, and `--check` for a check run.
 *
 * @param root - The game folder.
@@ -862,7 +908,7 @@ function hasEnglishStrings(root, settings) {
 * @returns The flags for the scanner's command line.
 * @example
 * ```ts
-* keysArguments("/g", resolveConfig({ page: { title: "T" } }), true).slice(4); // ["--manifest", "/g/manifest.json", "--check"]: no strings
+* keysArguments("/g", resolveConfig({ page: { title: "T" } }), true).slice(4); // ["--manifest", "/g/generated/manifest.json", "--check"]: no strings
 * keysArguments("/g", resolveConfig({ page: { title: "T" } }), false).at(-1); // "--pseudo" once /g/features/home/strings/en.json exists
 * ```
 */
@@ -870,7 +916,7 @@ function keysArguments(root, settings, check) {
 	return [
 		...scanArguments(root, settings),
 		"--manifest",
-		path.join(root, "manifest.json"),
+		path.join(root, DEV_MANIFEST),
 		...hasEnglishStrings(root, settings) ? ["--pseudo"] : [],
 		...check ? ["--check"] : []
 	];
@@ -1086,13 +1132,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
+*   `generated/manifest.json`.
+*/
+async function writeVisualPage(page, resolve) {
+	const settings = await loadGame(page.root);
+	const manifest = path.join(page.root, DEV_MANIFEST);
+	if (statSync(manifest, { throwIfNoEntry: false })?.isFile() !== true) throw new Error(`[game] visual: no ${DEV_MANIFEST} 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 = [
@@ -1121,15 +1342,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 = [
@@ -1138,6 +1382,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. */
@@ -1151,8 +1399,11 @@ const USAGE = [
 	"  native build <target> [--simulator]   build the native app (ios, macos, android)",
 	"  native dev <target>                   run the native shell on the dev server",
 	"  native doctor | native clean          check or remove the native project",
-	"  keys [--check]                        write generated/assets.ts and manifest.json",
+	"  keys [--check]                        write generated/assets.ts and generated/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>."
@@ -1161,7 +1412,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);
@@ -1238,7 +1489,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));
@@ -1354,6 +1605,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.
 *
@@ -1392,7 +1678,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": {
@@ -1407,6 +1693,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);
 	}
 }
 /**
@@ -1419,8 +1706,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.
@@ -1435,7 +1722,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);
@@ -1593,15 +1880,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.
 */
@@ -1634,13 +1921,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.
@@ -1648,6 +1936,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
 * ```
 */

package/dist/{commands-C4QlqijJ.d.mts → commands-DvFr8Uwp.d.mts}

@@ -1,6 +1,6 @@
 import { A as Api$2, E as DebugSwitches, Ot as Bookmark, h as Api$1, jt as FlowState, ln as Api, vn as Time, w as Captured } from "./types-ZQLYXo5X.mjs";
-import { a as AudioApi, r as UiApi, v as ScenesApi, x as AnimApi } from "./types-BM4shh8K.mjs";
-import { A as InputApi } from "./types-BUwDHKXm.mjs";
+import { a as AudioApi, r as UiApi, v as ScenesApi, x as AnimApi } from "./types-D_2G6Q68.mjs";
+import { A as InputApi } from "./types-BrTpz9oL.mjs";
 import { t as HeadlessApp } from "./headless-G4nuZ-xz.mjs";
 import { n as Command, r as ControlApp } from "./types-DAdwEJMp.mjs";
 

package/dist/control.d.mts

@@ -1,6 +1,6 @@
 import { t as HeadlessApp } from "./headless-G4nuZ-xz.mjs";
 import { i as InputArguments, n as Command, o as InputSchema, s as Ran } from "./types-DAdwEJMp.mjs";
-import { t as commands } from "./commands-C4QlqijJ.mjs";
+import { t as commands } from "./commands-DvFr8Uwp.mjs";
 import { t as defineCommand } from "./define-CCc0ozKe.mjs";
 
 //#region src/plugins/flow/doors/dev.d.ts