@moku-labs/game 0.13.0 → 0.13.1

package/dist/cli.mjs

@@ -1,13 +1,20 @@
 import { t as resolveConfig } from "./config-CdARrrhU.mjs";
+import { r as watchTree, t as createBatcher, x as isSkippedFolder$1 } from "./watch-CB8IWDBi.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 { constants, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import path from "node:path";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { parseArgs } from "node:util";
 import { pathToFileURL } from "node:url";
+import { createHash } from "node:crypto";
 //#region src/app/generate.ts
 /** The first line of a generated file a person may open. */
 const WRITTEN = "// Written by moku-game dev. Do not edit.";
+/**
+* The stamp module of a game, a file of `<game>/.moku/`. One per game: the dev page and the page
+* of `moku-game visual` import the same one.
+*/
+const ASSETS_STAMP = "assets-stamp.ts";
 /** A colour or a language tag: it lands in a `<style>` and in attributes, so nothing else passes. */
 const SAFE_VALUE = /^[#\w(),.%\s-]+$/;
 /** The files of `tests/scenarios/` that are not scenarios. */
@@ -223,10 +230,24 @@ function importLine(binding, specifier) {
 	return `import ${binding} from ${JSON.stringify(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 with the loaders of the named plugins
-* when the game needs it, the agents and the `.dev` modules.
+* The path from a page under `.moku/` to `.moku/` itself, where the one stamp of a game lives.
+*
+* @param toRoot - The path from the page to the game folder.
+* @returns `"./"` for the dev page in `.moku/`, `"../"` for the page in `.moku/visual/`.
+* @example
+* ```ts
+* toStampFolder("../../"); // "../"
+* ```
+*/
+function toStampFolder(toRoot) {
+	return toRoot.slice(3) || "./";
+}
+/**
+* The `main.ts` of the dev page: the dev flag first, then the assets stamp, 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 with the loaders of the
+* named plugins when the game needs it, the agents and the `.dev` modules. The stamp import makes
+* the page reload when the keys watch writes a new stamp: an asset file changed.
 *
 * @param settings - The resolved `config.ts`.
 * @param sources - The scenario files, the `.dev` modules and the agents.
@@ -252,6 +273,7 @@ function devMain(settings, sources, toRoot = "../") {
 	return [
 		WRITTEN,
 		"import \"./dev.ts\";",
+		`import "${toStampFolder(toRoot)}${ASSETS_STAMP}";`,
 		...pageImports(settings, toRoot),
 		...scenarios.map((file, index) => importLine(`scenario${index}`, `${toRoot}tests/scenarios/${file}`)),
 		...devModules.map((file, index) => importLine(`* as devModule${index}`, `${toRoot}${file}`)),
@@ -302,6 +324,22 @@ function devFlag() {
 	return `${WRITTEN}\nglobalThis.__MOKU_GAME_DEV__ = true;\n`;
 }
 /**
+* The `assets-stamp.ts` module the dev `main.ts` imports: one string that changes when an asset
+* file of the game changes. The hot plugin takes it for a logic module, so a new stamp reloads the
+* page, and the page shows the new bytes of an image whose key stayed the same. The page starts
+* with the empty stamp; the keys watch writes the hash of the asset files.
+*
+* @param hash - The hash of the asset files, `""` before the first watch.
+* @returns The text of `.moku/assets-stamp.ts`.
+* @example
+* ```ts
+* assetsStamp(""); // '// Written by moku-game dev. Do not edit.\nexport default "";\n'
+* ```
+*/
+function assetsStamp(hash) {
+	return `${WRITTEN}\nexport default ${JSON.stringify(hash)};\n`;
+}
+/**
 * A TOML array of strings. `JSON.stringify` of a path is a valid TOML basic string, also for a
 * Windows path.
 *
@@ -338,12 +376,31 @@ function bunfigText(paths) {
 	].join("\n");
 }
 //#endregion
+//#region src/app/files.ts
+/**
+* @file The file write of the files `moku-game` generates for a game. The dev page and the stamp
+* of the keys watch go through it: a file the dev server watches is touched only when its text
+* changed. Node and Bun only: the bin bundles it.
+*/
+/**
+* Writes a file only when its text changed, so a second run wakes no watcher.
+*
+* @param file - The absolute path.
+* @param text - The text.
+*/
+function writeIfChanged(file, text) {
+	if (existsSync(file) && readFileSync(file, "utf8") === text) return;
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(file, text);
+}
+//#endregion
 //#region src/app/serve.ts
 /**
 * @file `moku-game dev`: the game folder read and checked, the dev page written into
-* `<game>/.moku/`, the parent that re-runs the bin under the generated bunfig, and the child that
-* serves the page with `Bun.serve`. The hot plugin comes from the engine the game resolves, so
-* the game writes no bunfig, no HTML and no dev file. Node and Bun only: the bin bundles it.
+* `<game>/.moku/`, the parent that starts the keys watch and re-runs the bin under the generated
+* bunfig, and the child that serves the page with `Bun.serve`. The hot plugin comes from the
+* engine the game resolves, so the game writes no bunfig, no HTML and no dev file. Node and Bun
+* only: the bin bundles it.
 */
 /** The signals the dev parent hands to its child. */
 const FORWARDED = [
@@ -356,8 +413,8 @@ 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.
+* The dev manifest `moku-game keys` and the keys watch of `moku-game dev` write, 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. */
@@ -505,17 +562,6 @@ function devModulesOf(root, relative = "") {
 	});
 }
 /**
-* Writes a file only when its text changed, so a second run wakes no watcher.
-*
-* @param file - The absolute path.
-* @param text - The text.
-*/
-function writeIfChanged(file, text) {
-	if (existsSync(file) && readFileSync(file, "utf8") === text) return;
-	mkdirSync(path.dirname(file), { recursive: true });
-	writeFileSync(file, text);
-}
-/**
 * The text of the dev `main.ts` for the game as it is on disk now.
 *
 * @param root - The game folder.
@@ -539,7 +585,9 @@ function mainOf(root, settings, agents, toRoot = "../") {
 * Writes the dev page of a checked game into `<game>/.moku/`: `index.html`, `dev.ts`, `main.ts`
 * 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.
+* Every text is made before the first write, so a refused value writes nothing. A game without
+* `.moku/assets-stamp.ts` gets the empty one, so the import of `main.ts` resolves with or without
+* a keys watch; a stamp that is there is the watch's and stays.
 *
 * @param root - The game folder, absolute.
 * @param settings - The resolved config.
@@ -573,15 +621,18 @@ function writePage(root, settings, options, resolve, page = ".moku") {
 			preload
 		})]
 	];
+	const stamp = path.join(root, ".moku", ASSETS_STAMP);
 	for (const [file, text] of texts) writeIfChanged(file, text);
+	if (!existsSync(stamp)) writeIfChanged(stamp, assetsStamp(""));
 	return {
 		html,
 		bunfig
 	};
 }
 /**
-* Reads and checks a game, then writes its dev page into `<game>/.moku/`. The editor's step and
-* the dev parent's step 3; it starts no server and no watcher.
+* Reads and checks a game, then writes its dev page into `<game>/.moku/`, the first
+* `assets-stamp.ts` with it. The editor's step and the dev parent's step 3; it starts no server
+* and no watcher.
 *
 * @param root - The game folder, absolute.
 * @param options - The agents, the preloads and the extra plugins, absolute.
@@ -656,9 +707,12 @@ function devChildCommand(run, page, deps) {
 	];
 }
 /**
-* The dev parent: checks the game, writes the page, re-runs the bin under the generated bunfig
-* with the game as its working directory, and watches the scenarios while the child runs. It
-* hands Ctrl+C and the other stop signals to the child and answers the child's exit code.
+* The dev parent: checks the game, starts the keys watch on the raw files, writes the page,
+* re-runs the bin under the generated bunfig with the game as its working directory, and watches
+* the scenarios while the child runs. The first scan of the keys watch writes
+* `generated/manifest.json` before the page is served, and a save of an asset or a strings file
+* scans again; `--packed` serves the pack and watches no keys. It hands Ctrl+C and the other stop
+* signals to the child and answers the child's exit code.
 *
 * @param run - The flags of the run.
 * @param deps - The process seams.
@@ -668,15 +722,18 @@ 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, 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 ${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.");
-	return runChild(devChildCommand(run, page, deps), deps, {
-		cwd: run.root,
-		whileRunning: () => watchScenarios(run.root, settings, deps)
-	});
+	const keys = run.packed ? void 0 : await deps.watchKeys(run.root, settings);
+	try {
+		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.");
+		return await runChild(devChildCommand(run, page, deps), deps, {
+			cwd: run.root,
+			whileRunning: () => watchScenarios(run.root, settings, deps)
+		});
+	} finally {
+		keys?.close();
+	}
 }
 /**
 * Runs the bin again as a marked child, `MOKU_GAME_CHILD=1`, in its own process group: Ctrl+C
@@ -749,21 +806,22 @@ function safeDecode(pathname) {
 	}
 }
 /**
-* Answers a request with a file, or a 404 for a missing or empty one.
+* Answers a request with a file, or a 404 for a missing or empty one. A file is never cached:
+* after a reload the page shows the new bytes of an edited image.
 *
 * @param file - The absolute path, or `undefined` for a refused path.
 * @returns The response.
 */
 function fileResponse(file) {
 	const found = file === void 0 ? void 0 : statSync(file, { throwIfNoEntry: false });
-	return file !== void 0 && found?.isFile() === true && found.size > 0 ? new Response(Bun.file(file)) : new Response("Not found", { status: 404 });
+	return file !== void 0 && found?.isFile() === true && found.size > 0 ? new Response(Bun.file(file), { headers: { "Cache-Control": "no-store" } }) : new Response("Not found", { status: 404 });
 }
 /**
 * Starts the dev server on `127.0.0.1` only, never on every interface: the page on `/`, the
-* 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.
+* manifest on `/manifest.json`, and the files of the served folder as static files, each with
+* `Cache-Control: no-store`. 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 process imported.
@@ -1311,9 +1369,9 @@ async function runVisual(command, deps) {
 * @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`, `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.
+* keys watch, 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 = [
@@ -1732,6 +1790,275 @@ async function runCommand(argv, deps) {
 	}
 }
 //#endregion
+//#region src/app/keys.ts
+/**
+* @file The keys watch of a game folder, behind `moku-game dev` and the editor's `watchKeys`: it
+* keeps `generated/` fresh while a dev page is open. A file event is only a trigger. When the
+* events stop for a quiet period, a batch walks the game and reads the size and the time stamp of
+* every asset file and every `strings/<locale>.json`; it runs the scan of `moku-game keys` only
+* when they differ from the batch before. After a scan it writes `.moku/assets-stamp.ts` from the
+* asset files, so the dev page reloads and shows the new bytes of an image. One scan runs at a
+* time, and a failed scan never stops the watch. A batch that scanned is followed by one more
+* walk: the platform reports only the first path of a burst of writes, so a save made in the same
+* instant as the scan's own writes under `generated/` may never be reported. The scan, `fs.watch`
+* and the console come in as seams, so a test drives it. Node and Bun only: the bin bundles it.
+*/
+/** The quiet period that closes a batch of file events. */
+const QUIET_MS = 100;
+/** The asset files the scanner reads, by extension. */
+const ASSET_FILE = /\.(?:png|webp|fnt|mp3|m4a)$/i;
+/** A strings file: a `.json` directly in a `strings/` folder. */
+const STRINGS_FILE = /(?:^|\/)strings\/[^/]+\.json$/;
+/**
+* Lists one folder of the walk.
+*
+* @param folder - The absolute folder.
+* @returns Its entries; none when it cannot be read or vanished during the walk.
+*/
+function entriesOf(folder) {
+	try {
+		return readdirSync(folder, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+}
+/**
+* Tells whether a file is an input of the scan: an asset file, or a strings file.
+*
+* @param file - The path relative to the game, with `/`.
+* @returns True for a file the watch stamps.
+* @example
+* ```ts
+* isInput("features/home/strings/en.json"); // true
+* ```
+*/
+function isInput(file) {
+	return ASSET_FILE.test(file) || STRINGS_FILE.test(file);
+}
+/**
+* Reads one folder of the walk and the folders below it, outside the skipped ones: every asset
+* file and every strings file joins the inputs with its stamp. Symlinks are not followed.
+*
+* @param root - The real game folder.
+* @param folder - The folder, relative to the game; `""` is the game folder.
+* @param walk - The inputs and the folders so far.
+*/
+function readFolder(root, folder, walk) {
+	walk.folders.push(folder);
+	for (const entry of entriesOf(path.join(root, folder))) {
+		const inGame = folder === "" ? entry.name : `${folder}/${entry.name}`;
+		if (entry.isDirectory() && !isSkippedFolder$1(entry.name)) readFolder(root, inGame, walk);
+		if (!entry.isFile() || !isInput(inGame)) continue;
+		const stats = statSync(path.join(root, inGame), { throwIfNoEntry: false });
+		if (stats !== void 0) walk.inputs.set(inGame, `${stats.size}:${stats.mtimeMs}`);
+	}
+}
+/**
+* Walks a game folder for the inputs of the scan.
+*
+* @param root - The real game folder.
+* @returns The stamps of the inputs, and the folders on the way.
+*/
+function walkInputs(root) {
+	const walk = {
+		inputs: /* @__PURE__ */ new Map(),
+		folders: []
+	};
+	readFolder(root, "", walk);
+	return walk;
+}
+/**
+* Lists the inputs that differ between two walks: added, removed, or saved again.
+*
+* @param before - The stamps of the walk before.
+* @param after - The stamps of this walk.
+* @returns The root-relative paths, sorted.
+* @example
+* ```ts
+* changedPaths(new Map([["a.png", "3:1"]]), new Map([["a.png", "4:2"], ["b.png", "1:1"]])); // ["a.png", "b.png"]
+* ```
+*/
+function changedPaths(before, after) {
+	return [.../* @__PURE__ */ new Set([...before.keys(), ...after.keys()])].filter((file) => before.get(file) !== after.get(file)).toSorted();
+}
+/**
+* Hashes the asset files of a walk: their paths, sizes and time stamps. The strings files stay
+* out, so a strings save leaves the hash as it is.
+*
+* @param inputs - The stamps of a walk.
+* @returns The SHA-1 as 40 hex digits.
+* @example
+* ```ts
+* assetsHash(new Map([["features/home/strings/en.json", "9:1"]])); // "da39a3ee5e6b4b0d3255bfef95601890afd80709": no asset file
+* ```
+*/
+function assetsHash(inputs) {
+	const assets = [...inputs].filter(([file]) => ASSET_FILE.test(file)).map(([file, stamp]) => `${file}:${stamp}`).toSorted();
+	return createHash("sha1").update(assets.join("\n")).digest("hex");
+}
+/**
+* The line of a later scan that worked: the first changed input, and how many more.
+*
+* @param changed - The changed inputs, sorted, at least one.
+* @returns The line.
+* @example
+* ```ts
+* changeLine(["features/ui/assets/a.png", "features/ui/assets/b.png"]); // "keys: features/ui/assets/a.png and 1 more"
+* ```
+*/
+function changeLine(changed) {
+	const more = changed.length - 1;
+	return more === 0 ? `keys: ${changed[0]}` : `keys: ${changed[0]} and ${more} more`;
+}
+/**
+* The console a scan is handed. It records the scanner's errors and prints none: `onError` is
+* their only printer. The first scan prints its other lines as `moku-game keys` does; a later
+* scan drops them, the batch prints one line of its own.
+*
+* @param ui - The real console.
+* @param errors - Takes every error line of the scan.
+* @param first - True for the first scan of the watch.
+* @returns The console of one scan.
+*/
+function scanUi(ui, errors, first) {
+	return {
+		info: (message) => {
+			if (first) ui.info(message);
+		},
+		warn: (message) => {
+			if (first) ui.warn(message);
+		},
+		line: (text) => {
+			if (first) ui.line(text);
+		},
+		error: (message) => {
+			errors.push(message);
+		}
+	};
+}
+/**
+* The message of a scan that answered an exit code other than 0: the error lines it printed, one
+* per line, or the code itself when it printed none.
+*
+* @param code - The exit code of the scan, not 0.
+* @param errors - The error lines the scan printed.
+* @returns The message for `onError`.
+* @example
+* ```ts
+* failureText(1, []); // "the scan exited with code 1."
+* ```
+*/
+function failureText(code, errors) {
+	return errors.length > 0 ? errors.join("\n") : `the scan exited with code ${code}.`;
+}
+/**
+* Runs the scan of `moku-game keys` for the game as it is on disk now. The flags are read again
+* for every scan: `--pseudo` depends on a `strings/en.json` being there.
+*
+* @param watch - The watch.
+* @param first - True for the first scan of the watch.
+* @returns The message of a failed scan, or `undefined` when it worked.
+*/
+async function failureOf(watch, first) {
+	const errors = [];
+	try {
+		const argv = keysArguments(watch.root, watch.settings, false);
+		const code = await watch.seams.scan(argv, scanUi(watch.seams.ui, errors, first));
+		return code === 0 ? void 0 : failureText(code, errors);
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+}
+/**
+* Runs the scan and says how it went: a failure goes to `onError`, a later scan that worked
+* prints one line. The first scan printed the scanner's own lines.
+*
+* @param watch - The watch.
+* @param changed - The changed inputs, sorted.
+* @param first - True for the first scan of the watch.
+*/
+async function scanAndReport(watch, changed, first) {
+	const failure = await failureOf(watch, first);
+	if (failure !== void 0) watch.onError(failure);
+	else if (!first) watch.seams.ui.info(changeLine(changed));
+}
+/**
+* One batch: walks the game, and scans when an input differs from the batch before; the first
+* batch always scans. Then it writes the stamp of the asset files, asks for one trailing batch,
+* and arms the folder watchers with the folders of the walk. A batch that did not scan asks for
+* nothing, so the trailing batch of a quiet game ends the chain.
+*
+* @param watch - The watch.
+*/
+async function runBatch(watch) {
+	const walk = walkInputs(watch.root);
+	const first = watch.inputs === void 0;
+	const changed = changedPaths(watch.inputs ?? /* @__PURE__ */ new Map(), walk.inputs);
+	watch.inputs = walk.inputs;
+	if (first || changed.length > 0) {
+		await scanAndReport(watch, changed, first);
+		writeIfChanged(path.join(watch.root, ".moku", ASSETS_STAMP), assetsStamp(assetsHash(walk.inputs)));
+		watch.again();
+	}
+	if (!watch.closed) watch.tree.rearm(walk.folders);
+}
+/**
+* Runs one batch after the batch before it ended: two scans never write `generated/` at the same
+* time. A batch the batcher starts during the first scan waits here.
+*
+* @param watch - The watch.
+* @returns Resolves when the batch ended.
+*/
+function serialized(watch) {
+	const batch = watch.scanning.then(() => runBatch(watch));
+	watch.scanning = batch.catch(() => {});
+	return batch;
+}
+/**
+* Starts the keys watch of a checked game: watches the folder, runs the scan of `moku-game keys`
+* once, and resolves after it, so `generated/` is fresh before a page is served. The watcher
+* starts first: a save the platform reports during the first scan starts a batch after it. Then
+* every batch of file events outside the skipped folders scans again when an asset file or a
+* strings file changed. A failed scan, the first one too, goes to `onError` and the watch goes on.
+*
+* @param root - The game folder, absolute.
+* @param settings - The resolved config.
+* @param seams - The scan, `fs.watch` and the console.
+* @param options - Where the message of a failed scan goes.
+* @returns The running watch.
+* @throws {Error} When the game folder is gone, or the first batch breaks outside the scan.
+*/
+async function watchKeysAt(root, settings, seams, options = {}) {
+	const real = realpathSync(root);
+	const onError = options.onError ?? ((message) => seams.ui.warn(`[game] keys: ${message}`));
+	const batcher = createBatcher(QUIET_MS, () => serialized(watch));
+	const tree = watchTree(real, () => batcher.poke(), seams.watch);
+	const watch = {
+		root: real,
+		settings,
+		seams,
+		onError,
+		tree,
+		again: () => batcher.poke(),
+		inputs: void 0,
+		scanning: Promise.resolve(),
+		closed: false
+	};
+	const close = () => {
+		if (watch.closed) return;
+		watch.closed = true;
+		batcher.cancel();
+		tree.close();
+	};
+	try {
+		await serialized(watch);
+	} catch (error) {
+		close();
+		throw error;
+	}
+	return { close };
+}
+//#endregion
 //#region src/app/native.ts
 /**
 * @file The native verbs of `moku-game`: a game's `config.ts` as the config of `@moku-labs/native`,
@@ -1882,13 +2209,44 @@ async function runNative(verb, settings, where, options) {
 * @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, 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.
+* caller starts itself, as the editor does, and `watchKeys` keeps the game's `generated/` fresh
+* while that page is open. It imports no Pixi, and the root entry never imports it. The code
+* lives in `app/`; this file wires the real process into it.
 */
 /**
+* Runs the asset scanner's command line with the string tools of i18n: the scan behind
+* `moku-game keys`, `pack`, and the keys watch.
+*
+* @param argv - The flags of the scanner.
+* @param ui - Where its lines go.
+* @returns The exit code of the scanner.
+*/
+function runScanner(argv, ui) {
+	return runCli$1(argv, {
+		compile: compileStrings,
+		exportStrings,
+		importStrings
+	}, ui);
+}
+/**
+* The real seams of the keys watch: the asset scanner with the string tools, as `moku-game keys`
+* runs it, `fs.watch`, and the console.
+*
+* @param ui - The console of the process.
+* @returns The seams.
+*/
+function keysSeams(ui) {
+	return {
+		scan: runScanner,
+		watch,
+		ui
+	};
+}
+/**
 * 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, native, and the visual test runner, loaded only by `moku-game visual`.
+* started with, Bun's spawn and resolver, the signals, `fs.watch`, the keys watch, the asset
+* scanner with the string tools, native, and the visual test runner, loaded only by
+* `moku-game visual`.
 *
 * @returns The seams of this process.
 */
@@ -1914,11 +2272,8 @@ function processDeps() {
 			watcher.on("error", () => watcher.close());
 			return watcher;
 		},
-		assets: (argv) => runCli$1(argv, {
-			compile: compileStrings,
-			exportStrings,
-			importStrings
-		}, ui),
+		watchKeys: (root, settings) => watchKeysAt(root, settings, keysSeams(ui)),
+		assets: (argv) => runScanner(argv, ui),
 		native: runNative,
 		resolve: (specifier, from) => Bun.resolveSync(specifier, from),
 		loadPage: (file) => import(file),
@@ -1946,8 +2301,10 @@ async function runCli(argv) {
 /**
 * Writes a game's dev page into `<root>/.moku/` for a server the caller starts: `index.html`,
 * `dev.ts`, `main.ts` with the scenarios of `tests/scenarios/` (and, with agents, the agents and
-* the game's `.dev` modules), and `bunfig.toml` with the engine's hot plugin. It starts no server
-* and no watcher, and throws the `[game]` errors of `moku-game dev`.
+* the game's `.dev` modules), and `bunfig.toml` with the engine's hot plugin. It also writes the
+* first `assets-stamp.ts`, the empty one, when the game has none: `main.ts` imports it, and
+* `watchKeys` rewrites it when an asset file changes. It starts no server and no watcher, and
+* throws the `[game]` errors of `moku-game dev`.
 *
 * @param root - The game folder, relative to the cwd or absolute.
 * @param options - The agents, the preloads and the extra bundler plugins.
@@ -1970,5 +2327,35 @@ async function preparePage(root, options = {}) {
 		servePlugins: absolute(options.servePlugins)
 	}, (specifier, from) => Bun.resolveSync(specifier, from));
 }
+/**
+* Keeps `generated/` of a game fresh while its dev page is open, for a server the caller runs:
+* the editor calls it next to `preparePage`, and raw `moku-game dev` runs the same watch itself.
+* It watches the game folder, runs the scan of `moku-game keys` once and resolves after it. Then
+* a save of an asset file (`.png`, `.webp`, `.fnt`, `.mp3`, `.m4a`) or of a
+* `strings/<locale>.json` scans again, with the same flags, outputs and layers; an output that
+* did not change is not rewritten. On the page a rewritten `generated/strings.<locale>.ts` hot
+* swaps. An asset file that is new, gone or saved again rewrites `.moku/assets-stamp.ts`, which
+* the page imports, so the page reloads and shows the new image or the new bytes of an old one. A
+* failed scan goes to `onError` and the watch goes on, the first scan too. The layers of
+* `config.ts` are read once: a changed layer needs a new `watchKeys`.
+*
+* @param root - The game folder, relative to the cwd or absolute.
+* @param options - Where the message of a failed scan goes.
+* @returns The running watch; `close()` stops it.
+* @throws {Error} When the game has no `config.ts` or `index.ts`, or a config value is refused.
+* @example
+* ```ts
+* // The editor bin, next to preparePage, started with --root games/timber:
+* const { preparePage, watchKeys } = await import(Bun.resolveSync("@moku-labs/game/cli", root));
+* await preparePage("games/timber", { agents: ["@moku-labs/editor/agent/page"] });
+* const keys = await watchKeys("games/timber", { onError: message => log.warn(message) });
+* // generated/ is fresh; a save of features/home/strings/en.json rewrites generated/strings.en.ts
+* keys.close(); // when the editor closes the game
+* ```
+*/
+async function watchKeys(root, options = {}) {
+	const game = path.resolve(root);
+	return watchKeysAt(game, await loadGame(game), keysSeams(createBrandConsole()), options);
+}
 //#endregion
-export { preparePage, runCli };
+export { preparePage, runCli, watchKeys };