@moku-labs/game 0.13.2 → 0.14.0

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

@@ -1,6 +1,6 @@
-import { a as sheetAlone } from "./capture-fpd83Mi5.mjs";
+import { a as sheetAlone } from "./capture-D7XvoHdH.mjs";
 import { n as isDev, r as notInstalled, t as controlRefused } from "./dev-Cc50Dk7H.mjs";
-import { n as reproBookmark } from "./headless-BsNdJs9W.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";
 //#region src/plugins/anim/control.ts
 /**
@@ -342,8 +342,61 @@ function invalidBookmark() {
 	return /* @__PURE__ */ new Error("[game] The bookmark is not a flow.bookmark() value.\n  Pass the JSON that game.bookmark returned.");
 }
 /**
+* Tells whether a JSON value has the shape of a rest point: an object with a path and an input.
+*
+* @param value - The `rest` field of a bookmark.
+* @returns True when `path` is a string and `input` is there.
+* @example
+* ```ts
+* isRestPoint({ path: "home", input: null }); // true
+* isRestPoint({ path: "home" }); // false: a rest point has an input, `null` when it is empty
+* ```
+*/
+function isRestPoint(value) {
+	return isRecord(value) && typeof value.path === "string" && value.input !== void 0;
+}
+/**
+* Reads the rest point of a bookmark taken at a transit node.
+*
+* @param value - The `rest` field of a bookmark.
+* @returns The rest point, or `undefined` when the value is not one.
+* @example
+* ```ts
+* readRest({ path: "home", input: null }); // { path: "home", input: null }
+* readRest("home"); // undefined
+* ```
+*/
+function readRest(value) {
+	if (!isRestPoint(value)) return void 0;
+	return {
+		path: value.path,
+		input: value.input
+	};
+}
+/**
+* Reads the optional fields of a bookmark onto it: the `scene` the `game.bookmark` door added and
+* the `rest` point of a bookmark taken at a transit node. An absent field leaves no key.
+*
+* @param value - The JSON object of the bookmark.
+* @param bookmark - The bookmark with its required fields.
+* @returns The bookmark with its scene and its rest point.
+* @throws {Error} When the scene or the rest point has the wrong shape.
+*/
+function readBookmarkOptions(value, bookmark) {
+	const { scene, rest } = value;
+	if (scene !== void 0 && typeof scene !== "string") throw invalidBookmark();
+	if (scene !== void 0) bookmark.scene = scene;
+	if (rest !== void 0) {
+		const point = readRest(rest);
+		if (point === void 0) throw invalidBookmark();
+		bookmark.rest = point;
+	}
+	return bookmark;
+}
+/**
 * Reads a bookmark out of JSON, the value `flow.bookmark()` made and the editor kept. The
-* `scene` the `game.bookmark` door added is kept when present.
+* `scene` the `game.bookmark` door added and the `rest` point of a bookmark taken at a transit
+* node are kept when present.
 *
 * @param value - The JSON the editor sent.
 * @returns The bookmark.
@@ -358,25 +411,14 @@ function readBookmark(value) {
 	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();
-	const { scene } = value;
-	if (scene === void 0) return {
+	return readBookmarkOptions(value, {
 		path,
 		input,
 		player,
 		session,
 		rng,
 		graph
-	};
-	if (typeof scene !== "string") throw invalidBookmark();
-	return {
-		path,
-		input,
-		player,
-		session,
-		rng,
-		graph,
-		scene
-	};
+	});
 }
 /**
 * Builds the error of a value that is not a repro.
@@ -577,29 +619,66 @@ function nextFrame(app) {
 	});
 }
 /**
-* Waits on drawn frames until the graph rests at a gate: at most 600.
+* Starts the restore of a bookmark and does not wait for it. Both ways it can end are marked on
+* the entry, so a restore that rejects while a frame is waited on is never left unhandled.
 *
 * @param app - The app.
-* @returns True once it rests, false when it still does not after 600 drawn frames.
+* @param bookmark - The bookmark to enter.
+* @returns The restore in flight.
 */
-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());
+function startRestore(app, bookmark) {
+	const entry = {
+		restore: app.flow.restore(bookmark),
+		state: "pending"
+	};
+	entry.restore.then(() => {
+		entry.state = "entered";
+	}, () => {
+		entry.state = "failed";
+	});
+	return entry;
+}
+/**
+* Tells whether a restore still has frames to wait for: it has not settled, or it resolved and
+* the graph does not rest at a gate yet. A gate counts only after the restore resolved: until
+* then it can be the gate of the node the restore leaves. A failed restore waits for nothing.
+*
+* @param app - The app.
+* @param entry - The restore in flight.
+* @returns True while another frame is needed.
+*/
+function waiting(app, entry) {
+	if (entry.state === "pending") return true;
+	return entry.state === "entered" && !atRest(app.flow.state());
+}
+/**
+* Waits on drawn frames until a restore resolved and the graph rests at a gate, or the restore
+* failed: at most 600.
+*
+* @param app - The app.
+* @param entry - The restore in flight.
+* @returns False when frames are still needed after 600 drawn ones.
+*/
+async function waitForRest(app, entry) {
+	for (let frame = 0; frame < REST_FRAMES && waiting(app, entry); frame += 1) await nextFrame(app);
+	return !waiting(app, entry);
 }
 /**
 * 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.
+* the screen of the gate is built and drawn. The frames run while the restore is in flight: a
+* bookmark of a transit node resolves only at its gate, and on a paused clock no frame but the
+* ones stepped here brings its node there.
 *
 * @param app - The app.
 * @param bookmark - The bookmark to enter.
-* @throws {Error} When the graph does not rest within 600 drawn frames.
+* @throws {Error} When the graph does not rest within 600 drawn frames, and whatever the restore
+*   rejects with.
 */
 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.");
+	const entry = startRestore(app, bookmark);
+	const rested = await waitForRest(app, entry);
+	if (entry.state !== "pending") await entry.restore;
+	if (!rested) 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);
 }
 /**
@@ -880,8 +959,29 @@ const fillCommand = defineCommand({
 //#endregion
 //#region src/plugins/flow/control.ts
 /**
+* 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
+* node switches to the scene of a bookmark that was never entered. With nothing mounted the
+* record stays, as the scenes API has no way to clear it.
+*
+* @param app - The app; with `scenes`, the bookmark's scene is expected before the restore.
+* @param bookmark - The bookmark to enter.
+* @throws {Error} What `flow.restore` refused the bookmark with, unchanged.
+*/
+async function restoreWithScene(app, bookmark) {
+	const mounted = app.scenes?.current();
+	if (bookmark.scene !== void 0) app.scenes?.expect(bookmark.scene);
+	try {
+		await app.flow.restore(bookmark);
+	} catch (error) {
+		if (mounted !== void 0) app.scenes?.expect(mounted);
+		throw error;
+	}
+}
+/**
 * Enters a bookmark, or a repro's bookmark followed by its route. A bookmark's `scene` is handed
-* to `scenes.expect` first, so a rest node without a scene of its own mounts it.
+* to `scenes.expect` first, so a node without a scene of its own mounts it: a rest node, or the
+* transit node of a bookmark taken while an effect that takes answers waited.
 *
 * @param app - The app; with `scenes`, the bookmark's scene is expected before the restore.
 * @param input - Exactly one of a bookmark and a repro, as JSON.
@@ -892,13 +992,13 @@ const fillCommand = defineCommand({
 */
 async function restoreFrom(app, input) {
 	const { bookmark, repro } = input;
-	if (bookmark !== void 0 && repro === void 0) {
-		const read = readBookmark(bookmark);
-		if (read.scene !== void 0) app.scenes?.expect(read.scene);
-		await app.flow.restore(read);
+	const bookmarkOnly = bookmark !== void 0 && repro === void 0;
+	const reproOnly = repro !== void 0 && bookmark === void 0;
+	if (bookmarkOnly) {
+		await restoreWithScene(app, readBookmark(bookmark));
 		return app.flow.state();
 	}
-	if (repro !== void 0 && bookmark === void 0) {
+	if (reproOnly) {
 		const parsed = readRepro(repro);
 		await app.flow.restore(reproBookmark(app, parsed));
 		return app.flow.walk(parsed.route);
@@ -959,15 +1059,19 @@ const walkCommand = defineCommand({
 	}
 });
 /**
-* Takes a bookmark of the rest point: the node plus the committed state, plain JSON. An app with
-* the screen plugins adds the mounted `scene`, so a restore in a fresh page builds it again.
+* Takes a bookmark of where the graph stands: the node plus the committed state, plain JSON. The
+* node is the last rest node, or, while a transit node waits for an effect that takes answers (a
+* `popup`, or a hand-written descriptor with `answers`), that node; `rest` then names the rest
+* point before it. An app with the screen plugins adds the mounted `scene`, so a restore in a
+* fresh page builds it again.
 *
 * @example
 * ```ts
-* // The editor keeps the position while the Settings popup stands over Home.
+* // The editor keeps the position while the info popup of the mini game is open over Home.
 * const { value } = await run(app, commands.bookmark);
-* value.path; // "settings/open"
+* value.path; // "info/show": the node that waits for the popup's answer
 * value.scene; // "home"
+* value.rest; // { path: "home", input: null }
 * ```
 */
 const bookmarkCommand = defineCommand({
@@ -990,6 +1094,10 @@ const bookmarkCommand = defineCommand({
 * 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. A bookmark's
 * `scene` goes to `scenes.expect` first: a bookmark at a popup comes back with the scene under it.
+* A bookmark taken while a transit node waited for an effect that takes answers (a `popup`, or a
+* hand-written descriptor with `answers`) runs that node again, and the command answers once its
+* gate is open: the state it returns already lists the answers. The popup is drawn on the next
+* frame. A repro starts at a rest node only.
 *
 * @example
 * ```ts
@@ -998,11 +1106,11 @@ const bookmarkCommand = defineCommand({
 * const ran = await run(app, commands.restore, { repro });
 * ran.state; // { path: "board/awaitIntent", frame: 12, tainted: true }
 *
-* // A fresh page restores the bookmark game.bookmark took at the Settings popup over Home.
-* bookmark.scene; // "home"
-* await run(app, commands.restore, { bookmark });
-* await app.flow.walk([]); // the scene stage runs after the restore resolved
-* app.scenes.current(); // "home"
+* // A fresh page restores the bookmark game.bookmark took at the info popup of the mini game.
+* const { value } = await run(app, commands.restore, { bookmark });
+* value.path; // "info/show"
+* value.pending.gate; // ["ok", "close"]: the popup waits for its answer again
+* app.scenes.current(); // "home": the scene the bookmark named, under the popup
 * ```
 */
 const restoreCommand = defineCommand({

package/dist/{runtime-6qakboTm.d.mts → runtime-CWY6co6m.d.mts}

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