@moku-labs/game 0.2.0 → 0.3.0

package/dist/{run-tlcn1w7y.mjs → run-BfuMLahc.mjs}

@@ -1,5 +1,5 @@
-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";
+import { f as graphHash, n as isDev, s as sheetAlone, t as controlRefused } from "./dev-CQYJPmcD.mjs";
+import { a as isProjectionTarget, i as recordCheat, o as readTarget, r as isTainted, s as defineCommand, t as inputOrEmpty } from "./input-CK4nxBO1.mjs";
 //#region src/plugins/flow/headless.ts
 const noPayload = null;
 /** Seed of a repro that pins no rng state, the seed `saveOf` writes. */
@@ -219,37 +219,25 @@ const reducedMotionCommand = defineCommand({
 //#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.
+* 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
+* 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.
 */
 /**
-* Tells whether the JSON a command got names a view by its projection key.
+* Reads the cells of a trace out of the JSON a command got.
 *
-* @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`.
+* @param value - The JSON: a list of `{ projection, key }`.
+* @returns The targets in list order, fresh objects.
+* @throws {Error} When the JSON is not a list, or an element is not a projection 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\" }.");
+function readPath(value) {
+	if (Array.isArray(value) && value.every((item) => isProjectionTarget(item))) return value.map((target) => ({
+		projection: target.projection,
+		key: target.key
+	}));
+	throw new Error("[game] The path is not a list of projection keys.\n  Pass views like [{ projection: \"board.cells\", key: \"b3\" }, …].");
 }
 /**
 * Drags one view onto another, both by their projection keys. Answers what `input.drag`
@@ -277,6 +265,28 @@ const dragCommand = defineCommand({
 	}
 });
 /**
+* Traces through views by their projection keys, in list order. Answers what `input.trace`
+* answers: whether the gate took the answer.
+*
+* @example
+* ```ts
+* // Spell the first two letters of a word on the grid.
+* const path = [{ projection: "board.cells", key: "b3" }, { projection: "board.cells", key: "c3" }];
+* (await run(app, commands.trace, { path })).value; // true
+* ```
+*/
+const traceCommand = defineCommand({
+	id: "game.trace",
+	title: "Trace",
+	input: { path: "json" },
+	effect: "route",
+	run: (app, { path }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", { command: "game.trace" });
+		return app.input.trace(readPath(path));
+	}
+});
+/**
 * Presses a key without a keyboard, with or without Shift. Answers whether a listener handled
 * it.
 *
@@ -357,189 +367,6 @@ const resumeCommand = defineCommand({
 	}
 });
 //#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.
@@ -740,6 +567,453 @@ function readRepro(value) {
 	});
 }
 //#endregion
+//#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.
+*/
+/** The input fields of `game.capture`, in the order its `moku:dev` entry lists them. */
+const CAPTURE_FIELDS = [
+	"legend",
+	"layers",
+	"sheet",
+	"diff"
+];
+/** Drawn frames a restored bookmark gets to come to rest at its gate. */
+const REST_FRAMES = 600;
+/** Drawn frames after the rest, so the screen the gate opened is built and drawn. */
+const AFTER_REST_FRAMES = 2;
+/** The length of one frame at 60 fps: the step a paused clock takes per frame, as in `game.step`. */
+const FRAME_MS$1 = 1e3 / 60;
+/**
+* Builds the error of an input field of `game.capture` with the wrong shape.
+*
+* @param field - The field.
+* @param expected - What to pass instead.
+* @returns The error, ready to throw.
+* @example
+* ```ts
+* wrongShape("sheet", "{ frames, everyMs }, two numbers").message;
+* // "[game] game.capture: sheet has the wrong shape.\n  Pass { frames, everyMs }, two numbers."
+* ```
+*/
+function wrongShape(field, expected) {
+	return /* @__PURE__ */ new Error(`[game] game.capture: ${field} has the wrong shape.\n  Pass ${expected}.`);
+}
+/**
+* Reads the `layers` field: a JSON array of strings.
+*
+* @param value - The JSON the editor sent.
+* @returns The layer names.
+* @throws {Error} When it is not an array of strings.
+* @example
+* ```ts
+* readLayers(["board", "hud"]); // ["board", "hud"]
+* ```
+*/
+function readLayers(value) {
+	if (Array.isArray(value) && value.every((name) => typeof name === "string")) return value;
+	throw wrongShape("layers", "an array of layer names, such as [\"board\", \"hud\"]");
+}
+/**
+* Reads the `sheet` field: an object of two numbers, `frames` and `everyMs`. Their range is
+* checked by `renderer.capture()`.
+*
+* @param value - The JSON the editor sent.
+* @returns The sheet.
+* @throws {Error} When it is not an object with two numbers.
+* @example
+* ```ts
+* readSheet({ frames: 6, everyMs: 100 }); // { frames: 6, everyMs: 100 }
+* ```
+*/
+function readSheet(value) {
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+		const { frames, everyMs } = value;
+		if (typeof frames === "number" && typeof everyMs === "number") return {
+			frames,
+			everyMs
+		};
+	}
+	throw wrongShape("sheet", "{ frames, everyMs }, two numbers");
+}
+/**
+* Reads the `diff` field: a bookmark, the value `game.bookmark` answered.
+*
+* @param value - The JSON the editor sent.
+* @returns The bookmark.
+* @throws {Error} When it is not a bookmark.
+*/
+function readDiff(value) {
+	try {
+		return readBookmark(value);
+	} catch {
+		throw wrongShape("diff", "a bookmark, the value of game.bookmark");
+	}
+}
+/**
+* Reads the options `game.capture` passes to `renderer.capture()` as they are: only the fields
+* given.
+*
+* @param input - The input of the command.
+* @returns The options.
+* @throws {Error} When `layers` or `sheet` has the wrong shape.
+*/
+function readOptions(input) {
+	const options = {};
+	if (input.legend !== void 0) options.legend = input.legend;
+	if (input.layers !== void 0) options.layers = readLayers(input.layers);
+	if (input.sheet !== void 0) options.sheet = readSheet(input.sheet);
+	return options;
+}
+/**
+* The input fields given: `legend` when true, the others when present.
+*
+* @param input - The input of the command.
+* @returns Their names.
+* @example
+* ```ts
+* givenFields({ legend: true, diff: { path: "home" } }); // ["legend", "diff"]
+* ```
+*/
+function givenFields(input) {
+	return CAPTURE_FIELDS.filter((field) => field === "legend" ? input.legend === true : input[field] !== void 0);
+}
+/**
+* Tells whether the graph waits at a gate with no effect pending.
+*
+* @param state - The flow state.
+* @returns True at rest.
+* @example
+* ```ts
+* atRest({ running: true, path: "home", stack: [], pending: { gate: ["play"] }, mode: "live" }); // true
+* ```
+*/
+function atRest(state) {
+	return state.pending.gate !== void 0 && state.pending.fx === void 0;
+}
+/**
+* Waits for the next drawn frame: the end of its `render` phase. A paused clock runs no frame, so
+* the frame is stepped here instead, one `time.step(1000 / 60)`, as `game.step` does.
+*
+* @param app - The app whose frames are waited on.
+* @returns Resolves after that frame.
+*/
+function nextFrame(app) {
+	if (app.time.isPaused()) {
+		app.time.step(FRAME_MS$1);
+		return Promise.resolve();
+	}
+	return new Promise((resolve) => {
+		const off = app.time.onFrame("render", () => {
+			off();
+			resolve();
+		});
+	});
+}
+/**
+* Waits on drawn frames until the graph rests at a gate: at most 600.
+*
+* @param app - The app.
+* @returns True once it rests, false when it still does not after 600 drawn frames.
+*/
+async function waitForRest(app) {
+	for (let frame = 0; frame < REST_FRAMES; frame += 1) {
+		if (atRest(app.flow.state())) return true;
+		await nextFrame(app);
+	}
+	return atRest(app.flow.state());
+}
+/**
+* Restores a bookmark and waits until the graph rests at a gate, then two drawn frames more, so
+* the screen of the gate is built and drawn.
+*
+* @param app - The app.
+* @param bookmark - The bookmark to enter.
+* @throws {Error} When the graph does not rest within 600 drawn frames.
+*/
+async function restoreAtRest(app, bookmark) {
+	await app.flow.restore(bookmark);
+	if (!await waitForRest(app)) throw new Error("[game] game.capture diff: the bookmark did not come to rest in 600 frames.\n  Capture a bookmark taken at a gate.");
+	for (let frame = 0; frame < AFTER_REST_FRAMES; frame += 1) await nextFrame(app);
+}
+/**
+* Runs work in the state of a bookmark and comes back to where the game stood, also when the
+* work or the restore fails.
+*
+* @param app - The app.
+* @param bookmark - The bookmark to visit.
+* @param work - What to do there.
+* @returns What the work answered.
+* @throws {Error} When a restore does not come to rest, and whatever the work throws.
+*/
+async function atBookmark(app, bookmark, work) {
+	const before = app.flow.bookmark();
+	try {
+		await restoreAtRest(app, bookmark);
+		return await work();
+	} finally {
+		await restoreAtRest(app, before);
+	}
+}
+/**
+* The diff of `game.capture`: the picture of the bookmark, taken in its state, and the picture of
+* now drawn against it. The command journals itself first, since it replaces the state twice.
+*
+* @param app - The app.
+* @param options - The options passed on: `layers` to both pictures, `legend` to the second.
+* @param diff - The bookmark to compare with.
+* @param raw - The bookmark as the editor sent it, for the journal.
+* @returns The diff picture, or `undefined` while the renderer is inert.
+* @throws {Error} When the graph is not at rest, and when a restore does not come to rest.
+*/
+async function captureDiff(app, options, diff, raw) {
+	if (!app.renderer.host.ready()) return void 0;
+	if (!atRest(app.flow.state())) throw new Error("[game] game.capture diff needs the game at rest.\n  Wait for the gate, then capture.");
+	recordCheat(app, "game.capture", { diff: raw }, app.time.snapshot().frame);
+	const layers = options.layers === void 0 ? {} : { layers: options.layers };
+	const theirs = await atBookmark(app, diff, () => app.renderer.capture(layers));
+	return theirs === void 0 ? void 0 : app.renderer.capture({
+		...options,
+		against: theirs.png
+	});
+}
+/**
+* A picture of the whole canvas taken at the end of the next drawn frame: `{ png }`, and
+* `{ png, legend }` with `legend: true`. `legend`, `layers` and `sheet` go to `renderer.capture()`
+* as they are. `diff`, a bookmark, is the one option the command runs itself: at rest, it journals
+* 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.
+*
+* @example
+* ```ts
+* // The editor attaches the numbered screen to a bug report.
+* (await run(app, commands.capture, { legend: true })).value;
+* // { png: "data:image/png;base64,…", legend: [{ n: 1, projection: "hud", key: "claim", rect: { x: 1140, y: 2310, w: 567, h: 164 } }] }
+* // What changed since the start of the level: red where the pixels differ.
+* (await run(app, commands.capture, { diff: levelStart })).value; // { png: "data:image/png;base64,…" }
+* ```
+*/
+const captureCommand = defineCommand({
+	id: "game.capture",
+	title: "Capture",
+	input: {
+		legend: "boolean?",
+		layers: "json?",
+		sheet: "json?",
+		diff: "json?"
+	},
+	effect: "read",
+	run: (app, input) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		const given = givenFields(input);
+		app.log.debug("moku:dev", given.length === 0 ? { command: "game.capture" } : {
+			command: "game.capture",
+			options: given
+		});
+		const options = readOptions(input);
+		if (input.diff === void 0) return app.renderer.capture(options);
+		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.
+*
+* @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 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.
+*/
+/** 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)}.`);
+}
+/**
+* Refuses a time scale that is not a finite number of zero or more. `setScale` clamps silently;
+* the command refuses, so an editor slider cannot pass `NaN`.
+*
+* @param scale - The time scale.
+* @throws {Error} When it is negative or not finite.
+*/
+function checkScale(scale) {
+	if (Number.isFinite(scale) && scale >= 0) return;
+	throw new Error(`[game] game.timeScale takes a scale of 0 or more.\n  Pass a finite number, not ${String(scale)}.`);
+}
+/**
+* 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();
+	}
+});
+/**
+* Sets the time scale and answers the time after the write. 0 freezes game time while the frames
+* keep running; `game.step` still steps.
+*
+* @example
+* ```ts
+* // The editor slows a merge to a quarter speed to watch the item land.
+* (await run(app, commands.timeScale, { scale: 0.25 })).value.scale; // 0.25
+* ```
+*/
+const timeScaleCommand = defineCommand({
+	id: "game.timeScale",
+	title: "Time scale",
+	input: { scale: "number" },
+	effect: "cosmetic",
+	run: (app, { scale }) => {
+		if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();
+		app.log.debug("moku:dev", {
+			command: "game.timeScale",
+			scale
+		});
+		checkScale(scale);
+		app.time.setScale(scale);
+		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/control.ts
 /**
 * Enters a bookmark, or a repro's bookmark followed by its route.
@@ -896,7 +1170,9 @@ const commands = Object.freeze({
 	capture: captureCommand,
 	debug: debugCommand,
 	reducedMotion: reducedMotionCommand,
-	fill: fillCommand
+	fill: fillCommand,
+	timeScale: timeScaleCommand,
+	trace: traceCommand
 });
 //#endregion
 //#region src/plugins/flow/doors/run.ts