@moku-labs/game 0.7.1 → 0.8.0

package/README.md

@@ -115,7 +115,7 @@ await game.walk([{ at: "home", intent: "roll" }, { at: "home", intent: "roll" }]
 app.model.store.snapshot().session; // { rolls: 2 }
 ```
 
-The full version, with a reset node and a vitest file, is in [docs/quick-start.md](./docs/quick-start.md). A bigger game lives in [`tests/integration/merge-game/`](./tests/integration/merge-game). It is a test fixture and is not published.
+The full version, with a reset node and a vitest file, is in [docs/quick-start.md](./docs/quick-start.md). A bigger game, the merge game, lives in [moku-labs/demos](https://github.com/moku-labs/demos) with its tests.
 
 A game with a screen gets two more things from the package. The body font `fonts/font-body.*` (Pangolin, SIL OFL 1.1) is the default of the built-in text style `body` once copied into `src/features/ui/assets/`. The bin `moku-game-assets` writes the typed asset keys, the manifest and the strings. It runs under bun; with node only, run `bun node_modules/@moku-labs/game/dist/assets.mjs`. Both are in [docs/quick-start.md](./docs/quick-start.md#a-screen-the-body-font-and-the-asset-keys).
 
@@ -188,7 +188,8 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 | Import | Runs in | For |
 |---|---|---|
 | `@moku-labs/game` | anywhere | The engine: plugins, helpers, components |
-| `@moku-labs/game/testing` | Node and Bun | Headless games and visual tests |
+| `@moku-labs/game/testing` | anywhere | Headless games, the fake clock, the in-memory save |
+| `@moku-labs/game/visual` | Node and Bun | Visual tests: baselines of state, describe and pixels |
 | `@moku-labs/game/assets` | Node and Bun | Asset keys, the manifest, strings, the pack |
 | `@moku-labs/game/inspect` | anywhere | Read a running game |
 | `@moku-labs/game/control` | dev builds | Drive a running game |
@@ -246,8 +247,8 @@ bun run lint             # biome check . && eslint .
 bun run test             # vitest, unit and integration
 bun run test:coverage    # with the 90% threshold
 bun run validate         # publint and attw
-bun run fixture:visual   # visual tests of the fixture game
-bun run fixture:native   # the fixture as a native app
+bun run mini:pack        # pack the mini game of tests/fixtures
+bun run mini:visual      # visual tests of the mini game
 bun run release          # moku-release
 ```
 

package/dist/assets.d.mts

@@ -1,4 +1,4 @@
-import { l as Manifest } from "./types-BMEn0tSC.mjs";
+import { l as Manifest } from "./types-BWzCSRM2.mjs";
 
 //#region src/plugins/assets/scan/cli.d.ts
 /**

package/dist/{capture-fpd83Mi5.mjs → capture-BX5Gfoty.mjs}

@@ -1,386 +1,3 @@
-//#region src/plugins/flow/runner/journal.ts
-/** FNV-1a 32-bit offset basis. */
-const OFFSET_BASIS = 2166136261;
-/** FNV-1a 32-bit prime. */
-const PRIME = 16777619;
-/** Separates the parts of a hashed edge, so "a|b" and "a" + "b" never collide. */
-const SEPARATOR = "\0";
-/**
-* Hashes text with FNV-1a, 32 bit. Pure and deterministic: the same text always gives the same
-* eight hexadecimal characters, in every runtime.
-*
-* @param text - The text to hash.
-* @returns Eight lowercase hexadecimal characters.
-* @example
-* ```ts
-* hashText("board/merge"); // "53ceca70"
-* ```
-*/
-function hashText(text) {
-	let hash = OFFSET_BASIS;
-	for (const character of text) hash = Math.imul(hash ^ (character.codePointAt(0) ?? 0), PRIME);
-	return (hash >>> 0).toString(16).padStart(8, "0");
-}
-/**
-* Hashes one edge, so a replay against edited code fails loudly in dev.
-*
-* @param path - Path of the node that produced the outcome.
-* @param outcome - Outcome name.
-* @param next - Rendered edge target.
-* @returns The digest of the three parts together.
-* @example
-* ```ts
-* entryHash("board/merge", "done", "board/awaitIntent"); // "e881176b"
-* ```
-*/
-function entryHash(path, outcome, next) {
-	return hashText([
-		path,
-		outcome,
-		next
-	].join(SEPARATOR));
-}
-/**
-* Appends an entry with the next index and its hash, and drops the oldest entries above the limit.
-* The index keeps counting while entries are dropped, so two entries never share a number.
-*
-* @param state - Runner state that holds the journal.
-* @param entry - The taken edge without `index` and `hash`.
-* @param limit - Journal entries kept between checkpoints.
-* @returns The stored entry.
-*/
-function pushEntry(state, entry, limit) {
-	const stored = {
-		...entry,
-		index: state.journalIndex,
-		hash: entryHash(entry.path, entry.outcome, entry.next)
-	};
-	state.journalIndex += 1;
-	state.journal.push(stored);
-	if (state.journal.length > limit) state.journal.splice(0, state.journal.length - limit);
-	return stored;
-}
-/**
-* Clears the journal at a checkpoint. The running index is kept, and so is the array itself: a
-* reader that holds `history()` sees the compaction.
-*
-* @param state - Runner state that holds the journal.
-*/
-function compact(state) {
-	state.journal.length = 0;
-}
-//#endregion
-//#region src/plugins/flow/runner/registry.ts
-/**
-* Creates the empty flow map. It lives in its own function because the plugin's lint rule L5
-* refuses a collection built inside an exported declaration.
-*
-* @returns An empty map of flow id to flow.
-* @example
-* ```ts
-* emptyFlows().size; // 0
-* ```
-*/
-function emptyFlows() {
-	return /* @__PURE__ */ new Map();
-}
-/**
-* Adds a flow and every flow it reaches by reference to the map. The first flow under an id wins,
-* so a collision is visible to `validateGraph` instead of silently replacing a flow.
-*
-* @param flow - The flow to add.
-* @param flows - The map being filled.
-*/
-function addFlow(flow, flows) {
-	if (flows.has(flow.id)) return;
-	flows.set(flow.id, flow);
-	for (const entry of Object.values(flow.nodes)) if (entry.kind === "flow") addFlow(entry, flows);
-}
-/**
-* Collects every flow reachable from the main flow by reference, plus the registered extras.
-* The main flow is the first entry: `describeGraph` reads it as the entry point of the graph.
-*
-* @param main - The top-level flow.
-* @param extra - Flows added with `register`, not reachable by reference.
-* @returns Flow id to flow, main first.
-* @example
-* ```ts
-* [...collectFlows(mainFlow, []).keys()]; // ["main", "board"]: the main flow first
-* ```
-*/
-function collectFlows(main, extra) {
-	const flows = emptyFlows();
-	addFlow(main, flows);
-	for (const flow of extra) addFlow(flow, flows);
-	return flows;
-}
-/**
-* Renders a position as a path: the node of every frame, outermost first.
-*
-* @param stack - One frame per nesting level.
-* @returns The path, for example `"board/awaitIntent"`; empty without a position.
-* @example
-* ```ts
-* const board = { flow: "main", node: "board", input: null };
-* framePath([board, { flow: "board", node: "merge", input: null }]); // "board/merge"
-* ```
-*/
-function framePath(stack) {
-	return stack.map((frame) => frame.node).join("/");
-}
-/**
-* Picks the flow a path continues in after one entry: the sub-flow itself, or, behind a slot, the
-* first contribution in order that has the next segment as a node. A path keeps node names only,
-* so two contributions of one slot with the same node name cannot be told apart; `validateGraph`
-* warns about that.
-*
-* @param entry - The entry the path just passed.
-* @param next - The next segment of the path.
-* @param contributionsOf - Reads the contributions of a slot, in order.
-* @returns The flow to go on in, or `undefined` when the path ends here.
-*/
-function flowBehind(entry, next, contributionsOf) {
-	if (entry.kind === "flow") return entry;
-	if (entry.kind !== "slot") return void 0;
-	return contributionsOf(entry.name).find((item) => Object.hasOwn(item.flow.nodes, next))?.flow;
-}
-/**
-* Reads no contributions: the default of `findNode` for a caller that has no features API.
-*
-* @returns An empty list.
-* @example
-* ```ts
-* noContributions(); // []
-* ```
-*/
-function noContributions() {
-	return [];
-}
-/**
-* Finds the node, sub-flow or slot a path names, starting at the main flow. A path descends one
-* sub-flow per segment, and through a slot into the contribution that has the next segment; a
-* segment after a plain node finds nothing.
-*
-* @param main - The top-level flow.
-* @param path - A path as `framePath` renders it.
-* @param contributionsOf - Reads the contributions of a slot, in order. Without it a path ends at
-*   a slot.
-* @returns Where the path leads, or `undefined` when no such node exists.
-* @example
-* ```ts
-* findNode(mainFlow, "board/awaitIntent")?.trail;
-* // [{ flow: "main", node: "board" }, { flow: "board", node: "awaitIntent" }]
-* findNode(mainFlow, "afterOrder/show", () => [{ flow: rewardFlow }])?.trail;
-* // [{ flow: "main", node: "afterOrder" }, { flow: "rewardPopup", node: "show" }]
-* ```
-*/
-function findNode(main, path, contributionsOf = noContributions) {
-	const names = path.split("/").filter(Boolean);
-	const trail = [];
-	let flow = main;
-	for (const [step, name] of names.entries()) {
-		const entry = flow.nodes[name];
-		if (!entry) return void 0;
-		trail.push({
-			flow: flow.id,
-			node: name
-		});
-		if (step === names.length - 1) return {
-			flow,
-			name,
-			entry,
-			trail
-		};
-		const behind = flowBehind(entry, names[step + 1] ?? "", contributionsOf);
-		if (behind === void 0) return void 0;
-		flow = behind;
-	}
-}
-/**
-* Renders an edge target as a string: a node name, `"exit:win"` or `"map:node"`.
-*
-* @param target - The target as the edge table holds it.
-* @returns The rendered target.
-* @example
-* ```ts
-* renderTarget("home"); // "home"
-* renderTarget({ kind: "exit", outcome: "win" }); // "exit:win"
-* ```
-*/
-function renderTarget(target) {
-	if (typeof target === "string") return target;
-	return target.kind === "exit" ? `exit:${target.outcome}` : `map:${target.target}`;
-}
-/**
-* Renders the edge table of one flow.
-*
-* @param flow - The flow to render.
-* @returns Node name to outcome name to rendered target.
-* @example
-* ```ts
-* renderEdges(boardFlow).awaitIntent?.leave; // "exit:left"
-* ```
-*/
-function renderEdges(flow) {
-	const edges = {};
-	for (const [name, row] of Object.entries(flow.edges)) {
-		const rendered = {};
-		for (const [outcome, target] of Object.entries(row)) rendered[outcome] = renderTarget(target);
-		edges[name] = rendered;
-	}
-	return edges;
-}
-/**
-* Maps every node and flow a feature brought to the name of that feature.
-*
-* @param features - Features API.
-* @returns Node or flow object to feature name.
-*/
-function collectOwners(features) {
-	const owners = /* @__PURE__ */ new Map();
-	for (const { name, description } of features.all()) {
-		for (const node of description.nodes ?? []) owners.set(node, name);
-		for (const flow of description.flows ?? []) owners.set(flow, name);
-	}
-	return owners;
-}
-/**
-* Describes one entry of a flow: its flags, its scene, its outcome names, and the slot, sub-flow
-* or owning feature when it has one.
-*
-* @param flow - The flow that holds the entry.
-* @param name - Name of the entry inside that flow.
-* @param entry - The node, sub-flow or slot.
-* @param owner - Name of the feature that brought it, when a feature did.
-* @returns The entry as JSON.
-* @example
-* ```ts
-* describeNode(mainFlow, "home", home, undefined).rest; // true
-* describeNode(mainFlow, "board", boardFlow, "board").subFlow; // "board"
-* ```
-*/
-function describeNode(flow, name, entry, owner) {
-	const node = entry.kind === "node" ? entry : void 0;
-	return {
-		flow: flow.id,
-		node: name,
-		rest: node?.rest ?? false,
-		over: node?.over ?? false,
-		checkpoint: node?.checkpoint ?? false,
-		barrier: node?.barrier ?? false,
-		outcomes: Object.keys(entry.outcomes),
-		...node?.scene === void 0 ? {} : { scene: node.scene },
-		...entry.kind === "slot" ? { slot: entry.name } : {},
-		...entry.kind === "flow" ? { subFlow: entry.id } : {},
-		...owner === void 0 ? {} : { owner }
-	};
-}
-/**
-* Describes every entry of one flow.
-*
-* @param flow - The flow to describe.
-* @param owners - Node or flow object to feature name.
-* @returns Node name to description.
-* @example
-* ```ts
-* describeNodes(boardFlow, new Map()).merge?.outcomes; // ["done", "rejected"]
-* ```
-*/
-function describeNodes(flow, owners) {
-	const nodes = {};
-	for (const [name, entry] of Object.entries(flow.nodes)) nodes[name] = describeNode(flow, name, entry, owners.get(entry) ?? owners.get(flow));
-	return nodes;
-}
-/**
-* Collects the slot names of every flow of the graph. `describe()` and `validate` both read the
-* contributions of exactly these slots.
-*
-* @param flows - Every collected flow by id.
-* @returns The slot names, in the order the graph declares them, each once.
-* @example
-* ```ts
-* slotNames(collectFlows(mainFlow, [])); // ["afterOrder"]
-* ```
-*/
-function slotNames(flows) {
-	const names = [];
-	for (const flow of flows.values()) for (const entry of Object.values(flow.nodes)) if (entry.kind === "slot" && !names.includes(entry.name)) names.push(entry.name);
-	return names;
-}
-/**
-* Renders the whole graph as JSON without running the game: nodes, flags, outcomes, edges,
-* slots and who contributed. Edge targets become `"node"`, `"exit:win"`, `"map:node"`.
-*
-* @param flows - Every collected flow by id, the main flow first, as `collectFlows` returns them.
-* @param features - Features API: owners and slot contributions.
-* @returns The graph as plain JSON.
-*/
-function describeGraph(flows, features) {
-	const owners = collectOwners(features);
-	const described = {};
-	const slots = {};
-	for (const flow of flows.values()) described[flow.id] = {
-		nodes: describeNodes(flow, owners),
-		start: flow.start,
-		edges: renderEdges(flow)
-	};
-	for (const name of slotNames(flows)) slots[name] = features.contributions(name).map(({ feature, flow, order }) => ({
-		feature,
-		flow: flow.id,
-		order
-	}));
-	return {
-		main: [...flows.keys()][0] ?? "",
-		flows: described,
-		slots
-	};
-}
-/**
-* Compares two object keys without a locale, so the rendering is the same everywhere.
-*
-* @param first - First key.
-* @param second - Second key.
-* @returns A negative number, zero or a positive number.
-* @example
-* ```ts
-* compareKeys("edges", "nodes"); // -1
-* ```
-*/
-function compareKeys(first, second) {
-	if (first === second) return 0;
-	return first < second ? -1 : 1;
-}
-/**
-* Renders a JSON value with its object keys sorted, so two equal graphs written in a different
-* order hash the same.
-*
-* @param value - Any JSON value.
-* @returns The value as text.
-* @example
-* ```ts
-* stableJson({ b: 1, a: 2 }); // '{"a":2,"b":1}'
-* ```
-*/
-function stableJson(value) {
-	if (Array.isArray(value)) return `[${value.map((item) => stableJson(item)).join(",")}]`;
-	if (typeof value !== "object" || !value) return JSON.stringify(value) ?? "";
-	return `{${Object.entries(value).filter(([, item]) => item !== void 0).toSorted(([first], [second]) => compareKeys(first, second)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
-}
-/**
-* Hashes a graph description. A bookmark of a plain rest node is accepted only while this hash
-* is unchanged.
-*
-* @param graph - Result of `describeGraph`.
-* @returns Eight lowercase hexadecimal characters.
-* @example
-* ```ts
-* graphHash({ main: "main", flows: {}, slots: {} }); // "cfb16c03"
-* ```
-*/
-function graphHash(graph) {
-	return hashText(stableJson(graph));
-}
-//#endregion
 //#region src/plugins/renderer/monitor/picture.ts
 /** Size of the badge number in CSS pixels; the picture draws it times the resolution. */
 const BADGE_FONT_PX = 12;
@@ -1151,4 +768,4 @@ async function captureFrame(mctx, options) {
 	return shot === void 0 ? void 0 : answerOf(mctx, shot, options.against);
 }
 //#endregion
-export { sheetAlone as a, findNode as c, slotNames as d, compact as f, servePaused as i, framePath as l, captureFrame as n, collectFlows as o, pushEntry as p, serveCaptures as r, describeGraph as s, cancelCaptures as t, graphHash as u };
+export { sheetAlone as a, servePaused as i, captureFrame as n, serveCaptures as r, cancelCaptures as t };

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

@@ -1,7 +1,9 @@
-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 { N as Time, Z as Api, _ as Bookmark, b as FlowState } from "./types-ERb2Y9U5.mjs";
+import { C as Captured, T as DebugSwitches, k as Api$2, m as Api$1 } from "./types-BWzCSRM2.mjs";
+import { t as HeadlessApp } from "./headless-q98SwADR.mjs";
+import { n as Command, r as ControlApp } from "./types-CDSKa0vl.mjs";
+import { H as InputApi } from "./types-DgdMLZnV.mjs";
+import { b as AnimApi, p as ScenesApi, t as AudioApi, v as UiApi } from "./types-DlgsfOmW.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-q98SwADR.mjs";
+import { i as InputArguments, n as Command, o as InputSchema, s as Ran } from "./types-CDSKa0vl.mjs";
+import { t as commands } from "./commands-C1kIfOG5.mjs";
+import { t as defineCommand } from "./define-BPpZcpxW.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-CUPSFM85.mjs";
 export { commands, controlRefused, defineCommand, run };

package/dist/{define-BbgXv4cy.d.mts → define-BPpZcpxW.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-q98SwADR.mjs";
+import { c as Source, n as Command, o as InputSchema } from "./types-CDSKa0vl.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-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 };