@moku-labs/game 0.12.0 → 0.13.1

package/README.md

@@ -134,7 +134,7 @@ app.model.store.snapshot().session; // { rolls: 2 }
 
 `bunx moku-game dev` serves it with hot reload on `http://localhost:3000/`. The full version, with a reset node and a vitest file, is in [docs/quick-start.md](./docs/quick-start.md). A bigger game, the merge game, lives in [moku-labs/demos](https://github.com/moku-labs/demos) with its tests.
 
-A game with a screen gets two more things from the package. The body font `fonts/font-body.*` (Pangolin, SIL OFL 1.1) is the default of the built-in text style `body` once copied into `features/ui/assets/`. `moku-game keys` writes the typed asset keys, the manifest and the strings. Both are in [docs/quick-start.md](./docs/quick-start.md#a-screen-the-body-font-and-the-asset-keys).
+A game with a screen gets two more things from the package. The body font `fonts/font-body.*` (Pangolin, SIL OFL 1.1) is the default of the built-in text style `body` once copied into `features/ui/assets/`. `moku-game keys` writes the typed asset keys, the manifest and the strings, and `moku-game dev` writes them again when an asset or a strings file is saved. Both are in [docs/quick-start.md](./docs/quick-start.md#a-screen-the-body-font-and-the-asset-keys).
 
 ## Game shell
 
@@ -160,12 +160,12 @@ The engine bin `moku-game` serves, builds and packs a game folder. A game writes
 
 | Command | Does |
 |---|---|
-| `moku-game dev [--port 3000] [--packed]` | Serves the game with hot reload. Prints the bound URL, also for `--port 0` |
+| `moku-game dev [--port 3000] [--packed]` | Serves the game with hot reload. Prints the bound URL, also for `--port 0`. On the raw files it runs the scan of `keys` at start and on a save of an asset or a strings file |
 | `moku-game build [--out dist/web]` | Packs the assets and builds the production page |
 | `moku-game native build <target> [--simulator]` | Builds the native app: `ios`, `macos`, `android` |
 | `moku-game native dev <target>` | Runs the native shell on the dev server |
 | `moku-game native doctor`, `native clean` | Checks or removes the native project |
-| `moku-game keys [--check]` | Writes `generated/assets.ts`, the strings and `manifest.json` |
+| `moku-game keys [--check]` | Writes `generated/assets.ts`, the strings and `generated/manifest.json` |
 | `moku-game pack [--no-cache]` | Packs the assets into `dist/assets` |
 | `moku-game visual [--update] [--only <name>] [--no-pixels]` | Runs the visual tests of `tests/visual/index.ts` against `tests/visual/baselines/`. The pixel leg runs on a Mac, on a page served for the run. Exit 1 when a checkpoint differs |
 
@@ -245,7 +245,7 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 | `@moku-labs/game/app` | anywhere | `defineGameApp`, `startMoment` and the types of `index.ts` and `config.ts`. See [The game shell](./docs/shell.md) |
 | `@moku-labs/game/app/page` | the browser | `startPage`, the page the generated `.moku/main.ts` calls |
 | `@moku-labs/game/app/system` | the browser, the native shell | The system shell over the optional peer `@moku-labs/system` |
-| `@moku-labs/game/cli` | Node and Bun | `runCli`, the bin `moku-game`; `preparePage`, the dev page for the editor |
+| `@moku-labs/game/cli` | Node and Bun | `runCli`, the bin `moku-game`; `preparePage`, the dev page for the editor; `watchKeys`, which keeps `generated/` fresh next to it |
 | `@moku-labs/game/testing` | anywhere | Headless and isolated games, the fake clock, the in-memory save |
 | `@moku-labs/game/visual` | Node and Bun | Visual tests: baselines of state, describe and pixels |
 | `@moku-labs/game/assets` | Node and Bun | Asset keys, the manifest, strings, the pack |

package/dist/app/page.d.mts

@@ -19,6 +19,7 @@ import { m as StartedPage, r as GameConfig, t as AnyGameApp, u as PageOptions }
  * ```ts
  * // Written by moku-game dev. Do not edit.
  * import "./dev.ts";
+ * import "./assets-stamp.ts";
  * import { startPage } from "@moku-labs/game/app/page";
  * import { systemShellOf } from "@moku-labs/game/app/system";
  * import game from "../index.ts";

package/dist/app/page.mjs

@@ -321,6 +321,7 @@ async function startAgents(app, settings, options) {
 * ```ts
 * // Written by moku-game dev. Do not edit.
 * import "./dev.ts";
+* import "./assets-stamp.ts";
 * import { startPage } from "@moku-labs/game/app/page";
 * import { systemShellOf } from "@moku-labs/game/app/system";
 * import game from "../index.ts";

package/dist/cli.d.mts

@@ -1,3 +1,38 @@
+//#region src/app/keys.d.ts
+/** The running keys watch of one game folder, as `watchKeys` answers it. */
+type KeysWatcher = {
+  /**
+   * Stops watching. A scan that is running finishes; no later one starts. A second call does
+   * nothing.
+   *
+   * @example
+   * ```ts
+   * // The editor closes the game it has open.
+   * const keys = await watchKeys("games/timber");
+   * keys.close(); // a later save of features/home/strings/en.json rewrites nothing in generated/
+   * ```
+   */
+  close(): void;
+};
+/** What `watchKeys` is started with. */
+type WatchKeysOptions = {
+  /**
+   * Called with the scanner's message when a scan fails: bad JSON in a strings file, a key two
+   * files claim, a refused file. The watch goes on and the next save scans again. It is the only
+   * printer of a scan error. Default: a warning on the branded console, `[game] keys: <message>`.
+   *
+   * @param message - The message of the scanner; one line per problem when it found several.
+   * @example
+   * ```ts
+   * // The editor shows a failed scan in its own log, not in the terminal.
+   * const keys = await watchKeys("games/timber", { onError: message => log.warn(message) });
+   * // features/home/strings/en.json saved without its closing brace: under Bun log.warn gets
+   * // "[game] i18n: features/home/strings/en.json could not be read: JSON Parse error: Expected '}'.\n  Fix the message or use a supported ICU feature."
+   * ```
+   */
+  onError?: (message: string) => void;
+};
+//#endregion
 //#region src/cli.d.ts
 /**
  * What the dev page of `preparePage` is written with besides the game.
@@ -50,8 +85,10 @@ declare function runCli(argv: readonly string[]): Promise<number>;
 /**
  * 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.
@@ -67,5 +104,32 @@ declare function runCli(argv: readonly string[]): Promise<number>;
  * ```
  */
 declare function preparePage(root: string, options?: PreparePageOptions): Promise<PreparedPage>;
+/**
+ * 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
+ * ```
+ */
+declare function watchKeys(root: string, options?: WatchKeysOptions): Promise<KeysWatcher>;
 //#endregion
-export { PreparePageOptions, PreparedPage, preparePage, runCli };
+export { type KeysWatcher, PreparePageOptions, PreparedPage, type WatchKeysOptions, preparePage, runCli, watchKeys };