@moku-labs/game 0.7.1 → 0.9.0

package/dist/{commands-mzE9PX0H.d.mts → commands-DuwCxK5t.d.mts}

@@ -1,7 +1,8 @@
-import { C as Captured, Et as Bookmark, T as DebugSwitches, Vt as Time, an as Api, k as Api$2, kt as FlowState, m as Api$1 } from "./types-BMEn0tSC.mjs";
-import { d as HeadlessApp, n as Command, r as ControlApp } from "./types-CYYKjvLn.mjs";
-import { H as InputApi } from "./types-BaUUcIaN.mjs";
-import { b as AnimApi, p as ScenesApi, t as AudioApi, v as UiApi } from "./types-CXyipKhE.mjs";
+import { At as FlowState, C as Captured, Dt as Bookmark, T as DebugSwitches, Ut as Time, k as Api$2, m as Api$1, sn as Api } from "./types-B0v5VVa3.mjs";
+import { t as HeadlessApp } from "./headless-SCQXJxQf.mjs";
+import { n as Command, r as ControlApp } from "./types-DUMoYPYe.mjs";
+import { H as InputApi } from "./types-xXfyk56Q.mjs";
+import { b as AnimApi, p as ScenesApi, t as AudioApi, v as UiApi } from "./types-VZVWwqCg.mjs";
 
 //#region src/plugins/flow/doors/commands.d.ts
 /**

package/dist/control.d.mts

@@ -1,6 +1,7 @@
-import { d as HeadlessApp, i as InputArguments, n as Command, o as InputSchema, s as Ran } from "./types-CYYKjvLn.mjs";
-import { t as commands } from "./commands-mzE9PX0H.mjs";
-import { t as defineCommand } from "./define-BbgXv4cy.mjs";
+import { t as HeadlessApp } from "./headless-SCQXJxQf.mjs";
+import { i as InputArguments, n as Command, o as InputSchema, s as Ran } from "./types-DUMoYPYe.mjs";
+import { t as commands } from "./commands-DuwCxK5t.mjs";
+import { t as defineCommand } from "./define-B6pHpdBi.mjs";
 
 //#region src/plugins/flow/doors/dev.d.ts
 /**

package/dist/control.mjs

@@ -1,4 +1,4 @@
 import { t as controlRefused } from "./dev-wKLgOw7c.mjs";
-import { n as commands, t as run } from "./run-Bcyg32M5.mjs";
-import { s as defineCommand } from "./input-CK4nxBO1.mjs";
+import { s as defineCommand } from "./input-z_35Jwfn.mjs";
+import { n as commands, t as run } from "./run-CofJEdYx.mjs";
 export { commands, controlRefused, defineCommand, run };

package/dist/{define-BbgXv4cy.d.mts → define-B6pHpdBi.d.mts}

@@ -1,4 +1,5 @@
-import { c as Source, d as HeadlessApp, n as Command, o as InputSchema } from "./types-CYYKjvLn.mjs";
+import { t as HeadlessApp } from "./headless-SCQXJxQf.mjs";
+import { c as Source, n as Command, o as InputSchema } from "./types-DUMoYPYe.mjs";
 
 //#region src/plugins/flow/doors/define.d.ts
 /**
@@ -13,7 +14,7 @@ import { c as Source, d as HeadlessApp, n as Command, o as InputSchema } from ".
  * ```ts
  * // A game's .dev module: the orders on the board, re-read after every edge.
  * export const orders = defineSource({
- *   id: "timber.orders",
+ *   id: "mini.orders",
  *   title: "Orders",
  *   input: {},
  *   changes: "edge",
@@ -34,7 +35,7 @@ declare function defineSource<S extends InputSchema, O, App = HeadlessApp>(sourc
  * ```ts
  * // A game's .dev module: open the shop from anywhere, through the graph.
  * export const openShop = defineCommand({
- *   id: "timber.openShop",
+ *   id: "mini.openShop",
  *   title: "Open the shop",
  *   input: {},
  *   effect: "route",

package/dist/headless-BsNdJs9W.mjs

@@ -0,0 +1,186 @@
+import { u as graphHash } from "./capture-fpd83Mi5.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-SCQXJxQf.d.mts

@@ -0,0 +1,181 @@
+import { At as FlowState, Bt as Api, Jt as Json, Nt as RouteStep, jt as JournalEntry, on as RngState, ut as Api$1, zt as Answer } from "./types-B0v5VVa3.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 };

package/dist/hot.d.mts

@@ -14,8 +14,10 @@
 type HotOptions = {
   /**
    * The files that get the footer. Default: `.tsx` files, `styles.ts`, `view.ts`,
-   * `animations.ts`, `effects.ts` and `generated/strings.<locale>.ts`. Bun runs it as the load
-   * filter on the absolute path, so it should not anchor at the start.
+   * `animations.ts`, `effects.ts`, any `.ts` directly in a `styles/`, `motion/`, `effects/` or
+   * `views/` folder, and in `world/projections/` or `world/layout/`, and
+   * `generated/strings.<locale>.ts`. Bun runs it as the load filter on the absolute path, so it
+   * should not anchor at the start.
    */
   include?: RegExp;
   /**

package/dist/hot.mjs

@@ -7,16 +7,18 @@ import path from "node:path";
 * update and hands the new exports to the running game through `globalThis.__moku_hot`. The `ui`
 * plugin installs that handler in dev builds only. What swaps: styles, components, projections,
 * animations, text styles, emitters and generated strings. A view module is a `.tsx` file, a
-* `styles.ts`, a `view.ts`, an `animations.ts`, an `effects.ts` or a generated
-* `generated/strings.<locale>.ts`; a logic module never gets the footer, so its save reaches the
-* root and the page reloads and restores its state. The plugin lives in `[serve.static]` of
+* `styles.ts`, a `view.ts`, an `animations.ts`, an `effects.ts`, any `.ts` directly in a
+* `styles/`, `motion/`, `effects/` or `views/` folder, any `.ts` directly in `world/projections/`
+* or `world/layout/`, or a generated `generated/strings.<locale>.ts`; a logic module never gets
+* the footer (`world/components/` and `world/systems/` included: they are registered at start), so
+* its save reaches the root and the page reloads and restores its state. The plugin lives in `[serve.static]` of
 * `bunfig.toml`, the dev server only: `Bun.build` of a production build never loads it.
 */
 /**
-* The default view modules: `.tsx` files, `styles.ts`, `view.ts`, `animations.ts`, `effects.ts`
-* and the generated strings of a locale.
+* The default view modules: the view files by name or by kind folder. Two literals joined, so
+* each stays readable.
 */
-const DEFAULT_INCLUDE = /(\.tsx|\/styles\.ts|\/view\.ts|\/animations\.ts|\/effects\.ts|\/generated\/strings\.[\w-]+\.ts)$/;
+const DEFAULT_INCLUDE = new RegExp(`(${/\.tsx|\/styles\.ts|\/view\.ts|\/animations\.ts|\/effects\.ts|\/generated\/strings\.[\w-]+\.ts/.source}|${/\/(?:styles|motion|effects|views)\/[^/]+\.ts|\/world\/(?:projections|layout)\/[^/]+\.ts/.source})$`);
 /** The generated strings of one locale, the one file under `generated/` that swaps. */
 const STRINGS = /\/generated\/strings\.[\w-]+\.ts$/;
 /** The default folders and test files that never hot swap. The outer group only scopes the `$`. */