@moku-labs/game 0.14.11 → 0.14.13

package/dist/assets.d.mts

@@ -1,4 +1,4 @@
-import { u as Manifest } from "./types-BT9S_Lo2.mjs";
+import { d as Manifest } from "./types-BGcda5Le.mjs";
 
 //#region src/plugins/assets/scan/cli.d.ts
 /**
@@ -122,7 +122,11 @@ declare function runCli(argv: string[], strings: StringsTools, ui?: ScanUi): Pro
  * What one compile produced.
  */
 type CompileReport = {
-  /** True when an output on disk differs from what the compile produced. */changed: boolean; /** Every locale a feature brought a file for, and `en-XA` with `pseudo`, sorted. */
+  /** True when an output on disk differs from what the compile produced. */changed: boolean;
+  /**
+   * Every locale a feature, a sub-feature or a layer brought a file for, and `en-XA` with `pseudo`,
+   * sorted.
+   */
   locales: readonly string[]; /** Every message key, sorted. */
   keys: readonly string[]; /** One line per key a locale lacks. Nothing here stops a build. */
   notes: readonly string[];
@@ -149,11 +153,14 @@ type CompileOptions = {
   layers?: Readonly<Record<string, string>>;
 };
 /**
- * Walks `features/*​/strings/<locale>.json` of a game and the `strings/` of every layer, compiles
- * every message and writes the generated modules: the types module `strings.ts` and one
- * `strings.<locale>.ts` per locale, plus `strings.en-XA.ts` with `pseudo`. A check run writes
- * nothing and only reports whether something would change; it checks `strings.en-XA.ts` only with
- * `pseudo`.
+ * Walks the `strings/<locale>.json` of every feature of a game, sub-features at any depth
+ * included, and the `strings/` of every layer, compiles every message and writes the generated
+ * modules: the types module `strings.ts` with every key; one `strings.<locale>.ts` per locale with
+ * the keys of the top-level features and the layers; and for every sub-feature that brings string
+ * files one `strings.<feature>.<locale>.ts` per locale with its own keys (an empty table where it
+ * lacks the locale). `strings.en-XA.ts` and its per-feature twins come with `pseudo`. A game
+ * without sub-features writes exactly the modules 0.14.12 wrote. A check run writes nothing and
+ * only reports whether something would change; it checks the `en-XA` modules only with `pseudo`.
  *
  * @param root - Game source root, the folder that holds the features.
  * @param out - The generated directory the modules are written into.
@@ -172,6 +179,7 @@ type CompileOptions = {
  * // shared/strings/en.json { "ui.ok": "OK" } compile together.
  * const layered = await compileStrings("src", "src/generated", { layers: { shared: "ui" } });
  * // layered.keys: ["board.full", "ui.ok"]
+ * // features/episodes/ep01/strings/en.json { "ep01.title": "Ward" } also writes generated/strings.ep01.en.ts
  * ```
  */
 declare function compileStrings(root: string, out: string, options?: CompileOptions): Promise<CompileReport>;
@@ -249,7 +257,7 @@ type ExportReport = {
  */
 type ImportReport = {
   /** Every locale an exchange file was read for, sorted. */locales: readonly string[]; /** How many keys were written. */
-  keys: number; /** The string files of the features and layers rewritten, relative to the root, sorted. */
+  keys: number; /** The string files of the features, sub-features and layers rewritten, relative to the root, sorted. */
   files: readonly string[];
 };
 /**
@@ -390,7 +398,11 @@ declare function packAssets(options: PackOptions): Promise<PackResult>;
  * ```
  */
 type ScanOptions = {
-  /** Path of the game source root, the folder that holds the features. */root: string; /** Name of the folder that holds the features. Default `"features"`. */
+  /** Path of the game source root, the folder that holds the features. */root: string;
+  /**
+   * Name of the folder that holds the features: the folder whose owners `findFeatureOwners`
+   * finds, at any depth. Default `"features"`.
+   */
   features?: string; /** Path of the `manifest.json` to write. */
   manifest: string; /** Path of the generated key module to write. */
   keys: string; /** False for a check run: nothing is written. Default true. */
@@ -413,13 +425,17 @@ type ScanResult = {
 };
 /**
  * Walks the features and the layers of a game and writes its two generated files: one bundle per
- * feature or layer, split by its optional `assets.ts`, every file keyed by the key rule. A layer is
- * read like one more feature under its mapped name, after the features. A check run
- * (`write: false`) writes nothing and only reports whether something would change.
+ * feature owner or layer, split by its optional `assets.ts`, every file keyed by the key rule. A
+ * sub-feature (a folder with a door and resources inside a feature, at any depth) is an owner of
+ * its own: its keys and its bundle take the inner folder name, and only its bundle carries
+ * `parent` and `dir`. A layer is read like one more feature under its mapped name, after the
+ * features. A check run (`write: false`) writes nothing and only reports whether something would
+ * change.
  *
  * @param options - The game source root, the layers, the two output paths and whether to write.
  * @returns The manifest, the text of the key module and whether an output differed.
- * @throws {Error} One error that lists every problem the scan found, the layer problems first.
+ * @throws {Error} One error that lists every problem the scan found, the owner and layer problems
+ *   first.
  * @example
  * ```ts
  * const { manifest, changed } = await scanAssets({
@@ -429,6 +445,7 @@ type ScanResult = {
  *   layers: { shared: "ui" } // shared/assets/button/primary.png keeps the key "ui.button.primary"
  * });
  * // manifest.bundles.ui.files[0].key: "ui.button.primary", changed: true on the first run
+ * // features/episodes/ep01/assets/ward/room.png keeps the key "ep01.ward.room" in the bundle "ep01"
  * ```
  */
 declare function scanAssets(options: ScanOptions): Promise<ScanResult>;

package/dist/assets.mjs

@@ -1,2 +1,2 @@
-import { a as runCli, c as emitKeys, i as compileStrings, l as emitManifest, n as importStrings, o as scanAssets, r as checkStrings, s as packAssets, t as exportStrings } from "./assets-BrKSg1O6.mjs";
+import { a as runCli, c as emitKeys, i as compileStrings, l as emitManifest, n as importStrings, o as scanAssets, r as checkStrings, s as packAssets, t as exportStrings } from "./assets-CEMfBogh.mjs";
 export { checkStrings, compileStrings, emitKeys, emitManifest, exportStrings, importStrings, packAssets, runCli, scanAssets };

package/dist/cli.d.mts

@@ -1,3 +1,23 @@
+//#region src/app/engine.d.ts
+/**
+ * The engine a page is served or built with.
+ *
+ * @example
+ * ```ts
+ * const engine: EngineFingerprint = { id: "0.14.12+9c41e0", version: "0.14.12", dist: "9c41e0…", folder: "/game/node_modules/@moku-labs/game" };
+ * ```
+ */
+type EngineFingerprint = {
+  /** What the page and the log show: "0.14.12+9c41e0", "0.14.12+9c41e0.patch.3f2a7b", "0.0.0+src", "unknown". */id: string; /** `version` of the engine's package.json, "unknown" when no package.json of `@moku-labs/game` was found. */
+  version: string; /** SHA-256 (hex) of every file under the engine's `dist/`; "src" when the engine runs from its sources; "unknown". */
+  dist: string; /** The patch the install root declares for this version: its file (absolute) and SHA-256 (hex). */
+  patch?: {
+    file: string;
+    hash: string;
+  }; /** The engine's package folder, absolute; the folder of the resolved hot plugin when "unknown". */
+  folder: string;
+};
+//#endregion
 //#region src/app/keys.d.ts
 /** The running keys watch of one game folder, as `watchKeys` answers it. */
 type KeysWatcher = {
@@ -14,7 +34,10 @@ type KeysWatcher = {
    */
   close(): void;
 };
-/** What `watchKeys` is started with. */
+/**
+ * What `watchKeys` is started with. The watch scans when an asset file or a strings file changes;
+ * a folder that becomes or stops being a sub-feature scans too.
+ */
 type WatchKeysOptions = {
   /**
    * Called with the scanner's message when a scan fails: bad JSON in a strings file, a key two
@@ -33,6 +56,22 @@ type WatchKeysOptions = {
   onError?: (message: string) => void;
 };
 //#endregion
+//#region src/app/engine-watch.d.ts
+/**
+ * One change the engine watch saw.
+ *
+ * @example
+ * ```ts
+ * // `bun patch --commit` rebuilt the engine's dist: the served engine changed.
+ * const change: EngineChange = { before: { id: "0.14.12+1a2b3c", version: "0.14.12", dist: "1a2b3c…", folder: "/g/node_modules/@moku-labs/game" }, after: { id: "0.14.12+9c41e0", version: "0.14.12", dist: "9c41e0…", folder: "/g/node_modules/@moku-labs/game" }, restart: true };
+ * ```
+ */
+type EngineChange = {
+  /** The fingerprint the watch had until this change. */before: EngineFingerprint; /** The fingerprint of the engine now installed. */
+  after: EngineFingerprint; /** True when the served engine changed (version or dist): the page server must restart. False: only the patch file. */
+  restart: boolean;
+};
+//#endregion
 //#region src/cli.d.ts
 /**
  * What the dev page of `preparePage` is written with besides the game.
@@ -64,7 +103,36 @@ type PreparePageOptions = {
  */
 type PreparedPage = {
   /** Absolute path of `<root>/.moku/index.html`: the HTML a Bun server imports. */html: string; /** Absolute path of `<root>/.moku/bunfig.toml`: pass it as `bun --config=<bunfig>`. */
-  bunfig: string;
+  bunfig: string; /** The engine the page was written for: its id is the one the page shows in `globalThis.__MOKU_GAME_ENGINE__`. */
+  engine: EngineFingerprint;
+};
+/**
+ * What `watchEngine` reports to.
+ *
+ * @example
+ * ```ts
+ * // The editor restarts its page server on a new engine and logs a patch that is not installed yet.
+ * const options: WatchEngineOptions = {
+ *   onChange: change => (change.restart ? restartPageServer() : log.warn("the engine's patch changed; run bun install")),
+ *   onError: message => log.warn(message)
+ * };
+ * ```
+ */
+type WatchEngineOptions = {
+  /** Called with every change the watch sees. Default: the warning lines of `moku-game dev`, on the console. */onChange?: (change: EngineChange) => void; /** Where an unreadable engine goes. Default: a console warning. */
+  onError?: (message: string) => void;
+};
+/**
+ * The running engine watch of `watchEngine`.
+ *
+ * @example
+ * ```ts
+ * const engine: EngineWatcher = watchEngine("games/timber");
+ * engine.close(); // when the editor closes the game
+ * ```
+ */
+type EngineWatcher = {
+  /** Stops watching; a second call does nothing. */close(): void;
 };
 /**
  * Runs one `moku-game` command line in this process: `dev`, `build`, `native <verb>`, `keys`,
@@ -78,14 +146,16 @@ type PreparedPage = {
  * // 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(["build", "--debug"]); // 0: dist/web carries the editor agent; one warning names build debug-20261014T153012Z
  * await runCli(["help"]); // 0
  * ```
  */
 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 also writes the
+ * `script.ts`, `dev.ts` with the flags and the engine id, `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 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. The page accepts the new stamp: new bytes
  * of a file swap in place, a new or removed file reloads the page. It starts no server and no
@@ -93,15 +163,16 @@ declare function runCli(argv: readonly string[]): Promise<number>;
  *
  * @param root - The game folder, relative to the cwd or absolute.
  * @param options - The agents, the preloads and the extra bundler plugins.
- * @returns The absolute paths of the HTML and the bunfig.
+ * @returns The absolute paths of the HTML and the bunfig, and the engine the page was written for.
  * @throws {Error} When the game has no `config.ts` or `index.ts`, a config value is refused, the
  *   game does not resolve `@moku-labs/game/hot`, or a preload or plugin is not a file.
  * @example
  * ```ts
  * // The editor bin, started with --root games/timber:
  * const { preparePage } = await import(Bun.resolveSync("@moku-labs/game/cli", root));
- * await preparePage("games/timber", { agents: ["@moku-labs/editor/agent/page"] });
- * // { html: "<cwd>/games/timber/.moku/index.html", bunfig: "<cwd>/games/timber/.moku/bunfig.toml" }
+ * const page = await preparePage("games/timber", { agents: ["@moku-labs/editor/agent/page"] });
+ * // { html: "<cwd>/games/timber/.moku/index.html", bunfig: "<cwd>/games/timber/.moku/bunfig.toml", engine: { … } }
+ * // page.engine.id: "0.14.12+9c41e0"
  * ```
  */
 declare function preparePage(root: string, options?: PreparePageOptions): Promise<PreparedPage>;
@@ -133,5 +204,31 @@ declare function preparePage(root: string, options?: PreparePageOptions): Promis
  * ```
  */
 declare function watchKeys(root: string, options?: WatchKeysOptions): Promise<KeysWatcher>;
+/**
+ * Watches the engine a game resolves, for a page server the caller runs: the editor calls it next
+ * to `preparePage`, and raw `moku-game dev` runs the same watch itself. It takes the fingerprint
+ * of the installed engine now (the id `preparePage(...).engine` has), watches the engine's
+ * folders, its patch and the install root's `package.json` and lock, and after 300 ms of quiet
+ * fingerprints again: a new version or dist calls `onChange` with `restart: true` (the page server
+ * must restart, Bun caches nothing across a restart), a changed patch alone with `restart: false`
+ * (the install did not happen yet). An engine run from its sources is not watched. Sync: it
+ * scans nothing.
+ *
+ * @param root - The game folder, relative to the cwd or absolute.
+ * @param options - Where the changes and the errors go.
+ * @returns The running watch; `close()` stops it.
+ * @throws {Error} When the game does not resolve `@moku-labs/game/hot`.
+ * @example
+ * ```ts
+ * // The editor bin, next to preparePage, started with --root games/timber:
+ * const { preparePage, watchEngine } = await import(Bun.resolveSync("@moku-labs/game/cli", root));
+ * const page = await preparePage("games/timber", { agents: ["@moku-labs/editor/agent/page"] });
+ * page.engine.id; // "0.14.12+9c41e0"
+ * const engine = watchEngine("games/timber", { onChange: change => change.restart && restartPageServer() });
+ * // after `bun patch --commit` in the game: onChange({ before: { id: "0.14.12+9c41e0", … }, after: { id: "0.14.12+1a2b3c.patch.3f2a7b", … }, restart: true })
+ * engine.close(); // when the editor closes the game
+ * ```
+ */
+declare function watchEngine(root: string, options?: WatchEngineOptions): EngineWatcher;
 //#endregion
-export { type KeysWatcher, PreparePageOptions, PreparedPage, type WatchKeysOptions, preparePage, runCli, watchKeys };
+export { type EngineChange, type EngineFingerprint, EngineWatcher, type KeysWatcher, PreparePageOptions, PreparedPage, WatchEngineOptions, type WatchKeysOptions, preparePage, runCli, watchEngine, watchKeys };