@moku-labs/game 0.0.2 → 0.1.0

package/dist/run-tlcn1w7y.mjs

@@ -0,0 +1,944 @@
+import { n as isDev, s as graphHash, t as controlRefused } from "./dev-CcwFrwok.mjs";
+import { a as defineCommand, i as inputOrEmpty, n as isTainted, r as recordCheat } from "./session-DmAxY6Ll.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
+//#region src/plugins/anim/control.ts
+/**
+* @file anim plugin — the anim command of the `/control` door: switch reduced motion. Dev builds
+* only: the body starts with the inline dev guard, so a bundler `define` of `false` drops it, and
+* logs the `moku:dev` marker.
+*/
+/**
+* Switches reduced motion on or off, the way the player's "Less motion" setting does. Answers
+* the switch as it is afterwards.
+*
+* @example
+* ```ts
+* // Check the popups of the settings screen with no motion at all.
+* (await run(app, commands.reducedMotion, { on: true })).value; // true
+* ```
+*/
+const reducedMotionCommand = defineCommand({
+	id: "game.reducedMotion",
+	title: "Reduced motion",
+	input: { on: "boolean" },
+	effect: "cosmetic",
+	run: (app, { on }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.reducedMotion",
+			on
+		});
+		app.anim.setReducedMotion(on);
+		return app.anim.reducedMotion();
+	}
+});
+//#endregion
+//#region src/plugins/input/control.ts
+/**
+* @file input plugin — the input commands of the `/control` door: a drag from one view onto
+* another and a key press. Each goes through `app.input`, so the gate decides and the session
+* stays clean. Dev builds only: every body starts with the inline dev guard, so a bundler
+* `define` of `false` drops it, and logs the `moku:dev` marker. `readTarget` is shared with the
+* `game.tap` command of ui, which taps a view by the same projection key.
+*/
+/**
+* Tells whether the JSON a command got names a view by its projection key.
+*
+* @param value - The JSON.
+* @returns True for an object with a string `projection` and a string `key`.
+* @example
+* ```ts
+* isProjectionTarget({ projection: "board.items", key: "i5" }); // true
+* ```
+*/
+function isProjectionTarget(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.projection === "string" && typeof value.key === "string";
+}
+/**
+* Reads the projection key of a view out of the JSON a command got.
+*
+* @param value - The JSON: `{ projection, key }`.
+* @returns The target, a fresh object.
+* @throws {Error} When the JSON is not an object with a string `projection` and a string `key`.
+*/
+function readTarget(value) {
+	if (isProjectionTarget(value)) return {
+		projection: value.projection,
+		key: value.key
+	};
+	throw new Error("[game] The target is not a projection key.\n  Pass a view like { projection: \"board.items\", key: \"i5\" }.");
+}
+/**
+* Drags one view onto another, both by their projection keys. Answers what `input.drag`
+* answers: whether the gate took the answer.
+*
+* @example
+* ```ts
+* // Merge two logs of level 1 on the board.
+* const from = { projection: "board.items", key: "i5" };
+* (await run(app, commands.drag, { from, to: { projection: "board.items", key: "i7" } })).value; // true
+* ```
+*/
+const dragCommand = defineCommand({
+	id: "game.drag",
+	title: "Drag",
+	input: {
+		from: "json",
+		to: "json"
+	},
+	effect: "route",
+	run: (app, { from, to }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.drag" });
+		return app.input.drag(readTarget(from), readTarget(to));
+	}
+});
+/**
+* Presses a key without a keyboard, with or without Shift. Answers whether a listener handled
+* it.
+*
+* @example
+* ```ts
+* // Close the settings popup the way Escape does.
+* (await run(app, commands.key, { key: "Escape" })).value; // true
+* (await run(app, commands.key, { key: "Tab", shift: true })).value; // true: the focus moved back
+* ```
+*/
+const keyCommand = defineCommand({
+	id: "game.key",
+	title: "Press a key",
+	input: {
+		key: "string",
+		shift: "boolean?"
+	},
+	effect: "route",
+	run: (app, { key, shift = false }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.key",
+			key
+		});
+		return app.input.pressKey(key, { shift });
+	}
+});
+//#endregion
+//#region src/plugins/lifecycle/control.ts
+/**
+* @file lifecycle plugin — the lifecycle commands of the `/control` door: pause and resume the
+* game for the editor, through the `devtools` pause reason, so another reason keeps its hold.
+* Dev builds only: every body starts with the inline dev guard, so a bundler `define` of `false`
+* drops it, and logs the `moku:dev` marker.
+*/
+/**
+* Pauses the game with the pause reason `devtools`. Answers whether the game is paused.
+*
+* @example
+* ```ts
+* // The editor's pause button: the world stands, and `game.step` moves it frame by frame.
+* (await run(app, commands.pause)).value; // true
+* app.lifecycle.reasons(); // ["devtools"]
+* ```
+*/
+const pauseCommand = defineCommand({
+	id: "game.pause",
+	title: "Pause",
+	input: {},
+	effect: "cosmetic",
+	run: (app) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.pause" });
+		app.lifecycle.push("devtools");
+		return app.lifecycle.isPaused();
+	}
+});
+/**
+* Takes the pause reason `devtools` back. Answers whether the game is still paused: another
+* reason, such as a hidden tab, keeps its hold.
+*
+* @example
+* ```ts
+* // The editor's play button while the tab is visible.
+* (await run(app, commands.resume)).value; // false: the game runs again
+* ```
+*/
+const resumeCommand = defineCommand({
+	id: "game.resume",
+	title: "Resume",
+	input: {},
+	effect: "cosmetic",
+	run: (app) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.resume" });
+		app.lifecycle.pop("devtools");
+		return app.lifecycle.isPaused();
+	}
+});
+//#endregion
+//#region src/plugins/renderer/control.ts
+/**
+* @file renderer plugin — the renderer commands of the `/control` door: take a picture of the
+* canvas and switch the debug drawing. Dev builds only: every body starts with the inline dev
+* guard, so a bundler `define` of `false` drops it, and logs the `moku:dev` marker.
+*/
+/**
+* A PNG of the whole canvas taken at the end of the next drawn frame, as a data URL.
+* `undefined` while the renderer is inert, as in a headless test.
+*
+* @example
+* ```ts
+* // The editor attaches the screen to a bug report.
+* (await run(app, commands.capture)).value; // "data:image/png;base64,iVBORw0KGgo…"
+* ```
+*/
+const captureCommand = defineCommand({
+	id: "game.capture",
+	title: "Capture",
+	input: {},
+	effect: "read",
+	run: (app) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.capture" });
+		return app.renderer.capture();
+	}
+});
+/**
+* Switches the debug drawing: `nineSlice` outlines every nine-slice and the lines Pixi cuts its
+* texture at. Answers the switches as they are afterwards.
+*
+* @example
+* ```ts
+* // Check where the settings popup cuts its parchment.
+* (await run(app, commands.debug, { nineSlice: true })).value; // { nineSlice: true }
+* ```
+*/
+const debugCommand = defineCommand({
+	id: "game.debug",
+	title: "Debug drawing",
+	input: { nineSlice: "boolean" },
+	effect: "cosmetic",
+	run: (app, { nineSlice }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.debug",
+			nineSlice
+		});
+		app.renderer.sync.debug.nineSlice(nineSlice);
+		return app.renderer.sync.debug.state();
+	}
+});
+//#endregion
+//#region src/plugins/time/control.ts
+/**
+* @file time plugin — the time command of the `/control` door: step frames by hand. Dev builds
+* only: the body starts with the inline dev guard, so a bundler `define` of `false` drops it, and
+* logs the `moku:dev` marker.
+*/
+/** The length of one frame at 60 fps, the step a frame count takes by default. */
+const FRAME_MS = 1e3 / 60;
+/**
+* Refuses a frame count that is not a whole number of zero or more.
+*
+* @param frames - The frame count.
+* @throws {Error} When it is negative, fractional or not finite.
+*/
+function checkFrames(frames) {
+	if (Number.isInteger(frames) && frames >= 0) return;
+	throw new Error(`[game] game.step takes a whole number of frames.\n  Pass 0 or a positive whole number, not ${String(frames)}.`);
+}
+/**
+* Runs frames by hand, one `time.step` each, also while the game is paused, and answers the time
+* after them. A frame lasts 1000/60 ms unless `deltaMs` says otherwise.
+*
+* @example
+* ```ts
+* // The editor paused the game on a merge; step three frames to watch the item land.
+* const ran = await run(app, commands.step, { frames: 3 });
+* ran.value; // { delta: 16.666…, elapsed: 50, scale: 1, frame: 3, idle: false }
+* ```
+*/
+const stepCommand = defineCommand({
+	id: "game.step",
+	title: "Step frames",
+	input: {
+		frames: "number",
+		deltaMs: "number?"
+	},
+	effect: "cosmetic",
+	run: (app, { frames, deltaMs = FRAME_MS }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.step",
+			frames
+		});
+		checkFrames(frames);
+		for (let frame = 0; frame < frames; frame += 1) app.time.step(deltaMs);
+		return app.time.snapshot();
+	}
+});
+//#endregion
+//#region src/plugins/ui/control.ts
+/**
+* @file ui plugin — the two ui commands of the `/control` door: a tap on a keyed element or on a
+* view, and the text typed into a field. The tap goes through `app.input`, so the gate decides;
+* the text goes through `app.ui.fill`, which writes a component's local and answers nothing. The
+* session stays clean. Dev builds only: each body starts with the inline dev guard, so a bundler
+* `define` of `false` drops it, and logs the `moku:dev` marker.
+*/
+/**
+* Finds the entity of a keyed ui element on screen.
+*
+* @param ui - The ui API.
+* @param key - The `key` prop of the element.
+* @returns The entity.
+* @throws {Error} When no element with the key is on screen.
+*/
+function elementOf(ui, key) {
+	const entity = ui.find(key);
+	if (entity !== void 0) return entity;
+	throw new Error(`[game] No element with the key "${key}" is on screen.\n  Read sources.ui for the keys on screen.`);
+}
+/**
+* Taps a ui element by its key, or a view by its projection key: exactly one of the two. Answers
+* what `input.tap` answers: whether the gate took the answer.
+*
+* @example
+* ```ts
+* // Home rests: tap the Play plank, then the first generator of the board.
+* (await run(app, commands.tap, { key: "play" })).value; // true
+* await run(app, commands.tap, { target: { projection: "board.generators", key: "g1" } });
+* ```
+*/
+const tapCommand = defineCommand({
+	id: "game.tap",
+	title: "Tap",
+	input: {
+		key: "string?",
+		target: "json?"
+	},
+	effect: "route",
+	run: (app, { key, target }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.tap",
+			key
+		});
+		if (key !== void 0 && target === void 0) return app.input.tap(elementOf(app.ui, key));
+		if (target !== void 0 && key === void 0) return app.input.tap(readTarget(target));
+		throw new Error("[game] game.tap takes a key or a target.\n  Pass exactly one of { key } and { target }.");
+	}
+});
+/**
+* Types into a text field by its key, the way `app.ui.fill` does: the field becomes the one being
+* edited, the value cut to its `maxLength` is written into it and into the local of its
+* component. Answers what `fill` answers: false for a key that is no live `input`.
+*
+* @example
+* ```ts
+* // The Rename popup rests: type the name, then submit it with the Enter key.
+* (await run(app, commands.fill, { key: "nameField", value: "Alex" })).value; // true
+* await run(app, commands.key, { key: "Enter" }); // the gate takes { intent: "save", payload: { name: "Alex" } }
+* ```
+*/
+const fillCommand = defineCommand({
+	id: "game.fill",
+	title: "Fill",
+	input: {
+		key: "string",
+		value: "string"
+	},
+	effect: "route",
+	run: (app, { key, value }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.fill",
+			key
+		});
+		return app.ui.fill(key, value);
+	}
+});
+//#endregion
+//#region src/plugins/flow/json.ts
+/**
+* Tells whether a JSON value is an object.
+*
+* @param value - The value.
+* @returns True for an object that is neither null nor an array.
+* @example
+* ```ts
+* isRecord({ at: "home" }); // true
+* ```
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Builds the error of a route that is not a list of steps.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* invalidRoute().message.startsWith("[game] The route is not a list of route steps."); // true
+* ```
+*/
+function invalidRoute() {
+	return /* @__PURE__ */ new Error("[game] The route is not a list of route steps.\n  Pass steps like { at: \"home\", intent: \"play\" } or { at: \"board\", result: { outcome: \"left\" } }.");
+}
+/**
+* Reads the result of a skipped sub-flow.
+*
+* @param result - The `result` field of a step.
+* @returns The outcome and its payload, if any.
+* @throws {Error} When the result has no outcome name.
+* @example
+* ```ts
+* readResult({ outcome: "won", payload: { stars: 3 } }); // { outcome: "won", payload: { stars: 3 } }
+* ```
+*/
+function readResult(result) {
+	if (!isRecord(result) || typeof result.outcome !== "string") throw invalidRoute();
+	const { outcome, payload } = result;
+	return payload === void 0 ? { outcome } : {
+		outcome,
+		payload
+	};
+}
+/**
+* Reads one step: an answer at a rest node, or a substituted sub-flow result.
+*
+* @param step - One element of the route.
+* @returns The step.
+* @throws {Error} When the step has no `at`, or neither an intent nor a result.
+* @example
+* ```ts
+* readStep({ at: "home", intent: "play" }); // { at: "home", intent: "play" }
+* ```
+*/
+function readStep(step) {
+	if (!isRecord(step) || typeof step.at !== "string") throw invalidRoute();
+	const { at, intent, payload, result } = step;
+	if (typeof intent === "string") return payload === void 0 ? {
+		at,
+		intent
+	} : {
+		at,
+		intent,
+		payload
+	};
+	if (result !== void 0) return {
+		at,
+		result: readResult(result)
+	};
+	throw invalidRoute();
+}
+/**
+* Reads a route out of JSON.
+*
+* @param value - The JSON the editor sent.
+* @returns The route steps, in order.
+* @throws {Error} When the value is not a list of steps.
+* @example
+* ```ts
+* readRoute([{ at: "home", intent: "play" }]); // [{ at: "home", intent: "play" }]
+* ```
+*/
+function readRoute(value) {
+	if (!Array.isArray(value)) throw invalidRoute();
+	return value.map((step) => readStep(step));
+}
+/**
+* Reads an rng state: a seed and a number per stream.
+*
+* @param value - The JSON value.
+* @returns The rng state, or `undefined` when the value is not one.
+* @example
+* ```ts
+* readRng({ seed: 42, streams: { chest: 3 } }); // { seed: 42, streams: { chest: 3 } }
+* ```
+*/
+function readRng(value) {
+	if (!isRecord(value) || typeof value.seed !== "number" || !isRecord(value.streams)) return;
+	const streams = {};
+	for (const [name, draws] of Object.entries(value.streams)) {
+		if (typeof draws !== "number") return void 0;
+		streams[name] = draws;
+	}
+	return {
+		seed: value.seed,
+		streams
+	};
+}
+/**
+* Builds the error of a value that is not a bookmark.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* invalidBookmark().message.startsWith("[game] The bookmark is not"); // true
+* ```
+*/
+function invalidBookmark() {
+	return /* @__PURE__ */ new Error("[game] The bookmark is not a flow.bookmark() value.\n  Pass the JSON that game.bookmark returned.");
+}
+/**
+* Reads a bookmark out of JSON, the value `flow.bookmark()` made and the editor kept.
+*
+* @param value - The JSON the editor sent.
+* @returns The bookmark.
+* @throws {Error} When a field is missing or has the wrong type.
+* @example
+* ```ts
+* readBookmark(JSON.parse(saved)).path; // "board/awaitIntent"
+* ```
+*/
+function readBookmark(value) {
+	if (!isRecord(value)) throw invalidBookmark();
+	const { path, input, player, session, graph } = value;
+	const rng = readRng(value.rng);
+	if (typeof path !== "string" || typeof graph !== "string" || !(input !== void 0 && player !== void 0 && session !== void 0) || rng === void 0) throw invalidBookmark();
+	return {
+		path,
+		input,
+		player,
+		session,
+		rng,
+		graph
+	};
+}
+/**
+* Builds the error of a value that is not a repro.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* invalidRepro().message.startsWith("[game] The repro is not a Repro."); // true
+* ```
+*/
+function invalidRepro() {
+	return /* @__PURE__ */ new Error("[game] The repro is not a Repro.\n  Pass { player, route } with an optional session, rng and checkpoint.");
+}
+/**
+* Reads the optional fields of a repro onto it.
+*
+* @param value - The JSON object of the repro.
+* @param repro - The repro with its player and route.
+* @returns The repro with its session, rng and checkpoint.
+* @throws {Error} When the rng or the checkpoint has the wrong type.
+*/
+function readReproOptions(value, repro) {
+	const { session, checkpoint } = value;
+	if (session !== void 0) repro.session = session;
+	if (value.rng !== void 0) {
+		const rng = readRng(value.rng);
+		if (rng === void 0) throw invalidRepro();
+		repro.rng = rng;
+	}
+	if (checkpoint !== void 0) {
+		if (typeof checkpoint !== "string") throw invalidRepro();
+		repro.checkpoint = checkpoint;
+	}
+	return repro;
+}
+/**
+* Reads a repro out of JSON: the `/testing` repro of a bug report.
+*
+* @param value - The JSON the editor sent.
+* @returns The repro.
+* @throws {Error} When the player is missing, a field has the wrong type or the route is broken.
+* @example
+* ```ts
+* readRepro({ player: { coins: 7 }, checkpoint: "home", route: [] }).checkpoint; // "home"
+* ```
+*/
+function readRepro(value) {
+	if (!isRecord(value) || value.player === void 0) throw invalidRepro();
+	return readReproOptions(value, {
+		player: value.player,
+		route: readRoute(value.route)
+	});
+}
+//#endregion
+//#region src/plugins/flow/control.ts
+/**
+* Enters a bookmark, or a repro's bookmark followed by its route.
+*
+* @param app - The app.
+* @param input - Exactly one of a bookmark and a repro, as JSON.
+* @param input.bookmark - A `flow.bookmark()` value.
+* @param input.repro - A `/testing` repro.
+* @returns The state the game rests in afterwards.
+* @throws {Error} When both or neither are given, or the JSON is not of its shape.
+*/
+async function restoreFrom(app, input) {
+	const { bookmark, repro } = input;
+	if (bookmark !== void 0 && repro === void 0) {
+		await app.flow.restore(readBookmark(bookmark));
+		return app.flow.state();
+	}
+	if (repro !== void 0 && bookmark === void 0) {
+		const parsed = readRepro(repro);
+		await app.flow.restore(reproBookmark(app, parsed));
+		return app.flow.walk(parsed.route);
+	}
+	throw new Error("[game] game.restore takes a bookmark or a repro.\n  Pass exactly one of { bookmark } and { repro }.");
+}
+/**
+* Answers the gate, the way a tap on a button does. Goes through the graph: the session stays
+* clean.
+*
+* @example
+* ```ts
+* // The home screen rests: tap Play without touching the screen.
+* const ran = await run(app, commands.answer, { intent: "play" });
+* ran.value; // true: "home" waits for "play"
+* ran.state.tainted; // false
+* ```
+*/
+const answerCommand = defineCommand({
+	id: "game.answer",
+	title: "Answer",
+	input: {
+		intent: "string",
+		payload: "json?"
+	},
+	effect: "route",
+	run: (app, { intent, payload }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.answer",
+			intent
+		});
+		return app.flow.gate.answer(payload === void 0 ? { intent } : {
+			intent,
+			payload
+		});
+	}
+});
+/**
+* Walks a route in fast mode through the graph. The session stays clean.
+*
+* @example
+* ```ts
+* // Skip the menu and stand on the board.
+* const ran = await run(app, commands.walk, { route: [{ at: "home", intent: "play" }] });
+* ran.value.path; // "board/awaitIntent"
+* ```
+*/
+const walkCommand = defineCommand({
+	id: "game.walk",
+	title: "Walk a route",
+	input: { route: "json" },
+	effect: "route",
+	run: (app, { route }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.walk" });
+		return app.flow.walk(readRoute(route));
+	}
+});
+/**
+* Takes a bookmark of the rest point: the node plus the committed state, plain JSON.
+*
+* @example
+* ```ts
+* // The editor keeps the position before a risky test.
+* const { value } = await run(app, commands.bookmark);
+* value.path; // "board/awaitIntent"
+* ```
+*/
+const bookmarkCommand = defineCommand({
+	id: "game.bookmark",
+	title: "Bookmark",
+	input: {},
+	effect: "read",
+	run: (app) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.bookmark" });
+		return app.flow.bookmark();
+	}
+});
+/**
+* Restores a bookmark, or a repro: its state at its checkpoint, then its route. Replaces the
+* state outside the graph, so the session is tainted and the command journaled.
+*
+* @example
+* ```ts
+* // Load the bug report "the order stays after delivery".
+* const repro = { player: { coins: 40 }, checkpoint: "home", route: [{ at: "home", intent: "play" }] };
+* const ran = await run(app, commands.restore, { repro });
+* ran.state; // { path: "board/awaitIntent", frame: 12, tainted: true }
+* ```
+*/
+const restoreCommand = defineCommand({
+	id: "game.restore",
+	title: "Restore",
+	input: {
+		bookmark: "json?",
+		repro: "json?"
+	},
+	effect: "raw",
+	run: (app, input) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.restore" });
+		return restoreFrom(app, input);
+	}
+});
+//#endregion
+//#region src/plugins/flow/doors/commands.ts
+/**
+* @file flow/doors — the base commands: every command of the engine, keyed by a short name. Each
+* descriptor lives with the plugin that owns its data; this module only gathers them. Imported
+* by the door `src/control.ts` only, so no plugin reaches it and no import cycle forms.
+*/
+/**
+* Every command of the engine, keyed by its short name: what an editor lists as buttons and MCP
+* tools. Frozen. Each runs in dev builds only.
+*
+* @example
+* ```ts
+* // An e2e script taps Play, and the editor registers every command.
+* (await run(app, commands.tap, { key: "play" })).state.path; // "board/awaitIntent"
+* for (const command of Object.values(commands)) registry.add(command);
+* ```
+*/
+const commands = Object.freeze({
+	answer: answerCommand,
+	tap: tapCommand,
+	drag: dragCommand,
+	key: keyCommand,
+	walk: walkCommand,
+	bookmark: bookmarkCommand,
+	restore: restoreCommand,
+	step: stepCommand,
+	pause: pauseCommand,
+	resume: resumeCommand,
+	capture: captureCommand,
+	debug: debugCommand,
+	reducedMotion: reducedMotionCommand,
+	fill: fillCommand
+});
+//#endregion
+//#region src/plugins/flow/doors/run.ts
+/**
+* Reads where the game stands after a command.
+*
+* @param app - The app.
+* @returns The graph path, the frame and the taint.
+*/
+function envelopeOf(app) {
+	return {
+		path: app.flow.state().path,
+		frame: app.time.snapshot().frame,
+		tainted: isTainted(app)
+	};
+}
+/**
+* Runs a command in a dev build. A `cheat` or `raw` command taints the session and is journaled
+* before it runs, so a failing one still counts.
+*
+* @param app - The app the command acts on.
+* @param command - The command.
+* @param input - Its input; left out when every field of its schema is optional.
+* @returns The command's value and the envelope read after it.
+* @throws {Error} Outside a dev build, and whatever the command throws.
+* @example
+* ```ts
+* // An e2e script: load the bug report, then tap Play.
+* await run(app, commands.restore, { repro }); // state: { path: "home", frame: 12, tainted: true }
+* const ran = await run(app, commands.answer, { intent: "play" });
+* ran.value; // true
+* ran.state; // { path: "board/awaitIntent", frame: 14, tainted: true }
+* ```
+*/
+async function run(app, command, ...input) {
+	if (!isDev()) throw controlRefused();
+	const given = inputOrEmpty(input[0]);
+	if (command.effect === "cheat" || command.effect === "raw") recordCheat(app, command.id, given, app.time.snapshot().frame);
+	return {
+		value: await command.run(app, given),
+		state: envelopeOf(app)
+	};
+}
+//#endregion
+export { stepFrames as a, runRepro as i, commands as n, createHeadless as r, run as t };