@moku-labs/game 0.0.1 → 0.0.2

package/dist/control.mjs

@@ -0,0 +1,758 @@
+import { n as reproBookmark } from "./headless-CvamCUcR.mjs";
+import { a as defineCommand, i as inputOrEmpty, n as isTainted, r as recordCheat } from "./session-DmAxY6Ll.mjs";
+//#region src/plugins/flow/doors/dev.ts
+/**
+* Reads the dev flag at call time. Undefined means off: production is the default.
+*
+* @returns True only when `__MOKU_GAME_DEV__` is exactly `true`.
+* @example
+* ```ts
+* // The dev page set the flag in web/dev.ts before the engine started.
+* globalThis.__MOKU_GAME_DEV__ = true;
+* isDev(); // true
+* ```
+*/
+function isDev() {
+	return typeof __MOKU_GAME_DEV__ !== "undefined" && __MOKU_GAME_DEV__ === true;
+}
+/**
+* Builds the error a control command throws outside a dev build.
+*
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* // A production build called a /control command.
+* controlRefused().message; // "[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build."
+* ```
+*/
+function controlRefused() {
+	return /* @__PURE__ */ new Error("[game] Control commands run in dev builds only.\n  Define __MOKU_GAME_DEV__ as true in the dev build.");
+}
+//#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 ui command of the `/control` door: a tap on a keyed element or on a
+* view. It goes through `app.input`, so the gate decides and the session stays clean. 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.
+*/
+/**
+* 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 }.");
+	}
+});
+//#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
+});
+//#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 { commands, controlRefused, defineCommand, run };