@moku-labs/game 0.14.12 → 0.14.13

package/dist/{run-Bf2hKyjZ.mjs → run-BbipFRc6.mjs}

@@ -1,12 +1,12 @@
-import { a as sheetAlone } from "./capture-D7XvoHdH.mjs";
-import { n as isDev, r as notInstalled, t as controlRefused } from "./dev-Cc50Dk7H.mjs";
+import { a as sheetAlone, d as graphHash } from "./capture-D7XvoHdH.mjs";
+import { a as isDev, i as isControl, n as controlRefused, o as notInstalled, r as isAgent, t as controlReadOnly } from "./dev-DbHgx-R-.mjs";
 import { n as reproBookmark } from "./headless-BA6ffzqD.mjs";
-import { a as readTarget, i as isProjectionTarget, n as isTainted, o as inputOrEmpty, r as recordCheat, s as defineCommand } from "./session-DgukhR_7.mjs";
+import { a as readTarget, i as isProjectionTarget, n as isTainted, o as inputOrEmpty, r as recordCheat, s as defineCommand } from "./session-CeKgO2hy.mjs";
 //#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.
+* @file anim plugin — the anim command of the `/control` door: switch reduced motion. Dev and
+* debug builds: the body starts with the inline agent guard of a cosmetic command, 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
@@ -24,7 +24,7 @@ const reducedMotionCommand = defineCommand({
 	input: { on: "boolean" },
 	effect: "cosmetic",
 	run: (app, { on }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
 		app.log.debug("moku:dev", {
 			command: "game.reducedMotion",
 			on
@@ -36,9 +36,9 @@ const reducedMotionCommand = defineCommand({
 //#endregion
 //#region src/plugins/audio/control.ts
 /**
-* @file audio plugin — the audio command of the `/control` door: mute the whole game. 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.
+* @file audio plugin — the audio command of the `/control` door: mute the whole game. Dev and
+* debug builds: the body starts with the inline agent guard of a cosmetic command, so a bundler
+* `define` of `false` drops it, and logs the `moku:dev` marker.
 */
 /**
 * Mutes or unmutes the `master` bus, so music and sfx both go silent; the stored volumes stay.
@@ -57,7 +57,7 @@ const muteCommand = defineCommand({
 	input: { muted: "boolean" },
 	effect: "cosmetic",
 	run: (app, { muted }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
 		if (app.audio === void 0) throw notInstalled("game.mute", "audioPlugin", "command");
 		app.log.debug("moku:dev", {
 			command: "game.mute",
@@ -68,12 +68,54 @@ const muteCommand = defineCommand({
 	}
 });
 //#endregion
+//#region src/plugins/effects/control.ts
+/**
+* @file effects plugin — the filter command of the `/control` door: turn one filter kind off or on through
+* `effects.diagnostics`. Dev and debug builds: the body starts with the inline guard of a cosmetic command, so a
+* bundler `define` of `false` drops it, and logs the `moku:dev` marker.
+*/
+/**
+* Turns one filter kind off or on, through `effects.diagnostics`. Answers the kinds that are off afterwards.
+* Cosmetic: it runs on a `--debug` page. A door for the MCP and the tools page; it carries no `overlay` marker.
+*
+* @throws {Error} `[game] No filter kind "fx.nope".` naming every known kind, and `notInstalled` without
+*   `effectsPlugin`.
+* @example
+* ```ts
+* // The editor's MCP turns the glow off on the phone, then on again.
+* (await run(app, commands.filter, { kind: "effects.glow", on: false })).value; // ["effects.glow"]
+* (await run(app, commands.filter, { kind: "effects.glow", on: true })).value; // []
+* ```
+*/
+const filterCommand = defineCommand({
+	id: "game.filter",
+	title: "Filter kind on or off",
+	input: {
+		kind: "string",
+		on: "boolean"
+	},
+	effect: "cosmetic",
+	run: (app, { kind, on }) => {
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.filter",
+			kind,
+			on
+		});
+		if (app.effects === void 0) throw notInstalled("game.filter", "effectsPlugin", "command");
+		const { diagnostics } = app.effects;
+		if (!(on ? diagnostics.enable(kind) : diagnostics.disable(kind))) throw new Error(`[game] No filter kind "${kind}".\n  Known: ${diagnostics.kinds().join(", ")}.`);
+		return diagnostics.disabled();
+	}
+});
+//#endregion
 //#region src/plugins/input/control.ts
 /**
 * @file input plugin — the input commands of the `/control` door: a drag from one view onto
 * another, a trace through many views 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. The targets
+* decides and the session stays clean. Dev builds and `--debug=full` builds: every body starts
+* with the inline control guard of a route command, so a bundler `define` of `false` drops it,
+* and logs the `moku:dev` marker. The targets
 * are read with `target.ts`; `readTarget` is re-exported here for the `game.tap` command of ui,
 * which taps a view by the same projection key.
 */
@@ -111,7 +153,7 @@ const dragCommand = defineCommand({
 	},
 	effect: "route",
 	run: (app, { from, to }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlRefused();
 		app.log.debug("moku:dev", { command: "game.drag" });
 		return app.input.drag(readTarget(from), readTarget(to));
 	}
@@ -133,7 +175,7 @@ const traceCommand = defineCommand({
 	input: { path: "json" },
 	effect: "route",
 	run: (app, { path }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlRefused();
 		app.log.debug("moku:dev", { command: "game.trace" });
 		return app.input.trace(readPath(path));
 	}
@@ -158,7 +200,7 @@ const keyCommand = defineCommand({
 	},
 	effect: "route",
 	run: (app, { key, shift = false }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlRefused();
 		app.log.debug("moku:dev", {
 			command: "game.key",
 			key
@@ -171,8 +213,8 @@ const keyCommand = defineCommand({
 /**
 * @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.
+* Dev and debug builds: every body starts with the inline agent guard of a cosmetic command, 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.
@@ -190,7 +232,7 @@ const pauseCommand = defineCommand({
 	input: {},
 	effect: "cosmetic",
 	run: (app) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
 		app.log.debug("moku:dev", { command: "game.pause" });
 		app.lifecycle.push("devtools");
 		return app.lifecycle.isPaused();
@@ -212,7 +254,7 @@ const resumeCommand = defineCommand({
 	input: {},
 	effect: "cosmetic",
 	run: (app) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
 		app.log.debug("moku:dev", { command: "game.resume" });
 		app.lifecycle.pop("devtools");
 		return app.lifecycle.isPaused();
@@ -476,8 +518,10 @@ function readRepro(value) {
 //#region src/plugins/renderer/control.ts
 /**
 * @file renderer plugin — the renderer commands of the `/control` door: take a picture of the
-* canvas, with its options, 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.
+* canvas, with its options, and switch the debug drawing. Dev and debug builds: every body starts with
+* the inline agent guard of a read or cosmetic command, so a bundler `define` of `false` drops it,
+* and logs the `moku:dev` marker. A capture with `diff` writes the state, so it also takes the
+* control guard: a `--debug` page refuses it.
 */
 /** The input fields of `game.capture`, in the order its `moku:dev` entry lists them. */
 const CAPTURE_FIELDS = [
@@ -729,7 +773,8 @@ async function captureDiff(app, options, diff, raw) {
 * itself as a raw write (`tainted` turns true), restores the bookmark and waits for its gate, takes
 * that picture, restores where the game stood and waits again, and answers the pixel diff of now
 * against then. While the game is paused it steps each frame it waits on, 1000/60 ms of game time.
-* `undefined` while the renderer is inert, as in a headless test.
+* `undefined` while the renderer is inert, as in a headless test. A `--debug` page takes the
+* picture and refuses `diff` with the read-only error of `controlReadOnly`.
 *
 * @example
 * ```ts
@@ -751,7 +796,7 @@ const captureCommand = defineCommand({
 	},
 	effect: "read",
 	run: (app, input) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
 		const given = givenFields(input);
 		app.log.debug("moku:dev", given.length === 0 ? { command: "game.capture" } : {
 			command: "game.capture",
@@ -759,42 +804,58 @@ const captureCommand = defineCommand({
 		});
 		const options = readOptions(input);
 		if (input.diff === void 0) return app.renderer.capture(options);
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlReadOnly("game.capture diff");
 		const diff = readDiff(input.diff);
 		if (options.sheet !== void 0) throw sheetAlone();
 		return captureDiff(app, options, diff, input.diff);
 	}
 });
 /**
-* Switches the debug drawing: `nineSlice` outlines every nine-slice and the lines Pixi cuts its
-* texture at. Answers the switches as they are afterwards.
+* Switches the debug drawing and checks: `nineSlice` outlines every nine-slice and the lines Pixi
+* cuts its texture at, `verifyFrames` compares every frame the renderer skips (and every kept
+* picture) with the same frame drawn live, `kept` draws every filtered view live (false) or lets
+* the renderer keep pictures (true). Each field given is applied, one left out keeps its switch; a
+* call with none answers the switches unchanged. 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 }
+* (await run(app, commands.debug, { nineSlice: true })).value; // { nineSlice: true, verifyFrames: false, kept: true }
+* // The visual runner checks the skipped frames of a test in the browser.
+* (await run(app, commands.debug, { verifyFrames: true })).value; // { nineSlice: true, verifyFrames: true, kept: true }
+* // The editor measures the memory screen without kept pictures.
+* (await run(app, commands.debug, { kept: false })).value; // { nineSlice: true, verifyFrames: true, kept: false }
 * ```
 */
 const debugCommand = defineCommand({
 	id: "game.debug",
 	title: "Debug drawing",
-	input: { nineSlice: "boolean" },
+	input: {
+		nineSlice: "boolean?",
+		verifyFrames: "boolean?",
+		kept: "boolean?"
+	},
 	effect: "cosmetic",
-	run: (app, { nineSlice }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+	run: (app, { nineSlice, verifyFrames, kept }) => {
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
 		app.log.debug("moku:dev", {
 			command: "game.debug",
-			nineSlice
+			...nineSlice === void 0 ? {} : { nineSlice },
+			...verifyFrames === void 0 ? {} : { verifyFrames },
+			...kept === void 0 ? {} : { kept }
 		});
-		app.renderer.sync.debug.nineSlice(nineSlice);
+		if (nineSlice !== void 0) app.renderer.sync.debug.nineSlice(nineSlice);
+		if (verifyFrames !== void 0) app.renderer.sync.debug.verifyFrames(verifyFrames);
+		if (kept !== void 0) app.renderer.sync.debug.kept(kept);
 		return app.renderer.sync.debug.state();
 	}
 });
 //#endregion
 //#region src/plugins/time/control.ts
 /**
-* @file time plugin — the time commands of the `/control` door: step frames by hand and set the
-* time scale. 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.
+* @file time plugin — the time commands of the `/control` door: step frames by hand, set the
+* time scale and force the frame rate. Dev and debug builds: every body starts with the inline agent guard of a cosmetic
+* command, 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;
@@ -839,7 +900,7 @@ const stepCommand = defineCommand({
 	},
 	effect: "cosmetic",
 	run: (app, { frames, deltaMs = FRAME_MS }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
 		app.log.debug("moku:dev", {
 			command: "game.step",
 			frames
@@ -865,7 +926,7 @@ const timeScaleCommand = defineCommand({
 	input: { scale: "number" },
 	effect: "cosmetic",
 	run: (app, { scale }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
 		app.log.debug("moku:dev", {
 			command: "game.timeScale",
 			scale
@@ -875,14 +936,40 @@ const timeScaleCommand = defineCommand({
 		return app.time.snapshot();
 	}
 });
+/**
+* Forces the frame rate, or gives it back to the config without `fps`, and answers the rate after
+* the call. For an A/B run on the phone: the same screen at 120 and at 60. A wrong `fps` is
+* refused by `setRate` with its own message.
+*
+* @example
+* ```ts
+* (await run(app, commands.frameRate, { fps: 60 })).value.fps; // 60
+* (await run(app, commands.frameRate, {})).value.mode; // "auto" with adaptive, "fixed" without
+* ```
+*/
+const frameRateCommand = defineCommand({
+	id: "game.frameRate",
+	title: "Frame rate",
+	input: { fps: "number?" },
+	effect: "cosmetic",
+	run: (app, { fps }) => {
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.frameRate",
+			fps
+		});
+		return app.time.setRate(fps === void 0 ? "auto" : fps);
+	}
+});
 //#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.
+* session stays clean. Dev builds and `--debug=full` builds: each body starts with the inline
+* control guard of a route command, so a bundler `define` of `false` drops it, and logs the
+* `moku:dev` marker.
 */
 /**
 * Finds the entity of a keyed ui element on screen.
@@ -917,7 +1004,7 @@ const tapCommand = defineCommand({
 	},
 	effect: "route",
 	run: (app, { key, target }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlRefused();
 		app.log.debug("moku:dev", {
 			command: "game.tap",
 			key
@@ -948,7 +1035,7 @@ const fillCommand = defineCommand({
 	},
 	effect: "route",
 	run: (app, { key, value }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlRefused();
 		app.log.debug("moku:dev", {
 			command: "game.fill",
 			key
@@ -958,6 +1045,7 @@ const fillCommand = defineCommand({
 });
 //#endregion
 //#region src/plugins/flow/control.ts
+const noPayload = null;
 /**
 * Restores a bookmark with its `scene` expected first, so the node the restore enters mounts it.
 * A refused restore puts the record back to the mounted scene, when one is mounted: no later
@@ -1006,6 +1094,46 @@ async function restoreFrom(app, input) {
 	throw new Error("[game] game.restore takes a bookmark or a repro.\n  Pass exactly one of { bookmark } and { repro }.");
 }
 /**
+* Reads the save `game.saveImport` got: an object with the three trees of `game.saveExport`.
+*
+* @param save - The JSON the editor sent.
+* @returns The player, the session and the rng.
+* @throws {Error} When it is not an object with `player`, `session` and `rng`.
+* @example
+* ```ts
+* readSave({ player: { coins: 40 }, session: {}, rng: { seed: 42, streams: {} } }).player; // { coins: 40 }
+* ```
+*/
+function readSave(save) {
+	if (typeof save === "object" && save !== null && !Array.isArray(save)) {
+		const { player, session, rng } = save;
+		if (player !== void 0 && session !== void 0 && rng !== void 0) return {
+			player,
+			session,
+			rng
+		};
+	}
+	throw new Error("[game] game.saveImport needs { player, session, rng } of game.saveExport.");
+}
+/**
+* Builds the bookmark a save is imported at: the start of the main flow with the save's trees and
+* the hash of the graph that runs now. The start may be a transit node: `flow.restore` enters
+* one of the graph it was made for and plays it, as a fresh start does, on the imported trees.
+*
+* @param app - The started app.
+* @param save - The player, the session and the rng of the save.
+* @returns The bookmark, as JSON for `restoreFrom`.
+*/
+function startBookmark(app, save) {
+	const graph = app.flow.describe();
+	return {
+		path: graph.flows[graph.main]?.start ?? "",
+		input: noPayload,
+		...save,
+		graph: graphHash(graph)
+	};
+}
+/**
 * Answers the gate, the way a tap on a button does. Goes through the graph: the session stays
 * clean.
 *
@@ -1026,7 +1154,7 @@ const answerCommand = defineCommand({
 	},
 	effect: "route",
 	run: (app, { intent, payload }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlRefused();
 		app.log.debug("moku:dev", {
 			command: "game.answer",
 			intent
@@ -1053,7 +1181,7 @@ const walkCommand = defineCommand({
 	input: { route: "json" },
 	effect: "route",
 	run: (app, { route }) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlRefused();
 		app.log.debug("moku:dev", { command: "game.walk" });
 		return app.flow.walk(readRoute(route));
 	}
@@ -1080,7 +1208,7 @@ const bookmarkCommand = defineCommand({
 	input: {},
 	effect: "read",
 	run: (app) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
 		app.log.debug("moku:dev", { command: "game.bookmark" });
 		const bookmark = app.flow.bookmark();
 		const scene = app.scenes?.current();
@@ -1122,11 +1250,70 @@ const restoreCommand = defineCommand({
 	},
 	effect: "raw",
 	run: (app, input) => {
-		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlRefused();
 		app.log.debug("moku:dev", { command: "game.restore" });
 		return restoreFrom(app, input);
 	}
 });
+/**
+* Answers the committed state as the save holds it: the player, the session and the rng, plain
+* JSON. A read: it runs on a `--debug` page too, so a tester's progress can leave the store app.
+*
+* @example
+* ```ts
+* // The editor takes the tester's progress from the store app on the phone.
+* (await run(app, commands.saveExport, {})).value; // { player: { coins: 40, … }, session: { … }, rng: { seed: 42, streams: {} } }
+* ```
+*/
+const saveExportCommand = defineCommand({
+	id: "game.saveExport",
+	title: "Export the save",
+	input: {},
+	effect: "read",
+	run: (app) => {
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.saveExport" });
+		const { player, session, rng } = app.model.store.snapshot();
+		return {
+			player,
+			session,
+			rng
+		};
+	}
+});
+/**
+* Puts a save of `game.saveExport` in place and writes it, so the next start of the app reads it:
+* the trees are restored at the main flow's start, and the game lands where a fresh start with
+* them lands. A start that is a rest node is entered; a transit node runs again on the imported
+* trees, rng included, up to the first gate it opens, at a rest node or a popup. Then the store
+* flushes. Replaces the state outside the graph, so the session is tainted and the
+* command journaled. A `--debug` page refuses it; `--debug=full` and the dev page run it.
+*
+* @throws {Error} `[game] game.saveImport needs { player, session, rng } of game.saveExport.` for
+*   a value without the three trees.
+* @example
+* ```ts
+* // The debug app beside the store app gets the save exported from the store app. Its main
+* // flow starts at "boot", a transit node: boot runs again on the save and the game rests at home.
+* const ran = await run(app, commands.saveImport, { save: exported });
+* ran.value; // { restored: true }
+* ran.state.path; // "home"
+* ```
+*/
+const saveImportCommand = defineCommand({
+	id: "game.saveImport",
+	title: "Import a save",
+	input: { save: "json" },
+	effect: "raw",
+	run: async (app, { save }) => {
+		if ((typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) && (typeof __MOKU_GAME_CONTROL__ === "undefined" || !__MOKU_GAME_CONTROL__)) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.saveImport" });
+		await restoreFrom(app, { bookmark: startBookmark(app, readSave(save)) });
+		await app.flow.walk([]);
+		await app.model.store.flush();
+		return { restored: true };
+	}
+});
 //#endregion
 //#region src/plugins/flow/doors/commands.ts
 /**
@@ -1136,7 +1323,8 @@ const restoreCommand = defineCommand({
 */
 /**
 * 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.
+* tools. Frozen. Each runs on the dev page and on a debug page, by the profile `run` checks: a
+* `--debug` page runs the read and cosmetic ones.
 *
 * @example
 * ```ts
@@ -1153,6 +1341,8 @@ const commands = Object.freeze({
 	walk: walkCommand,
 	bookmark: bookmarkCommand,
 	restore: restoreCommand,
+	saveExport: saveExportCommand,
+	saveImport: saveImportCommand,
 	step: stepCommand,
 	pause: pauseCommand,
 	resume: resumeCommand,
@@ -1161,8 +1351,10 @@ const commands = Object.freeze({
 	reducedMotion: reducedMotionCommand,
 	fill: fillCommand,
 	timeScale: timeScaleCommand,
+	frameRate: frameRateCommand,
 	mute: muteCommand,
-	trace: traceCommand
+	trace: traceCommand,
+	filter: filterCommand
 });
 //#endregion
 //#region src/plugins/flow/doors/run.ts
@@ -1180,14 +1372,17 @@ function envelopeOf(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.
+* Runs a command in a dev build or a debug build. A debug build of `--debug` runs the read and
+* cosmetic commands only; `--debug=full` and the dev page run every command. 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.
+* @throws {Error} Outside dev builds and debug builds (read and cosmetic commands; every command
+*   with `--debug=full`), the read-only refusal of `controlReadOnly` for a `route`, `cheat` or
+*   `raw` command on a `--debug` page, and whatever the command throws.
 * @example
 * ```ts
 * // An e2e script: load the bug report, then tap Play.
@@ -1195,10 +1390,14 @@ function envelopeOf(app) {
 * const ran = await run(app, commands.answer, { intent: "play" });
 * ran.value; // true
 * ran.state; // { path: "board/awaitIntent", frame: 14, tainted: true }
+* // On a --debug page: await run(app, commands.tap, { key: "play" }); // throws "[game] The command game.tap changes the game: …"
 * ```
 */
 async function run(app, command, ...input) {
-	if (!isDev()) throw controlRefused();
+	if (!isDev() && !isControl()) {
+		if (!isAgent()) throw controlRefused();
+		if (command.effect !== "read" && command.effect !== "cosmetic") throw controlReadOnly(command.id);
+	}
 	const given = inputOrEmpty(input[0]);
 	if (command.effect === "cheat" || command.effect === "raw") recordCheat(app, command.id, given, app.time.snapshot().frame);
 	return {

package/dist/{runtime-BCnKn0xf.d.mts → runtime-DoSlRx8X.d.mts}

@@ -1,4 +1,4 @@
-import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-DOlpeuGx.mjs";
+import { a as JsxChild, h as UiIntrinsicElements, t as DescriptionNode } from "./types-7GXcXxxv.mjs";
 
 //#region src/plugins/ui/jsx/runtime.d.ts
 /** What the compiler passes as props: the children plus whatever the tag declared. */

package/dist/{session-DgukhR_7.mjs → session-CeKgO2hy.mjs}

@@ -39,8 +39,13 @@ function defineSource(source) {
 	return Object.freeze(source);
 }
 /**
-* Declares a command: a dev-only action the editor lists and runs. Its body starts with the
-* inline dev guard, so a production build drops it.
+* Declares a command: an action the editor lists and runs on the dev page and on a debug page.
+* Its body starts with the guard of its effect: the agent form for `read` and `cosmetic`, the
+* control form for the others (see docs/doors.md), so a production build drops it. A game's
+* `.dev` command with only the `__MOKU_GAME_DEV__` guard runs in dev and is refused on a debug
+* page. `overlay` shows it in the editor's overlay: `"toggle"` with the input `{ on: "boolean" }`
+* and a `value(app)` the switch is drawn from, `"button"` with no required input and no value;
+* any other combination is a type error.
 *
 * @param command - The descriptor.
 * @returns The same descriptor, frozen.
@@ -60,6 +65,29 @@ function defineSource(source) {
 * });
 * (await run(app, openShop)).state.path; // "shop"
 * ```
+* @example
+* ```ts
+* // features/ward/glow.dev.ts — the overlay's "Glow" switch of this game.
+* export const glowSwitch = defineCommand({
+*   id: "ward.glow",
+*   title: "Glow",
+*   input: { on: "boolean" },
+*   effect: "cosmetic",
+*   overlay: "toggle",
+*   value: (app: { readonly effects: Effects.EffectsApi }) =>
+*     !app.effects.diagnostics.disabled().includes("effects.glow"),
+*   run: (app, { on }) => {
+*     if (
+*       (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) &&
+*       (typeof __MOKU_GAME_AGENT__ === "undefined" || !__MOKU_GAME_AGENT__)
+*     ) {
+*       throw controlRefused();
+*     }
+*     return on ? app.effects.diagnostics.enable("effects.glow") : app.effects.diagnostics.disable("effects.glow");
+*   }
+* });
+* // The overlay draws a switch "Glow", on; a tap runs it with { on: false } and the next frame draws no glow.
+* ```
 */
 function defineCommand(command) {
 	checkId("command", command.id);