@moku-labs/game 0.14.12 → 0.14.13

package/dist/{types-gisvSHoC.d.mts → types-C73hbmxi.d.mts}

@@ -1,9 +1,56 @@
-import { Dt as AnyFlow, Gt as FakeClock, Ut as ClockSource, Yt as Config, Zt as Json, a as Config$3, g as Config$2, ht as FeaturePlugin, n as AssetsIo, nn as PlayerStateProvider, pt as Config$1, u as Manifest, v as PixiModule } from "./types-BjTtGSFb.mjs";
-import { o as AudioContextLike, s as Config$4 } from "./types-Y_rCuXtj.mjs";
-import { _t as audioPlugin, ct as PlatformProvider, ht as effectsPlugin, i as screen, ot as platformPlugin, t as createApp } from "./index-CLQ8NOTw.mjs";
-import { t as memory } from "./memory-pUQ7YZWC.mjs";
+import { E as Config$2, In as FeaturePlugin, Rn as AnyFlow, Sn as Config$1, _r as SaveDoc, a as Config$3, br as SnapshotOf, cr as Config, d as Manifest, gr as ProviderCall, hr as PlayerStateProvider, ir as FakeClock, k as PixiModule, n as AssetsIo, nr as ClockSource, qn as TypeTag, ur as Json, vt as Orientation } from "./types-BGcda5Le.mjs";
+import { o as AudioContextLike, s as Config$4 } from "./types-GHE4J5Uf.mjs";
+import { H as TextKey, I as I18nApi, V as StringTable } from "./types-7GXcXxxv.mjs";
+import { St as audioPlugin, ft as PlatformProvider, i as screen, t as createApp, ut as platformPlugin, yt as effectsPlugin } from "./index-DedbED3T.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
+//#region src/plugins/model/store/providers/memory.d.ts
+/**
+ * Creates an in-memory provider that keeps what it was committed and records every call.
+ * It is the default when a game configures no `playerProvider`, and the double every test uses:
+ * `provider.calls` is the whole persistence protocol of one run, in order. The document lives as
+ * long as the provider does, so a second app over the same instance reads what the first one
+ * wrote, and nothing survives the process.
+ *
+ * `load()` reads the fixture, or everything committed since; without either, the player is new.
+ * `commitDurable()` resolves at once: there is no disk behind it.
+ *
+ * @param fixture - The save `load()` starts from. Omitted: a new player.
+ * @param fixture.state - The saved document.
+ * @param fixture.version - Schema version of the saved document.
+ * @returns A provider that keeps its document and records its calls.
+ * @example
+ * ```ts
+ * // A new player is saved at once. One roll reaches the provider at the next rest node.
+ * const provider = memory();
+ * const game = await createHeadless(createGame(provider));
+ *
+ * await game.walk([{ at: "home", intent: "roll" }]);
+ * provider.calls.map(call => call.method); // ["load", "commit", "commit"]
+ * ```
+ */
+declare function memory(fixture?: {
+  state: SaveDoc;
+  version: number;
+}): PlayerStateProvider & {
+  calls: ProviderCall[];
+};
+/**
+ * Builds a save document from a player tree, with no rng streams drawn yet.
+ * Short fixtures in tests read as `saveOf({ coins: 5 })` instead of spelling out the rng branch.
+ *
+ * @param player - Player tree of the save.
+ * @param seed - Rng seed of the save.
+ * @returns The save document.
+ * @example
+ * ```ts
+ * // A returning player with 5 coins. The test starts from this save, not from `initialPlayer`.
+ * saveOf({ coins: 5 }, 42); // { player: { coins: 5 }, rng: { seed: 42, streams: {} } }
+ * const provider = memory({ state: saveOf({ coins: 5 }, 42), version: 1 });
+ * ```
+ */
+declare function saveOf(player: Json, seed?: number): SaveDoc;
+//#endregion
 //#region src/app/types.d.ts
 /**
  * The name of a `@moku-labs/system` plugin the game shell wires, as the system package names it.
@@ -64,8 +111,25 @@ type GameConfig = {
   save?: SaveKind; /** The asset build. Default: no layers. */
   assets?: {
     /** Asset layers by name: `{ shared: "ui" }` packs the shared layer from `features/ui`. */layers?: Readonly<Record<string, string>>;
+  }; /** The debug page. Read only on a page with the agent. Default: `{ overlay: "closed" }`. */
+  debug?: {
+    /**
+     * How the editor's overlay shows when a debug page starts: `"closed"` (default), the `"pill"`, or `"open"` (the
+     * card). Only a page with the agent reads it.
+     */
+    overlay?: OverlayStart;
   };
 };
+/**
+ * How the editor's overlay shows when a debug page starts, `config.ts` `debug.overlay`.
+ *
+ * @example
+ * ```ts
+ * // QA builds of the game start with the small pill shown.
+ * const start: OverlayStart = "pill";
+ * ```
+ */
+type OverlayStart = "closed" | "pill" | "open";
 /**
  * `GameConfig` with every default filled, as `resolveConfig` returns it. The page, the CLI and the
  * shell read this one, never the raw config.
@@ -74,7 +138,7 @@ type GameConfig = {
  * ```ts
  * const settings: ResolvedGameConfig = {
  *   page: { title: "mini-game", lang: "en", background: "#000000", orientation: "portrait", icons: {}, head: [] },
- *   native: undefined, system: [], save: "memory", assets: { layers: {} }
+ *   native: undefined, system: [], save: "memory", assets: { layers: {} }, debug: { overlay: "closed" }
  * };
  * ```
  */
@@ -85,6 +149,9 @@ type ResolvedGameConfig = {
   save: SaveKind; /** The asset build. */
   assets: {
     layers: Readonly<Record<string, string>>;
+  }; /** The debug page: how the overlay shows at its start. */
+  debug: {
+    overlay: OverlayStart;
   };
 };
 /**
@@ -147,24 +214,35 @@ type GamePluginConfigs<Plugins extends readonly AnyPluginInstance[] = readonly [
  * };
  * ```
  */
-type GameDefinition<Plugins extends readonly AnyPluginInstance[] = readonly [], HeadlessPlugins extends readonly AnyPluginInstance[] = readonly [], Player extends Json = Json, Session extends Json = Json> = {
-  /** The main flow. */flow: AnyFlow; /** The checkpoint entered after a failed retry. Default: the start of the main flow. */
+type GameDefinition<Plugins extends readonly AnyPluginInstance[] = readonly [], HeadlessPlugins extends readonly AnyPluginInstance[] = readonly [], Player extends Json = Json, Session extends Json = Json, Strings extends StringTable = StringTable> = {
+  /** The main flow. */flow: AnyFlow;
+  /**
+   * The generated `Strings` type of the game, as a type tag: `strings: type<Strings>()`. Only the
+   * compiler reads it: `app.i18n.isKey(value)` of the game's app then narrows to a key of the table.
+   * Left out, `isKey` narrows to `string`.
+   */
+  strings?: TypeTag<Strings>; /** The checkpoint entered after a failed retry. Default: the start of the main flow. */
   safeNode?: string; /** The player a new save starts from. */
   player: Player; /** The session at every start. */
-  session: Session; /** The long side the layout needs, in reference units. Default 1920. */
+  session: Session; /** The orientation the layout is designed for. Default `"portrait"`. Not `page.orientation` of `config.ts`, which locks the native build. */
+  orientation?: Orientation; /** The short side of the design frame, in reference units. Default 1080. */
+  referenceSide?: number; /** The long side the layout needs, in reference units. Default 1920. */
   referenceLong?: number; /** The rng seed of a new save. Default 42. */
   seed?: number; /** The shared layer: composed first among the features. */
   shared?: FeaturePlugin;
   /**
    * The features of the screen app, in order, after `shared`. The headless app composes their
-   * logic too, unless `headless.features` names its own list.
+   * logic too, unless `headless.features` names its own list. A feature that declares sub-features
+   * (`defineFeature(name, { features })`) brings them: list the parent only; the shell composes the
+   * tree depth first, a parent before its children.
    */
   features?: readonly FeaturePlugin[]; /** The game's own plugins, after the features. Their APIs land on `screen().app`. */
   plugins?: Plugins;
   /**
    * What the headless app composes: the logic of these features and these plugins, nothing else.
    * `headless.features` left out is the definition's `features`; `headless: { features: [] }`
-   * composes no feature. `shared` and `plugins` are never taken by default.
+   * composes no feature. `shared` and `plugins` are never taken by default. A parent brings the
+   * logic of its sub-features, depth first; `headless.features` may name a sub-feature alone.
    */
   headless?: {
     features?: readonly FeaturePlugin[];
@@ -183,6 +261,40 @@ type GameDefinition<Plugins extends readonly AnyPluginInstance[] = readonly [],
  * ```
  */
 type MemoryProvider = ReturnType<typeof memory>;
+/** The app with `model.store.snapshot()` typed by the game's player and session. */
+type WithGameSnapshot<App, Player, Session> = App extends {
+  model: {
+    store: {
+      snapshot(): unknown;
+    };
+  };
+} ? Omit<App, "model"> & {
+  model: Omit<App["model"], "store"> & {
+    store: Omit<App["model"]["store"], "snapshot"> & {
+      snapshot(): SnapshotOf<Player, Session>;
+    };
+  };
+} : App;
+/** The app with `i18n` typed by the game's strings table; an app without i18n, or the wide table, is left as it is. */
+type WithGameStrings<App, Strings extends StringTable> = App extends {
+  i18n: I18nApi;
+} ? StringTable extends Strings ? App : Omit<App, "i18n"> & {
+  i18n: I18nApi<TextKey<Strings>>;
+} : App;
+/**
+ * The app of one game with `model.store.snapshot()` typed by the game's player and session, and
+ * `i18n.isKey` by the game's strings table. Only the type: the store and the i18n API are the
+ * engine's, and every other member is the app's own.
+ *
+ * @example
+ * ```ts
+ * const { app } = game.headless();
+ * app.model.store.snapshot().player.count; // 0, typed number
+ * // A game whose index.ts passes strings: type<Strings>(): the screen app narrows a saved key.
+ * game.screen().app.i18n.isKey("ui.toast.saved"); // true once started, typed I18n.TextKey<Strings>
+ * ```
+ */
+type WithGameState<App, Player, Session, Strings extends StringTable = StringTable> = WithGameStrings<WithGameSnapshot<App, Player, Session>, Strings>;
 /**
  * What one call of `headless()` or `screen()` gives: the app, not started, and the clock and save
  * provider it runs on, so a test can move the time and read the save.
@@ -366,7 +478,7 @@ type ScreenSeams<Player, Session, Source, Provider> = HeadlessSeams<Player, Sess
  * const { app, clock, provider } = game.headless({ seed: 7 });
  * ```
  */
-type GameApp<Plugins extends readonly AnyPluginInstance[] = readonly [], HeadlessPlugins extends readonly AnyPluginInstance[] = readonly [], Player extends Json = Json, Session extends Json = Json> = {
+type GameApp<Plugins extends readonly AnyPluginInstance[] = readonly [], HeadlessPlugins extends readonly AnyPluginInstance[] = readonly [], Player extends Json = Json, Session extends Json = Json, Strings extends StringTable = StringTable> = {
   /**
    * Makes the logic app: the core plugins, the logic of `headless.features` and the
    * `headless.plugins`. A definition without `headless.features` gives the logic of its
@@ -383,7 +495,7 @@ type GameApp<Plugins extends readonly AnyPluginInstance[] = readonly [], Headles
    * run.state().path; // "home"
    * ```
    */
-  headless<Source extends ClockSource = FakeClock, Provider extends PlayerStateProvider = MemoryProvider>(seams?: HeadlessSeams<Player, Session, Source, Provider>): GameHandle<HeadlessAppOf<HeadlessPlugins>, Source, Provider>;
+  headless<Source extends ClockSource = FakeClock, Provider extends PlayerStateProvider = MemoryProvider>(seams?: HeadlessSeams<Player, Session, Source, Provider>): GameHandle<WithGameState<HeadlessAppOf<HeadlessPlugins>, Player, Session, Strings>, Source, Provider>;
   /**
    * Makes the screen app: the screen set, `audio`, `effects`, `platform`, then `shared`, the
    * features and the game's plugins, in that order. Without a mount the renderer is inert, so the
@@ -399,7 +511,7 @@ type GameApp<Plugins extends readonly AnyPluginInstance[] = readonly [], Headles
    * app.flow.state().path; // "home" once the runner rests
    * ```
    */
-  screen<Source extends ClockSource = FakeClock, Provider extends PlayerStateProvider = MemoryProvider>(seams?: ScreenSeams<Player, Session, Source, Provider>): GameHandle<ScreenAppOf<Plugins>, Source, Provider>;
+  screen<Source extends ClockSource = FakeClock, Provider extends PlayerStateProvider = MemoryProvider>(seams?: ScreenSeams<Player, Session, Source, Provider>): GameHandle<WithGameState<ScreenAppOf<Plugins>, Player, Session, Strings>, Source, Provider>;
 };
 /**
  * Any game, whatever its plugins and state: what the page takes.
@@ -471,9 +583,9 @@ type SystemShellFactory = (config: ResolvedGameConfig, report: (problem: string)
  * ```
  */
 type PageOptions = {
-  /** Prepared saves by name, for `?player=`. Dev only; the build passes none. */scenarios?: Readonly<Record<string, Scenario>>; /** The system shell factory, when `config.ts` names a system plugin or the store save. */
-  system?: SystemShellFactory; /** Agents started after the app. Dev only. */
-  agents?: readonly PageAgent[]; /** The game's `.dev` modules, handed to the agents. Dev only. */
+  /** Prepared saves by name, for `?player=`. Dev only; the builds pass none. */scenarios?: Readonly<Record<string, Scenario>>; /** The system shell factory, when `config.ts` names a system plugin or the store save. */
+  system?: SystemShellFactory; /** Agents started after the app: on the dev page and on a debug page. */
+  agents?: readonly PageAgent[]; /** The game's `.dev` modules, handed to the agents: dev and debug pages. */
   devModules?: readonly object[];
 };
 /**
@@ -593,4 +705,4 @@ type SystemShell = {
   stop(): Promise<void>;
 };
 //#endregion
-export { SystemShellFactory as _, GameHandle as a, MemoryProvider as c, SaveKind as d, Scenario as f, SystemName as g, SystemModules as h, GameDefinition as i, PageAgent as l, StartedPage as m, GameApp as n, GamePluginConfigs as o, ScreenSeams as p, GameConfig as r, HeadlessSeams as s, AnyGameApp as t, PageOptions as u };
+export { SystemShellFactory as _, GameHandle as a, saveOf as b, MemoryProvider as c, SaveKind as d, Scenario as f, SystemName as g, SystemModules as h, GameDefinition as i, PageAgent as l, StartedPage as m, GameApp as n, GamePluginConfigs as o, ScreenSeams as p, GameConfig as r, HeadlessSeams as s, AnyGameApp as t, PageOptions as u, WithGameState as v, memory as y };

package/dist/{types-CAPv9l29.d.mts → types-DngFQJro.d.mts}

@@ -1,5 +1,5 @@
-import { Zt as Json, on as Snapshot } from "./types-BjTtGSFb.mjs";
-import { t as HeadlessApp } from "./headless-CMHNsKjW.mjs";
+import { ur as Json, yr as Snapshot } from "./types-BGcda5Le.mjs";
+import { t as HeadlessApp } from "./headless-cFveciuY.mjs";
 import { Log } from "@moku-labs/common/browser";
 
 //#region src/plugins/flow/doors/types.d.ts
@@ -116,8 +116,46 @@ type Source<S extends InputSchema, O, App = HeadlessApp> = {
   readonly read: (app: App, input: InputOf<S>) => O;
 };
 /**
- * A dev-only action on a running game: an id, a title, the input it takes, its effect and how to
- * run it. The body starts with the inline dev guard, so a production build drops it.
+ * The input schema of an overlay toggle: the state the switch asks for, and nothing else.
+ *
+ * @example
+ * ```ts
+ * // The overlay runs a toggle with { on: !value(app) }.
+ * const input: ToggleInput = { on: "boolean" };
+ * ```
+ */
+type ToggleInput = {
+  readonly on: "boolean";
+};
+/** The schema a toggle accepts: exactly `{ on: "boolean" }`; any schema while `S` is the wide one. */
+type ToggleSchema<S extends InputSchema> = string extends keyof S ? S : [Exclude<keyof S, "on">] extends [never] ? S extends ToggleInput ? S : never : never;
+/** The schema a button accepts: no required field; any schema while `S` is the wide one. */
+type ButtonSchema<S extends InputSchema> = string extends keyof S ? S : [RequiredKeys<S>] extends [never] ? S : never;
+/**
+ * The overlay part of a command, one of three shapes told apart by `overlay`: none, a toggle
+ * with its input `{ on: "boolean" }` and its `value`, or a button with no required input and no
+ * `value`. Any other combination does not compile.
+ */
+type CommandOverlay<S extends InputSchema, App> = {
+  /** Not shown in the overlay. */readonly overlay?: never; /** Only a toggle has a value. */
+  readonly value?: never;
+} | {
+  /** A switch of the overlay, run with `{ on: !value(app) }`. */readonly overlay: "toggle";
+  readonly input: ToggleSchema<S>; /** The current value of the switch, read by the overlay to draw it. */
+  readonly value: (app: App) => boolean;
+} | {
+  /** A button of the overlay, run with `{}`. */readonly overlay: "button";
+  readonly input: ButtonSchema<S>; /** Only a toggle has a value. */
+  readonly value?: never;
+};
+/**
+ * An action on a running game, on the dev page and on a debug page: an id, a title, the input it
+ * takes, its effect and how to run it. Its body starts with the guard of its effect: the agent
+ * form for `read` and `cosmetic`, the control form for the others (see docs/doors.md), so a
+ * production build drops it. A game's `.dev` command with only the `__MOKU_GAME_DEV__` guard runs
+ * in dev and is refused on a debug page. With `overlay` the editor's overlay shows it: a toggle
+ * takes the input `{ on: "boolean" }` and a `value(app)`, a button no required input and no
+ * value; the types refuse every other shape.
  *
  * @example
  * ```ts
@@ -141,7 +179,7 @@ type Command<S extends InputSchema, O, App = HeadlessApp> = {
   readonly input: S;
   readonly effect: Effect;
   readonly run: (app: App, input: InputOf<S>) => O | Promise<O>;
-};
+} & CommandOverlay<S, App>;
 /**
  * Where the game stands after a command: the graph path, the frame and whether the session
  * was tainted by a cheat or a raw write.