@moku-labs/game 0.14.12 → 0.14.13

package/README.md

@@ -53,7 +53,7 @@ bun add @moku-labs/game pixi.js
 ```
 
 > [!IMPORTANT]
-> Bun only. ESM only. There is no CJS build. `pixi.js` `^8.0.0` is a peer dependency. Screens are `.tsx`, so a game sets `"jsx": "react-jsx"` and `"jsxImportSource": "@moku-labs/game"`.
+> Bun only. ESM only. There is no CJS build. `pixi.js` `^8.22.0` is a peer dependency. Screens are `.tsx`, so a game sets `"jsx": "react-jsx"` and `"jsxImportSource": "@moku-labs/game"`.
 
 A game in a native shell adds the optional peers: `bun add @moku-labs/system` for the system plugins and the store save, `bun add -d @moku-labs/native` for the native build. A web-only game installs neither.
 
@@ -144,7 +144,7 @@ The engine bin `moku-game` serves, builds and packs a game folder. A game writes
 |---|---|
 | `index.ts` | `export default defineGameApp({ ... })` |
 | `config.ts` | `page`, `native`, `system`, `save`, `assets`: plain data that `satisfies GameConfig` |
-| `core/`, `shared/`, `features/`, `plugins/` | The kit, the shared layer, the features, the game's plugins |
+| `core/`, `shared/`, `features/`, `plugins/` | The kit, the shared layer, the features (a feature may hold sub-features, `features/episodes/ep01/`), the game's plugins |
 | `tests/` | The tests. `tests/scenarios/<name>.ts` are the saves of `?player=<name>` on the dev page |
 | `.moku/` | What `moku-game` writes. Add `.moku/` to `.gitignore` |
 
@@ -160,9 +160,9 @@ 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`. 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 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. Restarts its server when the installed engine changes |
+| `moku-game build [--out dist/web] [--debug[=full] [--editor host:port]]` | Packs the assets and builds the page; `--debug` adds the editor's page agent (read and cosmetic commands), `--debug=full` every command; `--editor` names where the agent finds the editor (default `127.0.0.1:47600`). A debug page is never shipped: a release page that carries the agent is refused |
+| `moku-game native build <target> [--simulator] [--debug[=full] [--editor host:port]]` | Builds the native app: `ios`, `macos`, `android`; `--debug` builds an Android debug app beside the store app |
 | `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 `generated/manifest.json` |
@@ -201,7 +201,7 @@ A rest node waits. A player answer comes through the gate. A world event comes t
 | Flow | `defineFlow(id, { nodes, start, edges })`. A flow with `outcomes` is a node of another flow. |
 | Edge target | A node name, `exit("outcome")` to leave a sub-flow, or `to("node", mapper)`. |
 | Slot | `slot("name")`. Features contribute sub-flows to it. |
-| Feature | `defineFeature(name, { nodes?, flows?, contribute? })`. A plugin that adds to the graph. |
+| Feature | `defineFeature(name, { nodes?, flows?, contribute?, features? })`. A plugin that adds to the graph. `features` declares the sub-features of the feature; `flattenFeatures` turns the tree into the plugin list. |
 | Effect | `await fx(descriptor)` for awaited effects, `fx.emit(hint(...))` for cosmetic ones. |
 | Transition | Rest node to rest node, as one transaction. An error rolls back and retries. |
 
@@ -225,10 +225,10 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 | [`world`](./src/plugins/world/README.md) | screen | A small ECS and projections from committed state |
 | [`renderer`](./src/plugins/renderer/README.md) | screen | Pixi v8, loaded lazily, synced from the ECS |
 | [`input`](./src/plugins/input/README.md) | screen | Gestures as data: tap, press, drag, swipe |
-| [`assets`](./src/plugins/assets/README.md) | screen | Manifest, load tiers, typed keys, the production pack |
-| [`scenes`](./src/plugins/scenes/README.md) | screen | A scene as a declaration: bundle, layers, music |
+| [`assets`](./src/plugins/assets/README.md) | screen | Manifest, load tiers, typed keys, the production pack; bundles per feature and sub-feature, `release: "leave"`, `mipmaps` |
+| [`scenes`](./src/plugins/scenes/README.md) | screen | A scene as a declaration: bundle, `bundles(state)`, layers, music |
 | [`anim`](./src/plugins/anim/README.md) | screen | Choreography as data: tweens, timelines, motions |
-| [`i18n`](./src/plugins/i18n/README.md) | screen | Strings as data, ICU messages, compiled per locale |
+| [`i18n`](./src/plugins/i18n/README.md) | screen | Strings as data, ICU messages, compiled per locale; a sub-feature's strings travel with its bundle |
 | [`text`](./src/plugins/text/README.md) | screen | MSDF text, styles, inline tags and icons |
 | [`ui`](./src/plugins/ui/README.md) | screen | Screens in JSX, Yoga layout, popups, styles |
 | [`effects`](./src/plugins/effects/README.md) | opt-in | Particles and filters as components, WGSL and GLSL |
@@ -258,7 +258,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. 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.
+`@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. Four layout rules check a game on the layered layout: the order of the layers, the doors of the features at any depth, the sub-features a feature declares and the suffix of each test file. Eleven rules in all; a flat game lints exactly as in 0.14.12.
 
 ```json
 // .oxlintrc.json
@@ -274,12 +274,13 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
     "moku-game/static-keys": "error",
     "moku-game/layer-imports": "error",
     "moku-game/feature-door": "error",
+    "moku-game/sub-features": "error",
     "moku-game/test-suffix": "error"
   }
 }
 ```
 
-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).
+Each rule takes `{ "files": [...], "ignores": [...] }`. `layer-imports`, `feature-door`, `sub-features` 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
 
@@ -332,7 +333,7 @@ A save of a logic file reloads the page. What swaps and what reloads: [docs/hot-
 
 - **Node `>= 24`** and **Bun `>= 1.4.2`**. Use `bun` only.
 - **TypeScript** in strict mode, with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`.
-- **`pixi.js` `^8.0.0`** as a peer dependency. `playwright-core` for visual tests, `sharp` for the asset pack, `typescript` for the project index, `@moku-labs/system` for the system shell and `@moku-labs/native` for the native build are optional peers. `yoga-layout` is loaded lazily by `ui`. The string compiler uses `@formatjs/icu-messageformat-parser` at build time only.
+- **`pixi.js` `^8.22.0`** as a peer dependency. `playwright-core` for visual tests, `sharp` for the asset pack, `typescript` for the project index, `@moku-labs/system` for the system shell and `@moku-labs/native` for the native build are optional peers. `yoga-layout` is loaded lazily by `ui`. The string compiler uses `@formatjs/icu-messageformat-parser` at build time only.
 - **[`@moku-labs/core`](https://github.com/moku-labs/core)** is the kernel. **[`@moku-labs/common`](https://github.com/moku-labs/common)** brings `log` and `env`.
 
 ## License

package/dist/app/page.d.mts

@@ -1,4 +1,4 @@
-import { m as StartedPage, r as GameConfig, t as AnyGameApp, u as PageOptions } from "../types-gisvSHoC.mjs";
+import { m as StartedPage, r as GameConfig, t as AnyGameApp, u as PageOptions } from "../types-C73hbmxi.mjs";
 
 //#region src/app/page.d.ts
 /**
@@ -6,8 +6,11 @@ import { m as StartedPage, r as GameConfig, t as AnyGameApp, u as PageOptions }
  * fresh memory save, never on the stored one), builds the system shell when the page has one,
  * picks the save, makes the screen app on `#game` over the device clock and the manifest next to
  * the page, sets `globalThis.game`, `system` and `doors`, follows reduced motion, starts the shell,
- * then the app, and runs the graph. A graph that stops is logged, never thrown. In dev it then
- * starts the agents. Every problem goes to the app's log.
+ * then the app, and runs the graph. A graph that stops is logged, never thrown. In dev and in a
+ * debug build it then logs `page:build` (the build id, the engine id, the control profile),
+ * starts the agents and shows the overlay as `config.ts` `debug.overlay` asks. Every problem goes
+ * to the app's log. On `pagehide` it flushes the save, and stops the app when the page is really
+ * left (`persisted` false); a page kept in the back/forward cache keeps its app running.
  *
  * @param game - The default export of the game's `index.ts`.
  * @param config - The default export of the game's `config.ts`.
@@ -18,6 +21,7 @@ import { m as StartedPage, r as GameConfig, t as AnyGameApp, u as PageOptions }
  * @example
  * ```ts
  * // Written by moku-game dev. Do not edit.
+ * import "./script.ts";
  * import "./dev.ts";
  * import "./assets-stamp.ts";
  * import { startPage } from "@moku-labs/game/app/page";
@@ -29,6 +33,7 @@ import { m as StartedPage, r as GameConfig, t as AnyGameApp, u as PageOptions }
  * import * as devModule0 from "../features/board/board.dev.ts";
  * import agent0 from "@moku-labs/editor/agent/page";
  *
+ * performance.mark("moku:main");
  * await startPage(game, config, {
  *   scenarios: { "empty": scenario0, "full": scenario1 },
  *   system: systemShellOf({

package/dist/app/page.mjs

@@ -1,7 +1,8 @@
 import { r as systemSource, t as memory } from "../memory-CWlqhS7l.mjs";
 import { t as applyTo } from "../drafts-BawpSaVp.mjs";
-import { n as read, r as watch, t as sources } from "../sources-Duzj6lhV.mjs";
-import { t as resolveConfig } from "../config-CdARrrhU.mjs";
+import { i as isControl } from "../dev-DbHgx-R-.mjs";
+import { n as read, r as watch, t as sources } from "../sources-Cdvb0rOS.mjs";
+import { t as resolveConfig } from "../config-B87aFTW-.mjs";
 //#region src/app/save.ts
 /**
 * @file The saves of the page: `localSave` keeps the player in `localStorage`, `pageSave` picks
@@ -170,9 +171,9 @@ function pageSave(kind, where) {
 * @file The `@moku-labs/game/app/page` entry: `startPage`, the page of a game. The generated
 * `.moku/main.ts` calls it with the game, its config and what the CLI found: scenarios, the system
 * shell, the dev agents and the `.dev` modules. It reaches the shell only through
-* `options.system`, never by an import, so a web-only page bundles no system code. Its dev parts
-* (the write door `/control`, the agents, the audio journal) sit behind the inline dev guard, so a
-* production build drops them.
+* `options.system`, never by an import, so a web-only page bundles no system code. The write door
+* `/control` and the agents sit behind the inline dev or agent guard, the audio journal behind
+* the dev guard, so a production build drops them; a debug build keeps the door and the agents.
 */
 /** How many started sounds the audio journal of the dev page keeps. */
 const DEV_AUDIO_JOURNAL = 200;
@@ -252,7 +253,7 @@ function screenOf(game, runtime) {
 }
 /**
 * Sets the three handles of the page on `globalThis`: `game` for e2e, `system` for the shell,
-* `doors` for the editor. The write door `/control` is loaded in dev only.
+* `doors` for the editor. `/control` is loaded on the dev page and on a debug page.
 *
 * @param app - The screen app.
 * @param shell - The system shell, or `undefined`.
@@ -261,7 +262,7 @@ function screenOf(game, runtime) {
 async function setHandles(app, shell) {
 	Reflect.set(globalThis, "game", app);
 	Reflect.set(globalThis, "system", shell?.handle);
-	const control = typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ ? await import("../control.mjs") : void 0;
+	const control = typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ || typeof __MOKU_GAME_AGENT__ !== "undefined" && __MOKU_GAME_AGENT__ ? await import("../control.mjs") : void 0;
 	Reflect.set(globalThis, "doors", {
 		read,
 		watch,
@@ -284,8 +285,27 @@ function followReducedMotion(app) {
 	reducedMotion.addEventListener("change", (event) => app.anim.setReducedMotion(event.matches));
 }
 /**
-* Starts the dev agents, in order, after the app: each gets the app, the page title and the
-* game's `.dev` modules. A throwing agent is logged and the page keeps running.
+* Follows the page out. On `pagehide` the save is flushed at once: the browser waits for no
+* promise there, so the write starts now, and the failure, if any, is already in the log. A page
+* going into the back/forward cache (`persisted`) may come back with its app running, so only a
+* page that is really left stops its app, once.
+*
+* @param app - The started screen app.
+*/
+function followPageHide(app) {
+	const listener = (event) => {
+		app.model.store.flush().catch(() => {});
+		if (event.persisted) return;
+		removeEventListener("pagehide", listener);
+		app.stop().catch((error) => {
+			app.log.error("[game] The page did not stop cleanly.", void 0, toError(error));
+		});
+	};
+	addEventListener("pagehide", listener);
+}
+/**
+* Starts the agents, in order, after the app, in dev and in a debug build: each gets the app, the
+* page title and the game's `.dev` modules. A throwing agent is logged and the page keeps running.
 *
 * @param app - The running app.
 * @param settings - The resolved config.
@@ -304,12 +324,26 @@ async function startAgents(app, settings, options) {
 	}
 }
 /**
+* Shows the editor's overlay the way `config.ts` `debug.overlay` asks, once the agents started: the agent's channel
+* exists only then.
+*
+* @param app - The running app.
+* @param overlay - `"closed"` makes no call, `"pill"` opens the pill, `"open"` the card.
+*/
+function openStartOverlay(app, overlay) {
+	if (overlay === "closed") return;
+	app.debug.overlay.open({ mode: overlay === "pill" ? "pill" : "card" });
+}
+/**
 * Runs a game on its page: resolves `config.ts`, picks the start (a `?player=` scenario runs on a
 * fresh memory save, never on the stored one), builds the system shell when the page has one,
 * picks the save, makes the screen app on `#game` over the device clock and the manifest next to
 * the page, sets `globalThis.game`, `system` and `doors`, follows reduced motion, starts the shell,
-* then the app, and runs the graph. A graph that stops is logged, never thrown. In dev it then
-* starts the agents. Every problem goes to the app's log.
+* then the app, and runs the graph. A graph that stops is logged, never thrown. In dev and in a
+* debug build it then logs `page:build` (the build id, the engine id, the control profile),
+* starts the agents and shows the overlay as `config.ts` `debug.overlay` asks. Every problem goes
+* to the app's log. On `pagehide` it flushes the save, and stops the app when the page is really
+* left (`persisted` false); a page kept in the back/forward cache keeps its app running.
 *
 * @param game - The default export of the game's `index.ts`.
 * @param config - The default export of the game's `config.ts`.
@@ -320,6 +354,7 @@ async function startAgents(app, settings, options) {
 * @example
 * ```ts
 * // Written by moku-game dev. Do not edit.
+* import "./script.ts";
 * import "./dev.ts";
 * import "./assets-stamp.ts";
 * import { startPage } from "@moku-labs/game/app/page";
@@ -331,6 +366,7 @@ async function startAgents(app, settings, options) {
 * import * as devModule0 from "../features/board/board.dev.ts";
 * import agent0 from "@moku-labs/editor/agent/page";
 *
+* performance.mark("moku:main");
 * await startPage(game, config, {
 *   scenarios: { "empty": scenario0, "full": scenario1 },
 *   system: systemShellOf({
@@ -370,7 +406,16 @@ async function startPage(game, config, options = {}) {
 	app.flow.run().catch((error) => {
 		app.log.error("[game] The graph stopped.", void 0, toError(error));
 	});
-	if (typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__) await startAgents(app, settings, options);
+	if (typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ || typeof __MOKU_GAME_AGENT__ !== "undefined" && __MOKU_GAME_AGENT__) {
+		app.log.info("page:build", {
+			build: globalThis.__MOKU_GAME_BUILD__ ?? "dev",
+			engine: globalThis.__MOKU_GAME_ENGINE__ ?? null,
+			control: isControl() ? "full" : "read"
+		});
+		await startAgents(app, settings, options);
+		openStartOverlay(app, settings.debug.overlay);
+	}
+	followPageHide(app);
 	return {
 		app,
 		system: shell?.handle

package/dist/app/system.d.mts

@@ -1,6 +1,6 @@
-import { nn as PlayerStateProvider } from "../types-BjTtGSFb.mjs";
-import { ct as PlatformProvider } from "../index-CLQ8NOTw.mjs";
-import { _ as SystemShellFactory, g as SystemName, h as SystemModules } from "../types-gisvSHoC.mjs";
+import { hr as PlayerStateProvider } from "../types-BGcda5Le.mjs";
+import { ft as PlatformProvider } from "../index-DedbED3T.mjs";
+import { _ as SystemShellFactory, g as SystemName, h as SystemModules } from "../types-C73hbmxi.mjs";
 import { Back, Haptics, KeepAwake, Lifecycle, Store } from "@moku-labs/system";
 
 //#region src/app/system.d.ts
@@ -126,11 +126,13 @@ declare function storeSave(store: StoreSlice, key: string, report: (problem: str
  * @example
  * ```ts
  * // The in-memory .moku/build/main.ts of moku-game build, for a game whose config.ts names back.
+ * import "./script.ts";
  * import { startPage } from "@moku-labs/game/app/page";
  * import { systemShellOf } from "@moku-labs/game/app/system";
  * import game from "../../index.ts";
  * import config from "../../config.ts";
  *
+ * performance.mark("moku:main");
  * await startPage(game, config, {
  *   system: systemShellOf({
  *     system: () => import("@moku-labs/system"),

package/dist/app/system.mjs

@@ -300,11 +300,13 @@ function storeSave(store, key, report) {
 * @example
 * ```ts
 * // The in-memory .moku/build/main.ts of moku-game build, for a game whose config.ts names back.
+* import "./script.ts";
 * import { startPage } from "@moku-labs/game/app/page";
 * import { systemShellOf } from "@moku-labs/game/app/system";
 * import game from "../../index.ts";
 * import config from "../../config.ts";
 *
+* performance.mark("moku:main");
 * await startPage(game, config, {
 *   system: systemShellOf({
 *     system: () => import("@moku-labs/system"),

package/dist/app.d.mts

@@ -1,5 +1,6 @@
-import { Zt as Json } from "./types-BjTtGSFb.mjs";
-import { a as GameHandle, c as MemoryProvider, d as SaveKind, f as Scenario, g as SystemName, i as GameDefinition, l as PageAgent, n as GameApp, o as GamePluginConfigs, p as ScreenSeams, r as GameConfig, s as HeadlessSeams } from "./types-gisvSHoC.mjs";
+import { ur as Json } from "./types-BGcda5Le.mjs";
+import { V as StringTable } from "./types-7GXcXxxv.mjs";
+import { a as GameHandle, c as MemoryProvider, d as SaveKind, f as Scenario, g as SystemName, i as GameDefinition, l as PageAgent, n as GameApp, o as GamePluginConfigs, p as ScreenSeams, r as GameConfig, s as HeadlessSeams, v as WithGameState } from "./types-C73hbmxi.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/app/define.d.ts
@@ -15,23 +16,30 @@ declare const startMoment = 1000000;
 /**
  * Turns a game's one data object into the game: `game.headless()` for logic tests and
  * `game.screen()` for the page and the screen tests. Every type comes from the object: the plugin
- * tuples, the player and the session. Checks the definition at once, so an error points at
+ * tuples, the player, the session and, through `strings: type<Strings>()`, the string keys. Checks the definition at once, so an error points at
  * `index.ts`.
  *
  * @param definition - The game: its flow, starting state, features, plugins and plugin configs.
  * @returns The game, with `headless()` and `screen()`; no app is created yet.
- * @throws {Error} When `flow` is missing, or an entry of `shared`, `features` or `headless.features` is not a feature.
+ * @throws {Error} When `flow` is missing, or an entry of `shared`, `features` or `headless.features`
+ *   is not a feature, at any depth of the tree.
+ * @throws {Error} When a feature name is listed twice in `features` or in `headless.features`: the
+ *   game and a parent both list it, or two parents declare it.
+ * @throws {Error} When `shared` declares sub-features.
+ * @throws {Error} When `referenceSide` is not a finite number above 0, or `orientation` is neither
+ *   `"portrait"` nor `"landscape"`.
  * @example
  * ```ts
  * // index.ts of a game: the whole game, no createApp call. Its tests import it as `game`.
  * export default defineGameApp({
- *   flow: mainFlow, safeNode: "home", player: startingPlayer, session: startingSession,
+ *   flow: mainFlow, safeNode: "home", player: startingPlayer, session: startingSession, strings: type<Strings>(),
  *   shared: sharedFeature, features: [homeFeature, boardFeature, rewardFeature], plugins: [loadingPlugin],
  *   headless: { features: [rewardFeature] }, pluginConfigs: { ui: { tapTargetPt: 48 } }
  * });
  * game.headless({ seed: 7 }).app.flow.state().running; // false: the test starts it
+ * game.screen().app.i18n.isKey("home.play"); // a guard to the game's keys: true for a key of Strings
  * ```
  */
-declare function defineGameApp<const Plugins extends readonly AnyPluginInstance[] = readonly [], const HeadlessPlugins extends readonly AnyPluginInstance[] = readonly [], Player extends Json = Json, Session extends Json = Json>(definition: GameDefinition<Plugins, HeadlessPlugins, Player, Session>): GameApp<Plugins, HeadlessPlugins, Player, Session>;
+declare function defineGameApp<const Plugins extends readonly AnyPluginInstance[] = readonly [], const HeadlessPlugins extends readonly AnyPluginInstance[] = readonly [], Player extends Json = Json, Session extends Json = Json, Strings extends StringTable = StringTable>(definition: GameDefinition<Plugins, HeadlessPlugins, Player, Session, Strings>): GameApp<Plugins, HeadlessPlugins, Player, Session, Strings>;
 //#endregion
-export { type GameApp, type GameConfig, type GameDefinition, type GameHandle, type GamePluginConfigs, type HeadlessSeams, type MemoryProvider, type PageAgent, type SaveKind, type Scenario, type ScreenSeams, type SystemName, defineGameApp, startMoment };
+export { type GameApp, type GameConfig, type GameDefinition, type GameHandle, type GamePluginConfigs, type HeadlessSeams, type MemoryProvider, type PageAgent, type SaveKind, type Scenario, type ScreenSeams, type SystemName, type WithGameState, defineGameApp, startMoment };

package/dist/app.mjs

@@ -1,6 +1,6 @@
-import { Ct as effectsPlugin, H as platformPlugin, Nt as audioPlugin, i as screen, t as createApp } from "./src-CtC8w3_z.mjs";
+import { Dt as effectsPlugin, K as platformPlugin, Rt as audioPlugin, i as screen, p as flattenFeatures, t as createApp } from "./src-BEbJ_sSx.mjs";
 import { t as memory } from "./memory-CWlqhS7l.mjs";
-import { t as fakeClock } from "./fake-MpzwZhIZ.mjs";
+import { n as isFakeClock, t as fakeClock } from "./fake-6mazmHK3.mjs";
 //#region src/app/define.ts
 /**
 * The moment the default fake clock starts at, in epoch milliseconds. A test stamps times from it.
@@ -13,12 +13,13 @@ import { t as fakeClock } from "./fake-MpzwZhIZ.mjs";
 const startMoment = 1e6;
 /** The rng seed of a new save when neither the definition nor the seam names one. */
 const defaultSeed = 42;
-/** The plugins every app has: the engine's core five and the core plugins `log` and `env`. */
+/** The plugins every app has: the engine's core six and the core plugins `log` and `env`. */
 const corePluginNames = [
 	"time",
 	"lifecycle",
 	"model",
 	"clock",
+	"debug",
 	"flow",
 	"log",
 	"env"
@@ -37,27 +38,108 @@ function notAFeature(path) {
 	return /* @__PURE__ */ new Error(`[game] defineGameApp: ${path} is not a feature.\n  Make it with defineFeature(name, description).`);
 }
 /**
-* Throws for the first entry of a feature list that `defineFeature` did not make. The type already
-* says so; a game in JavaScript, or one that casts, is caught here, at the definition.
+* Builds the error of a feature name met twice in one list.
 *
-* @param list - `features`, `headless.features`, or `[shared]`.
-* @param pathOf - Names an entry by its index.
-* @throws {Error} When an entry has no `logicOnly`.
+* @param name - The feature name.
+* @param first - The path met first in the walk.
+* @param second - The path met second.
+* @returns The error.
+* @example
+* ```ts
+* listedTwice("ep01", "features[1].features[1]", "features[2]").message; // "[game] defineGameApp: the feature \"ep01\" is listed twice: features[1].features[1] and features[2].\n  List a sub-feature only in the features of its parent."
+* ```
+*/
+function listedTwice(name, first, second) {
+	return /* @__PURE__ */ new Error(`[game] defineGameApp: the feature "${name}" is listed twice: ${first} and ${second}.\n  List a sub-feature only in the features of its parent.`);
+}
+/**
+* Lists every entry of a feature list and of the sub-features under it, depth first, a parent
+* before its children, each with its path. An entry without a `features` list has no children.
+*
+* @param list - A feature list, or the `features` of one entry.
+* @param path - Where the list is: `features`, `features[1].features`.
+* @returns The entries with their paths.
 */
-function checkFeatures(list, pathOf) {
-	for (const [index, entry] of list.entries()) if (entry?.logicOnly === void 0) throw notAFeature(pathOf(index));
+function walkTree(list, path) {
+	return list.flatMap((entry, index) => {
+		const at = `${path}[${index}]`;
+		return [{
+			path: at,
+			entry
+		}, ...walkTree(entry?.features ?? [], `${at}.features`)];
+	});
+}
+/**
+* Throws for the first entry of a feature tree, at any depth, that `defineFeature` did not make,
+* and for a feature name met twice in the tree. The type already rules out the first; a game in
+* JavaScript, or one that casts, is caught here, at the definition.
+*
+* @param list - `features` or `headless.features`.
+* @param root - The name of the list in the paths.
+* @throws {Error} When an entry has no `logicOnly`, or a name is listed twice.
+*/
+function checkTree(list, root) {
+	const firstPaths = /* @__PURE__ */ new Map();
+	for (const { path, entry } of walkTree(list, root)) {
+		if (entry?.logicOnly === void 0) throw notAFeature(path);
+		const first = firstPaths.get(entry.name);
+		if (first !== void 0) throw listedTwice(entry.name, first, path);
+		firstPaths.set(entry.name, path);
+	}
+}
+/**
+* Throws for a `shared` that is not a feature, or that declares sub-features: the shared layer is
+* composed alone, so its children would never be.
+*
+* @param shared - The shared layer of the definition.
+* @throws {Error} When `shared` has no `logicOnly`, or its `features` is not empty.
+*/
+function checkShared(shared) {
+	if (shared.logicOnly === void 0) throw notAFeature("shared");
+	if ((shared.features ?? []).length > 0) throw new Error("[game] defineGameApp: shared declares sub-features.\n  The shared layer has none: declare them in a feature of features.");
+}
+/**
+* Writes a value after `got` in an error: a string in quotes, anything else as it prints.
+*
+* @param value - The value the definition holds.
+* @returns The value as the error shows it.
+* @example
+* ```ts
+* shown("390"); // "\"390\""
+* ```
+*/
+function shown(value) {
+	return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+/**
+* Throws for a design frame the engine would draw wrong: a `referenceSide` that is not a finite
+* number above 0 (the fit answers scale 1, CSS-pixel size), and an `orientation` other than
+* `"portrait"` or `"landscape"` (most often `page.orientation`'s `"any"`). `referenceLong: 0` is
+* a documented value and is not checked.
+*
+* @param definition - The game's definition.
+* @throws {Error} When `referenceSide` or `orientation` is set to a value the engine cannot lay out.
+*/
+function checkFrame(definition) {
+	const side = definition.referenceSide;
+	const orientation = definition.orientation;
+	if (side !== void 0 && !(typeof side === "number" && Number.isFinite(side) && side > 0)) throw new Error(`[game] defineGameApp: referenceSide must be a finite number above 0, got ${shown(side)}.\n  Pass the short side of the design frame in reference units: defineGameApp({ referenceSide: 390, ... }).`);
+	if (orientation !== void 0 && orientation !== "portrait" && orientation !== "landscape") throw new Error(`[game] defineGameApp: orientation must be "portrait" or "landscape", got ${shown(orientation)}.\n  The layout is designed for one orientation. A native build that turns with the device sets page.orientation: "any" in config.ts.`);
 }
 /**
 * Checks what TypeScript cannot stop: a definition from JavaScript, or one that casts.
 *
 * @param definition - The game's definition.
-* @throws {Error} When `flow` is missing, or a feature entry is not a feature.
+* @throws {Error} When `flow` is missing, a feature entry at any depth is not a feature, a feature
+*   name is listed twice in one list, `shared` declares sub-features, or the design frame is one
+*   the engine cannot lay out.
 */
 function checkDefinition(definition) {
 	if (definition.flow === void 0) throw new Error("[game] defineGameApp needs flow.\n  Pass the main flow: defineGameApp({ flow: mainFlow, ... }).");
-	if (definition.shared !== void 0) checkFeatures([definition.shared], () => "shared");
-	checkFeatures(definition.features ?? [], (index) => `features[${index}]`);
-	checkFeatures(definition.headless?.features ?? [], (index) => `headless.features[${index}]`);
+	if (definition.shared !== void 0) checkShared(definition.shared);
+	checkTree(definition.features ?? [], "features");
+	checkTree(definition.headless?.features ?? [], "headless.features");
+	checkFrame(definition);
 }
 /**
 * Copies the keys of a seam whose value is set, so a seam left out never erases a game value.
@@ -75,7 +157,9 @@ function definedKeys(seam) {
 }
 /**
 * Merges the seam-owned keys over the game's plugin configs, one plugin at a time: a key the game
-* owns stays, a key the shell owns is written. With `screen` the screen keys are written too.
+* owns stays, a key the shell owns is written. With `screen` the screen keys are written too. The
+* game's adaptive frame rate stands only in a screen app on a device clock (the page): a headless
+* app and a screen app on a fake clock never adapt.
 *
 * @param definition - The game's definition.
 * @param seams - The seams of this call.
@@ -99,6 +183,10 @@ function mergeConfigs(definition, seams, runtime, withScreen) {
 			...game.flow,
 			mainFlow: definition.flow,
 			safeNode: definition.safeNode
+		},
+		time: {
+			...game.time,
+			...withScreen && !isFakeClock(runtime.clock) ? {} : { adaptive: false }
 		}
 	};
 	if (!withScreen) return logic;
@@ -149,8 +237,10 @@ function runtimeOf(seams) {
 	};
 }
 /**
-* Creates one app over the engine: the plugins in order, the merged configs, and `referenceLong`
-* only when the definition sets it.
+* Creates one app over the engine: the plugins in order, the merged configs, and the frame keys
+* `orientation`, `referenceSide` and `referenceLong` only when the definition sets them. A
+* definition that sets none passes no `config` key, so the core defaults stay the one place of
+* truth.
 *
 * @param definition - The game's definition.
 * @param plugins - The plugins beyond the core, in order.
@@ -158,16 +248,22 @@ function runtimeOf(seams) {
 * @returns The app, not started.
 */
 function appOf(definition, plugins, pluginConfigs) {
+	const frame = definedKeys({
+		orientation: definition.orientation,
+		referenceSide: definition.referenceSide,
+		referenceLong: definition.referenceLong
+	});
 	return createApp({
 		plugins: [...plugins],
 		pluginConfigs,
-		...definition.referenceLong === void 0 ? {} : { config: { referenceLong: definition.referenceLong } }
+		...Object.keys(frame).length === 0 ? {} : { config: frame }
 	});
 }
 /**
-* Makes the headless app of a definition: the logic of `headless.features`, then
-* `headless.plugins`. Without a `headless.features` list it takes `features`; an empty list means
-* none. `shared` is not composed.
+* Makes the headless app of a definition: the logic of `headless.features` and of their
+* sub-features, then `headless.plugins`. Without a `headless.features` list it takes `features`;
+* an empty list means none. `shared` is not composed. The `logicOnly` is taken before flattening:
+* a parent's `logicOnly` carries its children's.
 *
 * @param definition - The game's definition.
 * @param seams - The seams of this call.
@@ -175,7 +271,7 @@ function appOf(definition, plugins, pluginConfigs) {
 */
 function headlessOf(definition, seams) {
 	const runtime = runtimeOf(seams);
-	const plugins = [...(definition.headless?.features ?? definition.features ?? []).map((feature) => feature.logicOnly), ...definition.headless?.plugins ?? []];
+	const plugins = [...flattenFeatures((definition.headless?.features ?? definition.features ?? []).map((feature) => feature.logicOnly)), ...definition.headless?.plugins ?? []];
 	return {
 		app: appOf(definition, plugins, composedOnly(mergeConfigs(definition, seams, runtime, false), plugins)),
 		...runtime
@@ -183,7 +279,8 @@ function headlessOf(definition, seams) {
 }
 /**
 * Makes the screen app of a definition: the screen set, `audio`, `effects`, `platform`, then
-* `shared`, the features and the game's plugins.
+* `shared`, the features with their sub-features (depth first, a parent before its children) and
+* the game's plugins.
 *
 * @param definition - The game's definition.
 * @param seams - The seams of this call.
@@ -198,7 +295,7 @@ function screenOf(definition, seams) {
 			effectsPlugin,
 			platformPlugin,
 			...definition.shared === void 0 ? [] : [definition.shared],
-			...definition.features ?? [],
+			...flattenFeatures(definition.features ?? []),
 			...definition.plugins ?? []
 		], mergeConfigs(definition, seams, runtime, true)),
 		...runtime
@@ -207,21 +304,28 @@ function screenOf(definition, seams) {
 /**
 * Turns a game's one data object into the game: `game.headless()` for logic tests and
 * `game.screen()` for the page and the screen tests. Every type comes from the object: the plugin
-* tuples, the player and the session. Checks the definition at once, so an error points at
+* tuples, the player, the session and, through `strings: type<Strings>()`, the string keys. Checks the definition at once, so an error points at
 * `index.ts`.
 *
 * @param definition - The game: its flow, starting state, features, plugins and plugin configs.
 * @returns The game, with `headless()` and `screen()`; no app is created yet.
-* @throws {Error} When `flow` is missing, or an entry of `shared`, `features` or `headless.features` is not a feature.
+* @throws {Error} When `flow` is missing, or an entry of `shared`, `features` or `headless.features`
+*   is not a feature, at any depth of the tree.
+* @throws {Error} When a feature name is listed twice in `features` or in `headless.features`: the
+*   game and a parent both list it, or two parents declare it.
+* @throws {Error} When `shared` declares sub-features.
+* @throws {Error} When `referenceSide` is not a finite number above 0, or `orientation` is neither
+*   `"portrait"` nor `"landscape"`.
 * @example
 * ```ts
 * // index.ts of a game: the whole game, no createApp call. Its tests import it as `game`.
 * export default defineGameApp({
-*   flow: mainFlow, safeNode: "home", player: startingPlayer, session: startingSession,
+*   flow: mainFlow, safeNode: "home", player: startingPlayer, session: startingSession, strings: type<Strings>(),
 *   shared: sharedFeature, features: [homeFeature, boardFeature, rewardFeature], plugins: [loadingPlugin],
 *   headless: { features: [rewardFeature] }, pluginConfigs: { ui: { tapTargetPt: 48 } }
 * });
 * game.headless({ seed: 7 }).app.flow.state().running; // false: the test starts it
+* game.screen().app.i18n.isKey("home.play"); // a guard to the game's keys: true for a key of Strings
 * ```
 */
 function defineGameApp(definition) {