@moku-labs/game 0.0.1 → 0.0.2

package/dist/define-sFoO3y6X.d.mts

@@ -0,0 +1,263 @@
+import { K as Snapshot, L as Json } from "./types-JNc_UQBo.mjs";
+import { t as HeadlessApp } from "./headless-KaSWcd0s.mjs";
+import { Log } from "@moku-labs/common/browser";
+
+//#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
+//#region src/plugins/flow/doors/define.d.ts
+/**
+ * Declares a source: a read-only view the editor lists, reads and watches. The types flow from
+ * the object: the input from `input`, the app from the `read` parameter, the output from its
+ * result.
+ *
+ * @param source - The descriptor.
+ * @returns The same descriptor, frozen.
+ * @throws {Error} When the id is not a dotted name such as `"game.position"`.
+ * @example
+ * ```ts
+ * // A game's .dev module: the orders on the board, re-read after every edge.
+ * export const orders = defineSource({
+ *   id: "timber.orders",
+ *   title: "Orders",
+ *   input: {},
+ *   changes: "edge",
+ *   read: app => app.flow.state().path
+ * });
+ * read(app, orders); // "board/awaitIntent"
+ * ```
+ */
+declare function defineSource<S extends InputSchema, O, App = HeadlessApp>(source: Source<S, O, App>): Source<S, O, App>;
+/**
+ * Declares a command: a dev-only action the editor lists and runs. Its body starts with the
+ * inline dev guard, so a production build drops it.
+ *
+ * @param command - The descriptor.
+ * @returns The same descriptor, frozen.
+ * @throws {Error} When the id is not a dotted name such as `"game.answer"`.
+ * @example
+ * ```ts
+ * // A game's .dev module: open the shop from anywhere, through the graph.
+ * export const openShop = defineCommand({
+ *   id: "timber.openShop",
+ *   title: "Open the shop",
+ *   input: {},
+ *   effect: "route",
+ *   run: app => {
+ *     if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+ *     return app.flow.walk([{ at: "home", intent: "shop" }]);
+ *   }
+ * });
+ * (await run(app, openShop)).state.path; // "shop"
+ * ```
+ */
+declare function defineCommand<S extends InputSchema, O, App = HeadlessApp>(command: Command<S, O, App>): Command<S, O, App>;
+//#endregion
+export { ControlApp as a, InputSchema as c, WatchApp as d, WatchInput as f, Command as i, Ran as l, defineSource as n, InputArguments as o, CheatEntry as r, InputOf as s, defineCommand as t, Source as u };

package/dist/headless-CvamCUcR.mjs

@@ -0,0 +1,186 @@
+import { a as graphHash } from "./registry-DlpRCibU.mjs";
+//#region src/plugins/flow/headless.ts
+const noPayload = null;
+/** Seed of a repro that pins no rng state, the seed `saveOf` writes. */
+const defaultSeed = 1;
+/**
+* Turns whatever `run()` rejected with into an error that can be thrown again.
+*
+* @param value - The rejection value.
+* @returns The value itself when it is an error, a wrapped one otherwise.
+* @example
+* ```ts
+* asError("offline").message; // "[game] The headless run failed.\n  offline."
+* ```
+*/
+function asError(value) {
+	if (value instanceof Error) return value;
+	return /* @__PURE__ */ new Error(`[game] The headless run failed.\n  ${String(value)}.`);
+}
+/**
+* Starts the one loop unless the app's own `onStart` already did, and keeps a fatal error until
+* someone asks for it. `run()` rejects only on a fatal error, and nobody awaits it here.
+*
+* @param app - The started app.
+* @returns The holder of the fatal error.
+*/
+function startLoop(app) {
+	const fatal = { error: void 0 };
+	if (app.flow.state().running) return fatal;
+	app.flow.run().catch((error) => {
+		fatal.error = error;
+	});
+	return fatal;
+}
+/**
+* Waits until the loop rests for the first time, or ends. An empty route walks nowhere: it only
+* waits for the gate the loop opens at the node it enters, so a start that is a chain of transit
+* nodes is played out before anything reads the game.
+*
+* @param app - The started app whose loop is running.
+* @param fatal - Holder of the fatal error of `run()`.
+* @returns Resolves once the loop rests at its first rest node.
+* @throws {Error} When the loop failed fatally instead of reaching a rest node.
+*/
+async function settleAtFirstRest(app, fatal) {
+	await app.flow.walk([]).catch((error) => {
+		throw asError(fatal.error ?? error);
+	});
+	if (fatal.error !== void 0) throw asError(fatal.error);
+}
+/**
+* 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();
+* ```
+*/
+async function createHeadless(app) {
+	app.flow.setMode("fast");
+	await app.start();
+	const fatal = startLoop(app);
+	await settleAtFirstRest(app, fatal);
+	return {
+		walk: async (route) => {
+			const state = await app.flow.walk(route).catch((error) => {
+				throw asError(fatal.error ?? error);
+			});
+			if (fatal.error !== void 0) throw asError(fatal.error);
+			return state;
+		},
+		answer: (answer) => app.flow.gate.answer(answer),
+		state: () => app.flow.state(),
+		history: () => app.flow.history(),
+		stop: async () => {
+			await app.stop();
+			if (fatal.error !== void 0) throw asError(fatal.error);
+		}
+	};
+}
+/**
+* Reads the rest node a repro starts at: its checkpoint, or the start of the main flow.
+*
+* @param app - The started app.
+* @param repro - Starting state, optional checkpoint and the route.
+* @returns The path of the node the repro enters.
+* @throws {Error} When the graph has no main flow to start from.
+*/
+function reproPath(app, repro) {
+	if (repro.checkpoint !== void 0) return repro.checkpoint;
+	const graph = app.flow.describe();
+	const start = graph.flows[graph.main]?.start;
+	if (start === void 0) throw new Error(`[game] runRepro() found no flow "${graph.main}" to start from.\n  Name the checkpoint the repro was taken at.`);
+	return start;
+}
+/**
+* Builds the bookmark a repro is entered with: its state, its checkpoint and the hash of the
+* graph that runs now, so a checkpoint is accepted and any other rest node is checked. The route
+* is not part of it: the caller walks it after the restore.
+*
+* @param app - The started app.
+* @param repro - Starting state, optional checkpoint and the route.
+* @returns The bookmark to restore.
+* @throws {Error} When the repro names no checkpoint and the graph has no main flow.
+* @example
+* ```ts
+* // The game.restore command loads a bug report taken at the "home" checkpoint.
+* const bookmark = reproBookmark(app, { player: { coins: 7 }, checkpoint: "home", route: [] });
+* bookmark.path; // "home"
+* bookmark.rng; // { seed: 1, streams: {} }: the repro pinned no rng
+* await app.flow.restore(bookmark);
+* ```
+*/
+function reproBookmark(app, repro) {
+	return {
+		path: reproPath(app, repro),
+		input: noPayload,
+		player: repro.player,
+		session: repro.session ?? {},
+		rng: repro.rng ?? {
+			seed: defaultSeed,
+			streams: {}
+		},
+		graph: graphHash(app.flow.describe())
+	};
+}
+/**
+* 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
+* ```
+*/
+async function runRepro(app, repro) {
+	const game = await createHeadless(app);
+	await app.flow.restore(reproBookmark(app, repro));
+	const state = await game.walk(repro.route);
+	const ended = app.flow.bookmark();
+	return {
+		path: state.stack.map((frame) => frame.node),
+		player: ended.player,
+		session: ended.session
+	};
+}
+/**
+* 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
+* ```
+*/
+function stepFrames(app, count, deltaMs) {
+	for (let frame = 0; frame < count; frame += 1) app.time.step(deltaMs);
+}
+//#endregion
+export { stepFrames as i, reproBookmark as n, runRepro as r, createHeadless as t };

package/dist/headless-KaSWcd0s.d.mts

@@ -0,0 +1,181 @@
+import { L as Json, O as Answer, S as RouteStep, Y as RngState, b as JournalEntry, k as Api, t as Api$1, y as FlowState } from "./types-JNc_UQBo.mjs";
+
+//#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
+export { createHeadless as a, ReproResult as i, HeadlessGame as n, runRepro as o, Repro as r, stepFrames as s, HeadlessApp as t };