@moku-labs/game 0.14.0 → 0.14.2

package/dist/{src-Dgmdzl8R.mjs → src-BD-MZliM.mjs}

@@ -1327,7 +1327,7 @@ function createFeaturesApi(ctx) {
 * asError("no audio device").message; // "no audio device"
 * ```
 */
-function asError$4(error) {
+function asError$5(error) {
 	return error instanceof Error ? error : new Error(String(error));
 }
 /**
@@ -1339,7 +1339,7 @@ function asError$4(error) {
 * @param error - What the handler threw or rejected with.
 */
 function reportFailure(log, kind, error) {
-	log.error("flow:fx-handler-failed", { kind }, asError$4(error));
+	log.error("flow:fx-handler-failed", { kind }, asError$5(error));
 }
 /**
 * Hands one released hint to every `onHint` listener, in registration order. A listener lives
@@ -1355,7 +1355,7 @@ function notifyHint(state, log, item) {
 	for (const listener of listeners) try {
 		listener(item);
 	} catch (error) {
-		log.error("flow:hint-listener-failed", { kind: item.kind }, asError$4(error));
+		log.error("flow:hint-listener-failed", { kind: item.kind }, asError$5(error));
 	}
 }
 /**
@@ -1708,9 +1708,10 @@ function deliver(state, answer) {
 	resolve?.(answer);
 }
 /**
-* Keeps an answer that arrived at a closed gate for one frame. Nothing is held in fast mode or
-* while time is not running: there is no frame that could re-offer it. The first answer wins, a
-* second one in the same frame is dropped.
+* Keeps an answer that arrived at a closed gate, with the frame and the game time of the refusal.
+* Nothing is held in fast mode or while time is not running: there is no frame that could age it.
+* Without a hold time (`holdMs` 0 or less) the first answer wins and a second one is dropped. With
+* one, every refused answer replaces the held one: the last press is the one the player means.
 *
 * @param ctx - Domain context of the flow plugin.
 * @param answer - The answer the closed gate refused.
@@ -1718,15 +1719,18 @@ function deliver(state, answer) {
 function hold(ctx, answer) {
 	if (ctx.state.fx.mode === "fast") return;
 	if (!ctx.deps.time.isRunning()) return;
-	if (ctx.state.gate.held !== void 0) return;
+	if (ctx.config.holdMs <= 0 && ctx.state.gate.held !== void 0) return;
+	const { frame, elapsed } = ctx.deps.time.snapshot();
 	ctx.state.gate.held = {
 		answer,
-		frame: ctx.deps.time.snapshot().frame
+		frame,
+		at: elapsed
 	};
 }
 /**
 * Offers the held answer to the gate that has just opened. It is offered once: an answer the new
-* gate does not accept is dropped, not kept for the next one.
+* gate does not accept is dropped, not kept for the next one. A gate that opens in fast mode gets
+* no offer: a fast walk answers its own gates, and a press of the live play before it is dropped.
 *
 * @param ctx - Domain context of the flow plugin.
 */
@@ -1734,13 +1738,15 @@ function offerHeld(ctx) {
 	const held = ctx.state.gate.held;
 	if (held === void 0) return;
 	ctx.state.gate.held = void 0;
+	if (ctx.state.fx.mode === "fast") return;
 	if (!accepts(ctx.state.gate, held.answer)) return;
 	deliver(ctx.state.gate, held.answer);
 }
 /**
 * Creates the gate API: the single entry of player answers. The gate closes before the answer is
-* handed on; an answer to a closed gate is held for one frame, first wins; `narrow` lets one
-* answer through; `pointer(true)` delays entering an `over` node.
+* handed on; an answer to a closed gate is held for the next gate, for one frame or for
+* `config.holdMs` of game time; `narrow` lets one answer through; `pointer(true)` delays entering
+* an `over` node.
 *
 * @param ctx - Domain context of the flow plugin.
 * @returns The public gate API plus the methods injected into `runner` and `fx`.
@@ -1778,9 +1784,14 @@ function createGateApi(ctx) {
 		narrow: (allow) => {
 			ctx.state.gate.narrow = allow;
 		},
-		clearHeld: (frame) => {
-			if (ctx.state.gate.held === void 0) return;
-			if (ctx.state.gate.held.frame === frame) return;
+		clearHeld: (frame, elapsed) => {
+			const held = ctx.state.gate.held;
+			if (held === void 0) return;
+			if (held.frame === frame) return;
+			if (ctx.config.holdMs > 0 && elapsed - held.at <= ctx.config.holdMs) return;
+			ctx.state.gate.held = void 0;
+		},
+		dropHeld: () => {
 			ctx.state.gate.held = void 0;
 		}
 	};
@@ -1908,10 +1919,11 @@ function registerSchedule(ctx, fx) {
 }
 /**
 * Connects flow to its dependencies in `onInit`: posts `elapsed` from `clock.onElapsed` into the
-* inbox, flushes effect completions and the gate hold in `time.onFrame("signals")`, and registers
-* the `schedule` handler. `onInit` has no access to the plugin's own API, so it builds its own
-* module objects — they are pure functions over `ctx.state`, which is the one place the modules
-* keep their data, so these objects and the API's objects are the same gate and the same fx.
+* inbox, flushes effect completions and ages the gate hold in `time.onFrame("signals")`, with the
+* frame and the elapsed game time of that frame, and registers the `schedule` handler. `onInit`
+* has no access to the plugin's own API, so it builds its own module objects — they are pure
+* functions over `ctx.state`, which is the one place the modules keep their data, so these
+* objects and the API's objects are the same gate and the same fx.
 *
 * @param ctx - Kernel context of the flow plugin.
 */
@@ -1926,9 +1938,9 @@ function connectFlow(ctx) {
 			payload: input
 		});
 	});
-	flowCtx.deps.time.onFrame("signals", ({ frame }) => {
+	flowCtx.deps.time.onFrame("signals", ({ frame, elapsed }) => {
 		fx.flushSettled();
-		gate.clearHeld(frame);
+		gate.clearHeld(frame, elapsed);
 	});
 	registerSchedule(flowCtx, fx);
 }
@@ -2086,6 +2098,25 @@ function nodeProblems(flow) {
 	return problems;
 }
 /**
+* Reports a `recover` on a node that does not rest. The recovery makes its node the rest point
+* of the loop, so only a rest node can carry one.
+*
+* @param flow - The flow being validated.
+* @returns One sentence per problem.
+* @example
+* ```ts
+* recoverProblems(boardFlow); // []: no transit node of the board has a recover
+* ```
+*/
+function recoverProblems(flow) {
+	const problems = [];
+	for (const [name, entry] of Object.entries(flow.nodes)) {
+		if (entry.kind !== "node" || entry.recover === void 0 || entry.rest) continue;
+		problems.push(`[game] Flow "${flow.id}": node "${name}" has recover but is not a rest node.\n  Add rest: true, or remove recover.`);
+	}
+	return problems;
+}
+/**
 * Reports a start node that is not in `nodes`, and every node the start cannot reach.
 *
 * @param flow - The flow being validated.
@@ -2286,6 +2317,32 @@ function safeNodeProblems(config, features) {
 	return [`[game] The safe node "${safeNode}" is not a checkpoint.\n  Mark it checkpoint: true or choose another rest node.`];
 }
 /**
+* Warns about a `recover` on a node that is not the safe node. The runner calls `recover` only in
+* the safe node, after it gave up on a transition, so the hook never runs anywhere else. The safe
+* node is the configured one, or the start of the main flow. Nothing is warned about while that
+* path names no node: a wrong `safeNode` is a problem of its own, and behind a start that is a
+* sub-flow or a slot the node the loop enters is not known before the game runs.
+*
+* @param flows - Every collected flow by id.
+* @param features - Features API, read for a safe node inside a slot contribution.
+* @param config - Resolved flow config: `mainFlow`, `safeNode`.
+* @returns One warning per node whose `recover` never runs.
+*/
+function recoverWarnings(flows, features, config) {
+	const { mainFlow } = config;
+	if (!mainFlow) return [];
+	const safePath = config.safeNode ?? mainFlow.start;
+	const safe = findNode(mainFlow, safePath, features.contributions);
+	if (safe?.entry.kind !== "node") return [];
+	const warnings = [];
+	for (const flow of flows.values()) for (const [name, entry] of Object.entries(flow.nodes)) {
+		if (entry.kind !== "node" || entry.recover === void 0) continue;
+		if (safe.flow.id === flow.id && safe.name === name) continue;
+		warnings.push(`[game] Flow "${flow.id}": node "${name}" has recover but is not the safe node.\n  The engine runs recover only in the safe node "${safePath}". Move recover there or remove it.`);
+	}
+	return warnings;
+}
+/**
 * Warns when two contributions of one slot have a node with the same name. A bookmark path keeps
 * node names only, so `restore` cannot tell the two apart and enters the first one in order.
 *
@@ -2326,9 +2383,11 @@ function sizeWarnings(flow) {
 * unreachable node, outcome without an edge, missing target, barrier edge that does not reach a
 * rest node of the same flow, cycle with no rest node, slot without a name, equal contribution
 * `order`, one flow contributed twice to a slot, `inbox` type that is not an outcome, rest node
-* with neither `run` nor outcomes, a scene id no feature registers, an `over` node that names a
-* scene, `safeNode` that is not a checkpoint, colliding ids. Types are bypassed by JSON data and
-* casts, so this runs even though the edge table is checked at compile time.
+* with neither `run` nor outcomes, a `recover` on a node that is not a rest node, a scene id no
+* feature registers, an `over` node that names a scene, `safeNode` that is not a checkpoint,
+* colliding ids. A `recover` on a node that is not the safe node is a warning: it never runs
+* there. Types are bypassed by JSON data and casts, so this runs even though the edge table is
+* checked at compile time.
 *
 * @param flows - Every collected flow by id, the main flow first.
 * @param features - Features API: slot contributions and feature names.
@@ -2339,10 +2398,10 @@ function validateGraph(flows, features, config) {
 	const problems = [];
 	const warnings = [];
 	for (const flow of flows.values()) {
-		problems.push(...edgeProblems(flow), ...nodeProblems(flow), ...reachProblems(flow), ...cycleProblems(flow));
+		problems.push(...edgeProblems(flow), ...nodeProblems(flow), ...recoverProblems(flow), ...reachProblems(flow), ...cycleProblems(flow));
 		warnings.push(...sizeWarnings(flow));
 	}
-	warnings.push(...slotNameWarnings(flows, features));
+	warnings.push(...slotNameWarnings(flows, features), ...recoverWarnings(flows, features, config));
 	problems.push(...flowIdProblems(flows), ...featureProblems(flows, features), ...sceneProblems(flows, features), ...safeNodeProblems(config, features));
 	return {
 		problems,
@@ -2882,8 +2941,22 @@ function continueSlot(frames, finished) {
 //#endregion
 //#region src/plugins/flow/runner/edge.ts
 /**
+* Turns whatever a node failed with into an error the log takes.
+*
+* @param value - The thrown value or the rejection reason.
+* @returns The value itself when it is an error, a new error with its text otherwise.
+* @example
+* ```ts
+* asError("no save").message; // "no save"
+* ```
+*/
+function asError$4(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
+/**
 * Commits the transaction of one node, releases its hints, journals the edge and emits
-* `flow:edge`. This is the only commit of the engine.
+* `flow:edge`. This is the only commit of the engine: the edge of a node, and the recovery edge
+* of the safe node, both go through it.
 *
 * @param ctx - Domain context of the flow plugin.
 * @param modules - Injected sibling APIs.
@@ -2916,7 +2989,11 @@ function commitEdge(ctx, modules, step, next) {
 }
 /**
 * Discards everything the failed node did, rolls back and decides between a retry and the safe
-* node. A failure while the loop already recovers in the safe node is fatal.
+* node. Every failure is written to the log as one error entry `flow:error`, right before the
+* event of the same name. When the loop gives up it stands on the safe node, whose `recover` is
+* then still to run, and an answer the gate still held is dropped; a retry keeps it. A failure
+* while the loop already recovers in the safe node is fatal: it is no event and no log entry, it
+* rejects `run()`.
 *
 * @param ctx - Domain context of the flow plugin.
 * @param modules - Injected sibling APIs.
@@ -2938,17 +3015,25 @@ function handleFailure(ctx, modules, transaction, error, path, safe) {
 	const retry = state.failures <= ctx.config.retries;
 	const safeTarget = () => safeFrames(ctx, modules.features.contributions);
 	const target = retry ? state.restFrame ?? safeTarget() : safeTarget();
+	const rolledBackTo = framePath(target);
+	ctx.log.error("flow:error", {
+		path,
+		rolledBackTo,
+		retry
+	}, asError$4(error));
 	ctx.emit("flow:error", {
 		path,
 		error,
-		rolledBackTo: framePath(target),
+		rolledBackTo,
 		retry
 	});
 	state.stack = [...target];
 	state.slotAfter = void 0;
 	if (!retry) {
 		safe.inside = true;
+		safe.recover = true;
 		state.failures = 0;
+		modules.gate.dropHeld();
 	}
 	return "continue";
 }
@@ -3057,7 +3142,9 @@ function type() {
 }
 /**
 * Defines a node. `out` of the body has one method per declared outcome; `run` is required
-* unless `rest: true`. `Game` is bound by `defineGame<Types>()`; here it is the engine's `Json`.
+* unless `rest: true`. A rest node may carry `recover`: the engine runs it before the node is
+* entered as the safe node. `Game` is bound by `defineGame<Types>()`; here it is the engine's
+* `Json`.
 *
 * @param spec - Input tag, outcomes, flags, inbox and the body.
 * @returns The node as plain data.
@@ -3084,7 +3171,8 @@ function defineNode(spec) {
 		checkpoint: spec.checkpoint === true,
 		barrier: spec.barrier === true,
 		inbox: spec.inbox ?? [],
-		...spec.scene === void 0 ? {} : { scene: spec.scene }
+		...spec.scene === void 0 ? {} : { scene: spec.scene },
+		...spec.recover === void 0 ? {} : { recover: spec.recover }
 	};
 	return spec.run ? {
 		...node,
@@ -3255,10 +3343,11 @@ function refuseEffect(signal) {
 * Builds the `fx` of a node context: awaited effects by call, cosmetic hints by `emit`. A `guide`
 * narrows the gate while it runs; the runner lifts the narrow when the node is left. A body that
 * was aborted keeps running, since the loop only stops waiting for it, so its `fx` starts nothing
-* any more: the gate and the narrow belong to the node the loop entered after it.
+* any more: the gate and the narrow belong to the node the loop entered after it. The `recover`
+* of a rest node gets the same `fx`, bound to the signal of its recovery.
 *
 * @param modules - Injected sibling APIs.
-* @param step - The node run in progress.
+* @param step - The run in progress: its abort signal, and how it tells a walk that a gate opened.
 * @returns The effects gateway of one node run.
 */
 function nodeFx(modules, step) {
@@ -3379,6 +3468,7 @@ function stopped(state) {
 }
 /**
 * Resolves as soon as the node is aborted, so a body that ignores its signal never holds the loop.
+* A recovery races its `recover` against the same promise.
 *
 * @param signal - The node's abort signal.
 * @returns The abort outcome.
@@ -3583,6 +3673,136 @@ function waitForPointer(ctx) {
 	});
 }
 //#endregion
+//#region src/plugins/flow/runner/recover.ts
+/**
+* Takes the recovery the loop owes the safe node. It is owed once per give-up, to the first node
+* entered after it, and a node without `recover` uses it up as well.
+*
+* @param safe - How the loop stands after it gave up.
+* @param node - The node being entered.
+* @returns True when the node has a `recover` that must run now.
+*/
+function takeRecovery(safe, node) {
+	if (!safe.recover) return false;
+	safe.recover = false;
+	return node.recover !== void 0;
+}
+/**
+* Builds the one object a `recover` receives: the node context without `input` and `out`.
+*
+* @param modules - Injected sibling APIs.
+* @param recovery - The recovery in progress.
+* @returns The recovery context.
+*/
+function recoverContext(modules, recovery) {
+	return {
+		player: recovery.transaction.player,
+		session: recovery.transaction.session,
+		rng: recovery.transaction.rng,
+		fx: nodeFx(modules, recovery),
+		signal: recovery.signal,
+		now: recovery.now
+	};
+}
+/**
+* Calls the `recover` of a node and turns what it does into an outcome. Nothing is thrown out of
+* here.
+*
+* @param modules - Injected sibling APIs.
+* @param recovery - The recovery in progress.
+* @returns That it returned, the abort or the failure.
+*/
+async function callRecover(modules, recovery) {
+	try {
+		await recovery.node.recover?.(recoverContext(modules, recovery));
+		if (recovery.signal.aborted) return {
+			kind: "aborted",
+			reason: abortReason(recovery.signal)
+		};
+		return { kind: "recovered" };
+	} catch (error) {
+		if (recovery.signal.aborted) return {
+			kind: "aborted",
+			reason: abortReason(recovery.signal)
+		};
+		return {
+			kind: "failed",
+			error
+		};
+	}
+}
+/**
+* Takes the recovery edge: what `recover` wrote is committed as an edge of the safe node onto
+* itself, with the outcome `"recover"`, and the node becomes the rest point. The journal entry,
+* `flow:edge`, the rest mark of the store and `flow:rest` are the ones of any edge into a rest
+* node, so a later rollback returns to the recovered state.
+*
+* @param ctx - Domain context of the flow plugin.
+* @param modules - Injected sibling APIs.
+* @param recovery - The recovery whose `recover` returned.
+*/
+function commitRecovery(ctx, modules, recovery) {
+	commitEdge(ctx, modules, {
+		location: recovery.location,
+		transaction: recovery.transaction,
+		result: {
+			outcome: "recover",
+			payload: null
+		},
+		barrier: false,
+		now: recovery.now,
+		path: recovery.path
+	}, recovery.path);
+	ctx.deps.model.store.markRest();
+	arrive(ctx, {
+		stack: [...ctx.state.runner.stack],
+		next: recovery.path,
+		rest: true,
+		checkpoint: recovery.node.checkpoint
+	});
+}
+/**
+* Runs the `recover` of the safe node as one transaction, before the node is entered: an abort
+* controller of its own, an open transaction, `recover` raced against the abort, then the
+* recovery edge. A `recover` that fails is a failure inside the safe node: fatal, `run()` rejects.
+* An aborted one leaves like an aborted node: `"stop"` ends the loop, `"restore"` lets the next
+* turn enter the bookmark. `safe.inside` is not touched: it stays true until the safe node's own
+* edge commits or a restore leaves the node, so a failure of the safe node after its recovery is
+* still fatal, never a loop.
+*
+* @param ctx - Domain context of the flow plugin.
+* @param modules - Injected sibling APIs.
+* @param place - The safe node the loop stands on.
+* @param safe - How the loop stands after it gave up.
+* @returns The outcome that ends this turn, or `undefined` when the node is entered now.
+* @throws {Error} When `recover` failed.
+*/
+async function recoverNode(ctx, modules, place, safe) {
+	const state = ctx.state.runner;
+	const abort = new AbortController();
+	state.abort = abort;
+	const recovery = {
+		...place,
+		transaction: ctx.deps.model.store.begin(),
+		signal: abort.signal,
+		now: ctx.deps.clock.now(),
+		/**
+		* Tells a walk that the recovery opened the gate for an answer.
+		*/
+		gateOpened: () => {
+			notifyGateOpen(state);
+		}
+	};
+	const outcome = await Promise.race([callRecover(modules, recovery), abortOutcome(abort.signal)]);
+	modules.gate.narrow(void 0);
+	modules.fx.endGuides();
+	if (outcome.kind === "failed") return handleFailure(ctx, modules, recovery.transaction, outcome.error, place.path, safe);
+	if (outcome.kind === "aborted") return handleAbort(modules, recovery.transaction, outcome.reason);
+	commitRecovery(ctx, modules, recovery);
+	if (stopped(state)) return "stop";
+	if (state.seam?.restoring !== void 0) return "continue";
+}
+//#endregion
 //#region src/plugins/flow/runner/stop.ts
 /**
 * Waits `timeoutMs` of real time. The deadline is not counted in frames: a paused clock runs no
@@ -3629,8 +3849,9 @@ async function settle$1(ctx, running) {
 }
 /**
 * Stops the runner: the active node is aborted with reason `"stop"`, the loop is given
-* `settleTimeoutMs` to settle, and a background flush that is still running is awaited. The loop
-* itself discards the open transaction and shuts the gate while it leaves the aborted node.
+* `settleTimeoutMs` to settle, an answer the gate still held is dropped, and a background flush
+* that is still running is awaited. The loop itself discards the open transaction and shuts the
+* gate while it leaves the aborted node.
 *
 * @param ctx - Config and state of the flow plugin.
 * @returns A promise that resolves when the graph stands still.
@@ -3648,6 +3869,7 @@ async function stopRunner(ctx) {
 	}
 	const settled = running === void 0 || await settle$1(ctx, running);
 	state.running = void 0;
+	ctx.state.gate.held = void 0;
 	if (settled) state.abort = void 0;
 	const flushing = state.flushing;
 	if (flushing !== void 0) {
@@ -3658,8 +3880,8 @@ async function stopRunner(ctx) {
 //#endregion
 //#region src/plugins/flow/runner/loop.ts
 /**
-* Runs one node: wait for the pointer, `onEnter` stages, open the transaction, produce the
-* outcome, then commit on the edge or recover.
+* Runs one node: wait for the pointer, the recovery the loop owes the safe node, `onEnter` stages,
+* open the transaction, produce the outcome, then commit on the edge or recover.
 *
 * @param ctx - Domain context of the flow plugin.
 * @param modules - Injected sibling APIs.
@@ -3674,6 +3896,14 @@ async function runNode(ctx, modules, location, node, safe) {
 	if (node.over) await waitForPointer(ctx);
 	if (stopped(state)) return "stop";
 	if (state.seam?.restoring !== void 0) return "continue";
+	if (takeRecovery(safe, node)) {
+		const ended = await recoverNode(ctx, modules, {
+			location,
+			node,
+			path
+		}, safe);
+		if (ended !== void 0) return ended;
+	}
 	const abort = new AbortController();
 	state.abort = abort;
 	const now = ctx.deps.clock.now();
@@ -3784,18 +4014,25 @@ function enterSlot(ctx, modules, location, slot, safe) {
 * node too. A restore leaves the whole document waiting for the provider, and a rollback of the
 * node would drop it unsent; and the frames of the transit node are what a failure of it must
 * retry, since the restored state belongs to them. `flow:rest` and the rest seam fire once for
-* every node entered here; only a rest node is announced as a checkpoint.
+* every node entered here; only a rest node is announced as a checkpoint. A restore wins over
+* what belonged to the old position: a recovery the loop still owed the safe node does not run on
+* the restored state, the loop is no longer inside the safe node, so a failure of the restored
+* node is retried and not fatal, and an answer the gate still held is dropped.
 *
 * @param ctx - Domain context of the flow plugin.
 * @param modules - Injected sibling APIs; the features API resolves a path through a slot.
 * @param bookmark - The bookmark to enter.
+* @param safe - How the loop stands after it gave up. Both of its flags are cleared.
 * @throws {Error} When the graph has no node at the bookmark's path.
 */
-function enterBookmark(ctx, modules, bookmark) {
+function enterBookmark(ctx, modules, bookmark, safe) {
 	const state = ctx.state.runner;
 	const location = findNode(requireMainFlow(ctx), bookmark.path, modules.features.contributions);
 	loopSeam(state).restoring = void 0;
 	if (location === void 0) throw new Error(`[game] The bookmark names no node "${bookmark.path}".\n  Bookmark a node of the running graph.`);
+	safe.inside = false;
+	safe.recover = false;
+	modules.gate.dropHeld();
 	ctx.deps.model.store.restore({
 		player: bookmark.player,
 		session: bookmark.session,
@@ -3826,7 +4063,7 @@ async function advance(ctx, modules, safe) {
 	if (stopped(state)) return "stop";
 	const restoring = state.seam?.restoring;
 	if (restoring !== void 0) {
-		enterBookmark(ctx, modules, restoring);
+		enterBookmark(ctx, modules, restoring, safe);
 		return "continue";
 	}
 	const location = locateFrames(ctx, state.stack);
@@ -3838,7 +4075,8 @@ async function advance(ctx, modules, safe) {
 /**
 * Runs the graph until aborted: enter node, `onEnter` stages, begin a transaction, await the
 * body, commit on the edge, release hints, journal, emit `flow:edge`, follow the edge. An error
-* discards, rolls back and retries, then enters `safeNode`; a failure inside `safeNode` rejects.
+* discards, rolls back, is logged and retries, then enters `safeNode`, whose `recover` runs first
+* as one committed edge; a failure inside `safeNode` rejects.
 * Abort reasons: `"stop"` ends the loop, `"inbox"` turns the event into the outcome, `"restore"`
 * enters the bookmark's frame.
 *
@@ -3862,7 +4100,10 @@ async function runLoop(ctx, modules) {
 	state.restFrame = [...state.stack];
 	state.slotAfter = void 0;
 	state.failures = 0;
-	const safe = { inside: false };
+	const safe = {
+		inside: false,
+		recover: false
+	};
 	const loop = { running: true };
 	while (loop.running) loop.running = await advance(ctx, modules, safe) === "continue";
 }
@@ -4518,8 +4759,8 @@ function createModules$3(ctx) {
 	};
 }
 /**
-* Reduces the gate to what a game may call. `open`, `close`, `narrow` and `clearHeld` belong to
-* the runner and to `fx`.
+* Reduces the gate to what a game may call. `open`, `close`, `narrow`, `clearHeld` and `dropHeld`
+* belong to the runner, to `fx` and to the plugin root.
 *
 * @param gate - The full gate module.
 * @returns The public gate API.
@@ -4809,7 +5050,8 @@ const flowPlugin = /*#__PURE__*/ createPlugin$1("flow", {
 		safeNode: void 0,
 		retries: 1,
 		settleTimeoutMs: 2e3,
-		journalLimit: 500
+		journalLimit: 500,
+		holdMs: 0
 	},
 	events: (register) => register.map({
 		"flow:edge": "An edge was taken and its state committed",
@@ -18210,8 +18452,9 @@ async function bufferOf(ctx, key) {
 /**
 * Plays one sound: the handler of the kind `"sfx"`. Every play is its own source, so the same key
 * twice in one frame is heard twice, and the promise resolves when the sound STARTED. The handler
-* ignores its signal: a sound that began plays to its end. While the first gesture's `resume()` is
-* pending the sound waits in `pendingSfx`, one per key; before any gesture it is dropped.
+* ignores its signal: a sound that began plays to its end. While a gesture's `resume()` is
+* pending the sound waits in `pendingSfx`, one per key. A locked context no gesture is resuming
+* drops it: the start attempt of the unlock queues nothing.
 *
 * @param ctx - Domain context of the plugin.
 * @param descriptor - The `sfx` descriptor `anim` built.
@@ -18411,7 +18654,7 @@ function refused(ctx, key) {
 /**
 * Switches the music: the handler of the kind `"music"` and what `scenes:changed` calls. The same
 * key does nothing, a new key cross-fades, `null` fades out. While the context is locked the key
-* is only remembered; the first touch starts it. A key that is still on its way counts as the
+* is only remembered; the unlock starts it. A key that is still on its way counts as the
 * same key, and every other request replaces it: the replaced switch starts nothing when its
 * buffer or its element is ready, so one tap that unlocks the context and enters a scene with the
 * same track starts it once. `config.music` picks the decode or the stream path.
@@ -18569,17 +18812,22 @@ function resetSession(state) {
 //#endregion
 //#region src/plugins/audio/unlock.ts
 /**
-* @file audio plugin — the unlock: the only file that touches `window`. A browser starts every
-* audio context suspended and resumes it on a user gesture, so two listeners wait for the first
-* one. They sit on `window`, not on the canvas: the gesture may as well be a button of the
-* game's loading page, which `input` never sees.
+* @file audio plugin — the unlock: the only file that touches `window`. A browser starts an audio
+* context suspended and lets it run on a user gesture, so two listeners wait for the first one.
+* They sit on `window`, not on the canvas: the gesture may as well be a button of the game's
+* loading page, which `input` never sees. A shell that asks for no gesture, such as a native
+* webview with the requirement switched off, lets the context run at once. So the plugin also
+* asks once at start, and unlocks with no touch where the answer is yes.
 */
 /** The two gestures that unlock a context. The first of them to arrive wins. */
 const UNLOCK_EVENTS = ["pointerdown", "touchend"];
 /**
-* Reacts to a resume that went through. The context is unlocked only when it really runs; the
-* sounds fired during the resume and the track a scene declared while it was locked start here. A
-* context that still does not run drops the sounds: the next gesture is a new moment.
+* Reacts to a resume that went through, of a gesture or of the start attempt. The context is
+* unlocked only when it really runs; the sounds fired during the resume and the track a scene
+* declared while it was locked start here. A context that still does not run drops the sounds:
+* the next gesture is a new moment. A gesture and the start attempt that settle together both
+* come here, and the music still starts once: a track that is on its way or already plays is not
+* started again. A later gesture on an unlocked context tries a remembered track again.
 *
 * @param ctx - Domain context of the plugin.
 */
@@ -18632,8 +18880,50 @@ function resumeContext(ctx) {
 	});
 }
 /**
-* Installs the two unlock listeners on `window`. Without a DOM there is nothing to listen on and
-* the context stays locked for the whole run, which is what a headless game wants.
+* Reacts to the start attempt that fulfilled. Nothing happens when the app stopped meanwhile, when
+* a gesture already unlocked the context, or when the context still does not run: the listeners
+* are there for that. Otherwise the listeners go and the context is unlocked the way a gesture
+* unlocks it.
+*
+* @param ctx - Domain context of the plugin.
+* @param context - The context the attempt was made on.
+*/
+function onStartResumed(ctx, context) {
+	const state = ctx.state;
+	if (state.context !== context || state.unlocked || context.state !== "running") return;
+	removeUnlock(state);
+	onResumed(ctx);
+}
+/**
+* Leaves a refused start attempt alone. Nobody asked for sound yet, so there is nothing to report,
+* and the listeners are installed: the first gesture asks again.
+*/
+function ignoreRefusal() {}
+/**
+* Unlocks the context in `onStart` where the shell lets audio play, and waits for a gesture where
+* it does not. A context that already runs is unlocked at once, with no listener. Any other gets
+* the two listeners and one `resume()`. `resuming` is not set for it: a browser that wants a
+* gesture leaves that promise pending, and a sound must not queue behind a promise that may never
+* settle. The attempt needs no `window`, so it also serves a context given through
+* `config.context` in a runtime without a DOM.
+*
+* @param ctx - Domain context of the plugin.
+*/
+function startUnlock(ctx) {
+	const context = ctx.state.context;
+	if (context === void 0) return;
+	if (context.state === "running") {
+		onResumed(ctx);
+		return;
+	}
+	installUnlock(ctx);
+	context.resume().then(() => {
+		onStartResumed(ctx, context);
+	}, ignoreRefusal);
+}
+/**
+* Installs the two unlock listeners on `window`. Without a DOM there is nothing to listen on:
+* the context stays locked unless the start attempt of `startUnlock` runs it.
 *
 * @param ctx - Domain context of the plugin.
 */
@@ -18720,9 +19010,10 @@ function createContext(config) {
 }
 /**
 * Starts the plugin in `onStart`: the audio session first, before any sound exists, then both
-* effect handlers, then the context with its graph and its unlock. The handlers are registered
-* even headless, so a node that awaits a sound resolves in plain Bun exactly as it does in a
-* browser.
+* effect handlers, then the context with its graph and its unlock. The unlock asks the context to
+* run at once: a shell that lets audio play is unlocked with no touch, and a browser that wants a
+* gesture gets the two listeners. The handlers are registered even headless, so a node that
+* awaits a sound resolves in plain Bun exactly as it does in a browser.
 *
 * @param ctx - Kernel context of the audio plugin.
 */
@@ -18737,7 +19028,7 @@ function startAudio(ctx) {
 	state.context = context;
 	state.buses = buildGraph(context, state.buses);
 	applyAllGains(state);
-	installUnlock(audio);
+	startUnlock(audio);
 }
 /**
 * Frees everything `onStart` opened: the two handler registrations, the two window listeners, the
@@ -24501,8 +24792,8 @@ function leave(ctx) {
 * Runs the Back chain once. `back()` and the provider's `onBack` both go through here, so a test
 * and a real press end the same way. Escape is what ui answers with the `escape` button of its
 * top root; it also ends the editing of a text field. While the graph moves between nodes the gate
-* is closed: it holds the answer for one frame, so the press counts as taken and never leaves the
-* app in the middle of a step.
+* is closed: it holds the answer for the next gate (one frame, or `flow.holdMs`), so the press
+* counts as taken and never leaves the app in the middle of a step.
 *
 * @param ctx - Kernel context of the platform plugin.
 * @returns What took the press, `"none"` without a provider.
@@ -35424,6 +35715,7 @@ function defineMotion(spec) {
 * | flow | retries | 1 |
 * | flow | settleTimeoutMs | 2000 |
 * | flow | journalLimit | 500 |
+* | flow | holdMs | 0, an answer to a closed gate lives one frame |
 * | world | settleMs | 350 |
 * | world | reconciledEvent | false |
 * | renderer | mount | undefined, inert without a mount |