@moku-labs/game 0.0.1 → 0.0.3

package/dist/types-D0uYTTC3.d.mts

@@ -0,0 +1,392 @@
+import { At as Json, Ht as RngState, St as Api, ft as FlowState, ht as RouteStep, pt as JournalEntry, q as Api$1, xt as Answer, zt as Snapshot } from "./types-Cjf3ywai.mjs";
+import { Log } from "@moku-labs/common/browser";
+
+//#region src/plugins/flow/headless.d.ts
+/**
+ * The part of an app the headless helpers use. Structural on purpose: any app created with the
+ * default plugins fits.
+ *
+ * @example
+ * ```ts
+ * const app: HeadlessApp = createApp({ pluginConfigs: { flow: { mainFlow } } });
+ * ```
+ */
+type HeadlessApp = {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  time: Api;
+  flow: Api$1;
+};
+/**
+ * A game played without a screen: answers go through the gate, effects resolve instantly.
+ *
+ * @example
+ * ```ts
+ * // A test of the dice game: two rolls, no screen, no waiting.
+ * const game = await createHeadless(app);
+ * const state = await game.walk([{ at: "home", intent: "roll" }, { at: "home", intent: "roll" }]);
+ *
+ * state.path; // "home"
+ * await game.stop();
+ * ```
+ */
+type HeadlessGame = {
+  /**
+   * Walks a route through the running loop.
+   *
+   * @param route - The player's answers and substituted sub-flow results, in order.
+   * @returns The state the walk ended in.
+   * @throws {Error} When a step is never reached, or the loop failed fatally.
+   * @example
+   * ```ts
+   * // Open the board and tap the generator twice. Every node's logic runs for real.
+   * const tap = { at: "board/awaitIntent", intent: "tap", payload: { generatorId: "sawmill" } };
+   * const state = await game.walk([{ at: "home", intent: "play" }, tap, tap]);
+   *
+   * state.path; // "board/awaitIntent"
+   * ```
+   */
+  walk(route: readonly RouteStep[]): Promise<FlowState>;
+  /**
+   * Gives one answer to the gate, the way a tap does.
+   *
+   * @param answer - Intent and optional payload.
+   * @returns Whether the gate took it.
+   * @example
+   * ```ts
+   * // One tap without a route. The test then waits for the loop by itself.
+   * game.answer({ intent: "play" }); // true: "home" rests and lists "play"
+   * ```
+   */
+  answer(answer: Answer): boolean;
+  /**
+   * Reads where the graph stands.
+   *
+   * @returns Whether it runs, the path, the stack, what it waits for and the mode.
+   * @example
+   * ```ts
+   * // Right after createHeadless: the graph rests at its first rest node.
+   * game.state().path; // "home"
+   * game.state().pending; // { gate: ["play"] }
+   * ```
+   */
+  state(): FlowState;
+  /**
+   * Reads the edges taken since the last checkpoint.
+   *
+   * @returns A copy of the journal.
+   * @example
+   * ```ts
+   * // After a merge onto an empty cell: the last edge says why the move was refused.
+   * const last = game.history().at(-1);
+   * // last?.path: "board/merge", last?.outcome: "rejected", last?.payload: { reason: "empty" }
+   * ```
+   */
+  history(): readonly JournalEntry[];
+  /**
+   * Stops the app, then re-throws a fatal error of the loop.
+   *
+   * @throws {Error} When the loop failed fatally.
+   * @example
+   * ```ts
+   * // The last line of a headless test. A fatal error of the loop fails the test here.
+   * await game.stop();
+   * ```
+   */
+  stop(): Promise<void>;
+};
+/**
+ * A reproducible run: a starting state, an optional checkpoint and the route played from it.
+ *
+ * @example
+ * ```ts
+ * const repro: Repro = { player: { coins: 0 }, checkpoint: "home", route: [{ at: "home", intent: "play" }] };
+ * ```
+ */
+type Repro = {
+  player: Json;
+  session?: Json;
+  rng?: RngState;
+  checkpoint?: string;
+  route: RouteStep[];
+};
+/**
+ * What a repro run ends with: the path where the loop rests and the committed state.
+ *
+ * @example
+ * ```ts
+ * const result: ReproResult = { path: ["home"], player: { coins: 3 }, session: { visits: 1 } };
+ * ```
+ */
+type ReproResult = {
+  path: string[];
+  player: Json;
+  session: Json;
+};
+/**
+ * Starts an app headless: sets flow mode `"fast"`, awaits `app.start()`, starts `flow.run()`
+ * unless the app's own `onStart` already did, and waits until the loop rests for the first time.
+ * `game.state().path` therefore names the first rest node of the graph as soon as the call
+ * resolves. A fatal error of the loop rejects this call, and a later one is re-thrown by `walk`
+ * and by `stop`, so a headless test never loses it.
+ *
+ * @param app - An app that is not started yet.
+ * @returns The game: walk it, answer it, read it, stop it.
+ * @throws {Error} When the loop failed fatally before it reached its first rest node.
+ * @example
+ * ```ts
+ * // A test starts the merge game without a screen. The call resolves at the first rest node.
+ * const game = await createHeadless(app);
+ *
+ * game.state().path; // "home": the transit node "boot" was played out
+ * game.state().mode; // "fast"
+ * await game.stop();
+ * ```
+ */
+declare function createHeadless(app: HeadlessApp): Promise<HeadlessGame>;
+/**
+ * Plays a repro: starts the app headless, restores the bookmark built from its state and
+ * checkpoint, then walks its route. The app keeps running, so the caller can read more than the
+ * result and stops it itself.
+ *
+ * @param app - An app that is not started yet.
+ * @param repro - Starting state, optional checkpoint and the route.
+ * @returns The path the run ended at, and the committed state.
+ * @example
+ * ```ts
+ * // A bug report on the dice game: "reset keeps my coins". Replay it from the "home" checkpoint.
+ * const reset = { at: "home", intent: "reset" };
+ * const result = await runRepro(app, { player: { coins: 7 }, checkpoint: "home", route: [reset] });
+ *
+ * result.player; // { coins: 0 }; result.path is ["home"]
+ * await app.stop(); // the app keeps running after the run
+ * ```
+ */
+declare function runRepro(app: HeadlessApp, repro: Repro): Promise<ReproResult>;
+/**
+ * Steps the frame loop by hand: `count` calls of `app.time.step(deltaMs)`. A headless game has no
+ * frame source, so this is the only thing that moves the frame phases.
+ *
+ * @param app - A started app.
+ * @param count - Number of frames.
+ * @param deltaMs - Milliseconds per frame.
+ * @example
+ * ```ts
+ * // A headless game has no frame source: the test moves the six frame phases by hand.
+ * stepFrames(app, 2, 16);
+ * app.time.snapshot(); // frame: 2, delta: 16, elapsed: 32
+ * ```
+ */
+declare function stepFrames(app: HeadlessApp, count: number, deltaMs: number): void;
+//#endregion
+//#region src/plugins/flow/doors/types.d.ts
+/**
+ * The kinds an input field can take. `json` is any JSON value the command checks itself.
+ *
+ * @example
+ * ```ts
+ * // The schema of game.step: the frame count, and the frame length in milliseconds.
+ * const kinds: InputKind[] = ["number", "number"];
+ * ```
+ */
+type InputKind = "string" | "number" | "boolean" | "json";
+/**
+ * The input of a source or a command: field name to kind. A kind ending in `?` is optional, so
+ * "key or target" is two optional fields and the command checks that one is given.
+ *
+ * @example
+ * ```ts
+ * // game.restore takes exactly one of the two.
+ * const input: InputSchema = { bookmark: "json?", repro: "json?" };
+ * ```
+ */
+type InputSchema = Readonly<Record<string, InputKind | `${InputKind}?`>>;
+/** The TypeScript type of each input kind. */
+type KindTypes = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  json: Json;
+};
+/** The value type of one field kind, optional or not. */
+type ValueOf<Kind> = Kind extends `${infer Base extends InputKind}?` ? KindTypes[Base] : Kind extends InputKind ? KindTypes[Kind] : never;
+/** The fields of a schema whose kind has no `?`. */
+type RequiredKeys<S extends InputSchema> = { [K in keyof S]: S[K] extends InputKind ? K : never }[keyof S];
+/** Shows an intersection as one object type. */
+type Flat<T> = { [K in keyof T]: T[K] };
+/**
+ * The input value a schema describes. A `?` field may be left out or be `undefined`.
+ *
+ * @example
+ * ```ts
+ * type Step = InputOf<{ frames: "number"; deltaMs: "number?" }>; // { frames: number; deltaMs?: number | undefined }
+ * const step: Step = { frames: 3 };
+ * ```
+ */
+type InputOf<S extends InputSchema> = Flat<{ -readonly [K in RequiredKeys<S>]: ValueOf<S[K]> } & { -readonly [K in Exclude<keyof S, RequiredKeys<S>>]?: ValueOf<S[K]> | undefined }>;
+/**
+ * The input argument of `read` and `run`: optional when every field of the schema is optional,
+ * required otherwise.
+ *
+ * @example
+ * ```ts
+ * type History = InputArguments<{ last: "number?" }>; // [input?: { last?: number | undefined }]
+ * type Rect = InputArguments<{ key: "string" }>; // [input: { key: string }]
+ * ```
+ */
+type InputArguments<S extends InputSchema> = Partial<InputOf<S>> extends InputOf<S> ? [input?: InputOf<S>] : [input: InputOf<S>];
+/**
+ * The input argument of `watch`: `undefined` is allowed when every field is optional.
+ *
+ * @example
+ * ```ts
+ * type Position = WatchInput<{}>; // {} | undefined
+ * type Rect = WatchInput<{ key: "string" }>; // { key: string }
+ * ```
+ */
+type WatchInput<S extends InputSchema> = Partial<InputOf<S>> extends InputOf<S> ? InputOf<S> | undefined : InputOf<S>;
+/**
+ * When `watch` reads a source again: every frame, when the committed model changed, or when
+ * the graph moved (an edge, a gate, a mode).
+ *
+ * @example
+ * ```ts
+ * // game.position moves only with the graph; game.render changes every frame.
+ * const changes: Changes = "edge";
+ * ```
+ */
+type Changes = "frame" | "commit" | "edge";
+/**
+ * What a command does to the game. `route` goes through the graph and keeps the session clean;
+ * `cheat` and `raw` taint it and are journaled.
+ *
+ * @example
+ * ```ts
+ * // game.restore replaces the whole state: the session is not a played one any more.
+ * const effect: Effect = "raw";
+ * ```
+ */
+type Effect = "read" | "route" | "cosmetic" | "cheat" | "raw";
+/**
+ * A read-only view on a running game: an id, a title, the input it takes, when it changes and
+ * how to read it. `App` is what the reader needs: the headless app by default, a screen source
+ * asks for the screen plugins.
+ *
+ * @example
+ * ```ts
+ * // A game's .dev module: the coins a panel shows, re-read on every commit.
+ * const coins = defineSource({
+ *   id: "timber.coins",
+ *   title: "Coins",
+ *   input: {},
+ *   changes: "commit",
+ *   read: (app: HeadlessApp & { model: ModelApi }) => app.model.store.snapshot().player
+ * });
+ * read(app, coins); // { coins: 120, ... }
+ * ```
+ */
+type Source<S extends InputSchema, O, App = HeadlessApp> = {
+  readonly id: string;
+  readonly title: string;
+  readonly input: S;
+  readonly changes: Changes;
+  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.
+ *
+ * @example
+ * ```ts
+ * // A game's .dev module: jump to a level through the graph, the session stays clean.
+ * const jumpToLevel = defineCommand({
+ *   id: "timber.jumpToLevel",
+ *   title: "Go to level",
+ *   input: { level: "number" },
+ *   effect: "route",
+ *   run: (app, { level }) => {
+ *     if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+ *     return app.flow.walk([{ at: "home", intent: "play", payload: { level } }]);
+ *   }
+ * });
+ * (await run(app, jumpToLevel, { level: 3 })).state.path; // "board/awaitIntent"
+ * ```
+ */
+type Command<S extends InputSchema, O, App = HeadlessApp> = {
+  readonly id: string;
+  readonly title: string;
+  readonly input: S;
+  readonly effect: Effect;
+  readonly run: (app: App, input: InputOf<S>) => O | Promise<O>;
+};
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const envelope: Envelope = { path: "board/awaitIntent", frame: 1840, tainted: false };
+ * ```
+ */
+type Envelope = {
+  readonly path: string;
+  readonly frame: number;
+  readonly tainted: boolean;
+};
+/**
+ * What `run` resolves with: the command's value and the envelope read after it.
+ *
+ * @example
+ * ```ts
+ * // A tap on Play while the home screen rests.
+ * const ran: Ran<boolean> = { value: true, state: { path: "board/awaitIntent", frame: 312, tainted: false } };
+ * ```
+ */
+type Ran<O> = {
+  readonly value: O;
+  readonly state: Envelope;
+};
+/**
+ * One journaled cheat or raw command: its id, the input it got and the frame it ran on.
+ *
+ * @example
+ * ```ts
+ * const entry: CheatEntry = { id: "game.restore", input: { bookmark: { path: "home" } }, frame: 96 };
+ * ```
+ */
+type CheatEntry = {
+  readonly id: string;
+  readonly input: Readonly<Record<string, Json | undefined>>;
+  readonly frame: number;
+};
+/**
+ * What `watch` needs of an app: the frame loop, the graph and the committed model it compares.
+ * Every app with the default plugins fits.
+ *
+ * @example
+ * ```ts
+ * const app: WatchApp = createApp({ pluginConfigs: { flow: { mainFlow } } });
+ * ```
+ */
+type WatchApp = HeadlessApp & {
+  readonly model: {
+    readonly store: {
+      snapshot(): Snapshot;
+    };
+  };
+};
+/**
+ * What the base commands need of an app: the headless app plus the log, where every command
+ * leaves a `moku:dev` entry. Every app with the default plugins fits.
+ *
+ * @example
+ * ```ts
+ * const app: ControlApp = createApp({ pluginConfigs: { flow: { mainFlow } } });
+ * app.log.trace().at(-1)?.event; // "moku:dev" after a command ran
+ * ```
+ */
+type ControlApp = HeadlessApp & {
+  readonly log: Log.LogApi;
+};
+//#endregion
+export { stepFrames as _, InputOf as a, Source as c, HeadlessApp as d, HeadlessGame as f, runRepro as g, createHeadless as h, InputArguments as i, WatchApp as l, ReproResult as m, Command as n, InputSchema as o, Repro as p, ControlApp as r, Ran as s, CheatEntry as t, WatchInput as u };