@moku-labs/game 0.7.1 → 0.9.0

package/README.md

@@ -115,7 +115,7 @@ await game.walk([{ at: "home", intent: "roll" }, { at: "home", intent: "roll" }]
 app.model.store.snapshot().session; // { rolls: 2 }
 ```
 
-The full version, with a reset node and a vitest file, is in [docs/quick-start.md](./docs/quick-start.md). A bigger game lives in [`tests/integration/merge-game/`](./tests/integration/merge-game). It is a test fixture and is not published.
+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 `src/features/ui/assets/`. The bin `moku-game-assets` writes the typed asset keys, the manifest and the strings. It runs under bun; with node only, run `bun node_modules/@moku-labs/game/dist/assets.mjs`. Both are in [docs/quick-start.md](./docs/quick-start.md#a-screen-the-body-font-and-the-asset-keys).
 
@@ -188,7 +188,8 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 | Import | Runs in | For |
 |---|---|---|
 | `@moku-labs/game` | anywhere | The engine: plugins, helpers, components |
-| `@moku-labs/game/testing` | Node and Bun | Headless games and visual tests |
+| `@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 |
 | `@moku-labs/game/inspect` | anywhere | Read a running game |
 | `@moku-labs/game/control` | dev builds | Drive a running game |
@@ -199,7 +200,7 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 
 ### Lint for games
 
-`@moku-labs/game/lint` is an oxlint JS plugin, `moku-game`. It checks the engine rules in a game: lazy Pixi and Yoga, no native package in the logic, the editor only in dev files, no module-scope state, determinism, pure rules and JSX keys the project index can follow.
+`@moku-labs/game/lint` is an oxlint JS plugin, `moku-game`. It checks the engine rules in a game: lazy Pixi and Yoga, no native package in the logic, the editor only in dev files, no module-scope state, determinism, pure rules and JSX keys the project index can follow. Three layout rules check a game on the layered layout: the order of the layers, the doors of the features and the suffix of each test file.
 
 ```json
 // .oxlintrc.json
@@ -212,12 +213,15 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
     "moku-game/no-module-state": "error",
     "moku-game/determinism": "error",
     "moku-game/rules-siblings": "error",
-    "moku-game/static-keys": "error"
+    "moku-game/static-keys": "error",
+    "moku-game/layer-imports": "error",
+    "moku-game/feature-door": "error",
+    "moku-game/test-suffix": "error"
   }
 }
 ```
 
-Each rule takes `{ "files": [...], "ignores": [...] }`. The defaults follow the template layout. See [Lint for games](./docs/lint.md).
+Each rule takes `{ "files": [...], "ignores": [...] }`. `layer-imports`, `feature-door` and `rules-siblings` also take `root` and `tsconfig`; `test-suffix` takes `root` and `suffixes`. The defaults follow the layout of a game. See [Lint for games](./docs/lint.md).
 
 ## Docs
 
@@ -232,7 +236,7 @@ Each rule takes `{ "files": [...], "ignores": [...] }`. The defaults follow the
 | [Configuration](./docs/configuration.md) | Every config field and its default |
 | [Lint for games](./docs/lint.md) | The `moku-game` oxlint rules, their options and defaults |
 | [Project index](./docs/project-index.md) | `openProject`, the key scheme, `find` and `watch`, the `moku-game-index` bin |
-| [Testing](./docs/testing.md) | Headless and visual tests, all scripts, test layout, lint rules |
+| [Testing](./docs/testing.md) | Headless, isolated and visual tests, all scripts, test layout, lint rules |
 | [`llms.txt`](./llms.txt) | The engine in one page, for an AI that writes a game |
 
 Each plugin has its own README, linked in the table above. The kernel is specified in the [Moku Core specification](https://github.com/moku-labs/core/tree/main/specification).
@@ -246,8 +250,8 @@ bun run lint             # biome check . && eslint .
 bun run test             # vitest, unit and integration
 bun run test:coverage    # with the 90% threshold
 bun run validate         # publint and attw
-bun run fixture:visual   # visual tests of the fixture game
-bun run fixture:native   # the fixture as a native app
+bun run mini:pack        # pack the mini game of tests/fixtures
+bun run mini:visual      # visual tests of the mini game
 bun run release          # moku-release
 ```
 

package/dist/assets.d.mts

@@ -1,4 +1,4 @@
-import { l as Manifest } from "./types-BMEn0tSC.mjs";
+import { l as Manifest } from "./types-B0v5VVa3.mjs";
 
 //#region src/plugins/assets/scan/cli.d.ts
 /**
@@ -19,18 +19,20 @@ type StringsReport = {
 };
 /**
  * Compiles the feature strings of a root into a folder, or checks them in a check run; with
- * `pseudo` it writes the pseudo-locale `en-XA` too. `compileStrings` of i18n fits it, and a test
- * passes a stub instead.
+ * `pseudo` it writes the pseudo-locale `en-XA` too, and with `layers` it walks the `strings/` of
+ * every layer as well. `compileStrings` of i18n fits it, and a test passes a stub instead.
  *
  * @example
  * ```ts
  * // A test of a wrapper script: a game with one English key.
  * const compile: StringsCompiler = async () => ({ changed: false, locales: ["en"], keys: ["hud.title"], notes: [] });
+ * // runCli passes { check: false, pseudo: true, layers: { shared: "ui" } } for "--pseudo --layer shared=ui"
  * ```
  */
 type StringsCompiler = (root: string, out: string, options: {
   check: boolean;
   pseudo: boolean;
+  layers?: Readonly<Record<string, string>>;
 }) => Promise<StringsReport>;
 /**
  * Writes one exchange file per locale for the translators into a folder, and reports how many
@@ -44,6 +46,7 @@ type StringsCompiler = (root: string, out: string, options: {
  */
 type StringsExporter = (root: string, dir: string, options: {
   source: string;
+  layers?: Readonly<Record<string, string>>;
 }) => Promise<{
   locales: readonly string[];
   missing: Readonly<Record<string, number>>;
@@ -63,6 +66,7 @@ type StringsImporter = (root: string, dir: string, options: {
   source: string;
   pseudo: boolean;
   out: string;
+  layers?: Readonly<Record<string, string>>;
 }) => Promise<{
   locales: readonly string[];
   keys: number;
@@ -90,8 +94,10 @@ type StringsTools = {
  * compile the feature strings next to the key module, or check that all of it is current. With
  * `--pack <dir>` it packs the art for production on the same scan (`--no-cache` for a cold run);
  * `--pseudo` adds the pseudo-locale to a dev run. `--export <dir>` and `--import <dir>` exchange
- * the strings with translators and run alone, from the locale of `--source`. Nothing here calls
- * `process.exit`; the caller does.
+ * the strings with translators and run alone, from the locale of `--source`.
+ * `--layer <folder>[=<name>]` (repeatable) scans a folder under the root like one more feature,
+ * its keys and bundles under `<name>` (`<folder>` by default); it goes with every mode. Nothing
+ * here calls `process.exit`; the caller does.
  *
  * @param argv - The arguments after the script name.
  * @param strings - The string tools of i18n: compile, export and import.
@@ -105,6 +111,8 @@ type StringsTools = {
  * // 0, and dist/assets holds the pages, the loose files and the packed manifest.json
  * await runCli(["--root", "src", "--export", "translations"], strings);
  * // 0, and translations/ holds one <locale>.json per locale for the translators
+ * await runCli(["--root", "src", "--layer", "shared=ui"], strings);
+ * // 0, shared/assets/* keyed ui.*, shared/strings/* compiled
  * ```
  */
 declare function runCli(argv: string[], strings: StringsTools, ui?: ScanUi): Promise<number>;
@@ -121,36 +129,56 @@ type CompileReport = {
 };
 /**
  * What one compile is told beyond its two paths.
+ *
+ * @example
+ * ```ts
+ * // A v15 game: the dev build writes en-XA, and shared/strings/ compiles next to the features.
+ * const options: CompileOptions = { pseudo: true, layers: { shared: "ui" } };
+ * ```
  */
 type CompileOptions = {
   /** True for a check run: nothing is written. */check?: boolean; /** Name of the folder that holds the features. Default `"features"`. */
   features?: string; /** True to also write `strings.en-XA.ts`, the pseudo-locale, from the `"en"` messages. */
   pseudo?: boolean;
+  /**
+   * Layers walked next to the features: folder under `root` to the name its keys take.
+   * `{ shared: "ui" }` reads `<root>/shared/strings/<locale>.json` exactly as a feature's
+   * `strings/` is read. A folder is one name, without "/", "\" or ".". Default `{}`: features
+   * only.
+   */
+  layers?: Readonly<Record<string, string>>;
 };
 /**
- * Walks `features/*​/strings/<locale>.json` of a game, 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 `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`.
  *
  * @param root - Game source root, the folder that holds the features.
  * @param out - The generated directory the modules are written into.
- * @param options - Whether this is a check run, what the features folder is called, and whether
- *   the pseudo-locale is written.
+ * @param options - Whether this is a check run, what the features folder is called, whether the
+ *   pseudo-locale is written, and the layers.
  * @returns Whether an output differed, the locales, the keys and the notes.
- * @throws {Error} One error that lists every problem the compile found, or the pseudo error when
- *   no feature brings an `en` string file.
+ * @throws {Error} One error that lists every problem the compile found, the pseudo error when
+ *   no feature or layer brings an `en` string file, or the layer error when a layer folder is not
+ *   one folder name: nothing is read then.
  * @example
  * ```ts
  * // A dev build also writes the pseudo-locale, derived from the English messages.
  * const report = await compileStrings("src", "src/generated", { pseudo: true });
  * // report.locales: ["en", "en-XA", "ru"], report.changed: true on the first run
+ * // A v15 game: features/board/strings/en.json { "board.full": "Full" } and the layer file
+ * // 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"]
  * ```
  */
 declare function compileStrings(root: string, out: string, options?: CompileOptions): Promise<CompileReport>;
 /**
  * Tells whether the generated modules of a game are current, without writing anything. The
- * `--check` run of `bun run assets:keys` covers the strings with it.
+ * `--check` run of `bun run assets:keys` covers the strings with it. It walks the features only: a
+ * game with layers checks through `runCli` with `--check --layer …`.
  *
  * @param root - Game source root, the folder that holds the features.
  * @param out - The generated directory the modules live in.
@@ -164,17 +192,27 @@ declare function compileStrings(root: string, out: string, options?: CompileOpti
 declare function checkStrings(root: string, out: string): Promise<boolean>;
 //#endregion
 //#region src/plugins/i18n/compile/exchange.d.ts
+/** A layer map: folder under the root to the name its keys take. */
+type Layers = Readonly<Record<string, string>>;
 /**
  * What an export and an import are told beyond their two paths.
  *
  * @example
  * ```ts
  * const options: ExchangeOptions = { source: "ru" }; // the translators read the Russian text
+ * // A v15 game: the keys of shared/strings/ go out and come back with the rest.
+ * const layered: ExchangeOptions = { source: "ru", layers: { shared: "ui" } };
  * ```
  */
 type ExchangeOptions = {
   /** The locale translators read from, written as `source` beside each text. Default `"en"`. */source?: string; /** Name of the folder that holds the features. Default `"features"`. */
   features?: string;
+  /**
+   * Layers read next to the features: folder under `root` to the name its keys take.
+   * `{ shared: "ui" }` exports the keys of `<root>/shared/strings/` and imports their texts back
+   * into that folder. A folder is one name, without "/", "\" or ".". Default `{}`: features only.
+   */
+  layers?: Layers;
 };
 /**
  * What an import is told: the exchange options and the compile that runs after the files are
@@ -211,20 +249,21 @@ 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 that were rewritten, relative to the root, sorted. */
+  keys: number; /** The string files of the features and layers rewritten, relative to the root, sorted. */
   files: readonly string[];
 };
 /**
- * Writes the files translators work in: one `<dir>/<locale>.json` per locale the features bring,
- * the source locale included, so a new language starts as a copy of `en.json`. Every key of the
- * game is in every file, sorted: `{ text, source, note? }`, with `text: ""` where the locale has no
- * message yet. The game tree is not touched, and a second run writes the same bytes.
+ * Writes the files translators work in: one `<dir>/<locale>.json` per locale the features and
+ * layers bring, the source locale included, so a new language starts as a copy of `en.json`. Every
+ * key of the game is in every file, sorted: `{ text, source, note? }`, with `text: ""` where the
+ * locale has no message yet. The game tree is not touched, and a second run writes the same bytes.
  *
  * @param root - Game source root, the folder that holds the features.
  * @param dir - The folder the exchange files are written into; created when missing.
- * @param options - The source locale and the name of the features folder.
+ * @param options - The source locale, the name of the features folder and the layers.
  * @returns The exported locales and how many keys each one lacks.
- * @throws {Error} When the game's strings do not compile, or no feature brings the source locale.
+ * @throws {Error} When the game's strings do not compile, a layer folder is not one folder name,
+ *   or no feature brings the source locale.
  * @example
  * ```ts
  * // Before a release, the game hands its strings to the translators.
@@ -235,21 +274,26 @@ type ImportReport = {
 declare function exportStrings(root: string, dir: string, options?: ExchangeOptions): Promise<ExportReport>;
 /**
  * Takes translated exchange files back into the game: every `<dir>/<locale>.json` is checked
- * against the game first, then each new text is written into the string file of the feature that
- * owns its key, and the strings are compiled into `out` as a dev run does. An empty text and a
- * text equal to the current message are skipped. With any problem nothing is written.
+ * against the game first, then each new text is written into the string file of the feature or
+ * layer that owns its key, and the strings are compiled into `out` as a dev run does. An empty text
+ * and a text equal to the current message are skipped. With any problem nothing is written.
  *
  * @param root - Game source root, the folder that holds the features.
  * @param dir - The folder the translators handed back.
- * @param options - The features folder, where the compile writes, and whether it writes `en-XA`.
+ * @param options - The features folder, the layers, where the compile writes, and whether it
+ *   writes `en-XA`.
  * @returns The locales read, how many keys were written and the files rewritten.
- * @throws {Error} One error that lists every problem of the exchange files, or the compile's own
- *   error after the files are written (a parameter kind that differs across locales).
+ * @throws {Error} One error that lists every problem of the exchange files, the layer error
+ *   before anything is read when a layer folder is not one folder name, or the compile's own error
+ *   after the files are written (a parameter kind that differs across locales).
  * @example
  * ```ts
  * // The translators handed back translations/ru.json with two hud texts filled in.
  * await importStrings("src", "translations", { out: "src/generated" });
  * // { locales: ["ru"], keys: 2, files: ["features/hud/strings/ru.json"] }
+ * // A v15 game: the translated ui.ok lands in the layer's own file.
+ * await importStrings("src", "translations", { out: "src/generated", layers: { shared: "ui" } });
+ * // { locales: ["ru"], keys: 1, files: ["shared/strings/ru.json"] }
  * ```
  */
 declare function importStrings(root: string, dir: string, options?: ImportOptions): Promise<ImportReport>;
@@ -331,7 +375,19 @@ declare function packAssets(options: PackOptions): Promise<PackResult>;
 //#endregion
 //#region src/plugins/assets/scan/scan.d.ts
 /**
- * What one scan is told: where the features are and where the two generated files go.
+ * What one scan is told: where the features and the layers are and where the two generated files
+ * go.
+ *
+ * @example
+ * ```ts
+ * // A v15 game: shared/ is a layer whose assets keep the ui.* keys.
+ * const options: ScanOptions = {
+ *   root: "src",
+ *   manifest: "public/assets/manifest.json",
+ *   keys: "src/generated/assets.ts",
+ *   layers: { shared: "ui" }
+ * };
+ * ```
  */
 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"`. */
@@ -339,6 +395,12 @@ type ScanOptions = {
   manifest: string; /** Path of the generated key module to write. */
   keys: string; /** False for a check run: nothing is written. Default true. */
   write?: boolean;
+  /**
+   * Layers scanned next to the features: folder under `root` to the name its keys and its default
+   * bundle take. `{ shared: "ui" }` reads `<root>/shared/assets.ts` and `<root>/shared/assets/`
+   * exactly as `features/ui/` is read, so every key stays `ui.*`. Default `{}`: features only.
+   */
+  layers?: Readonly<Record<string, string>>;
 };
 /**
  * What a scan produced.
@@ -350,19 +412,21 @@ type ScanResult = {
   notes: readonly string[];
 };
 /**
- * Walks the features of a game and writes its two generated files: one bundle per feature, split
- * by the optional `assets.ts` of that feature, every file keyed by the key rule. A check run
+ * 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.
  *
- * @param options - The game source root, the two output paths and whether to write.
+ * @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.
+ * @throws {Error} One error that lists every problem the scan found, the layer problems first.
  * @example
  * ```ts
  * const { manifest, changed } = await scanAssets({
  *   root: "src",
  *   manifest: "public/assets/manifest.json",
- *   keys: "src/generated/assets.ts"
+ *   keys: "src/generated/assets.ts",
+ *   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
  * ```