@moku-labs/game 0.0.1 → 0.0.2

package/dist/types-JNc_UQBo.d.mts

@@ -0,0 +1,2896 @@
+import { Log } from "@moku-labs/common/browser";
+import { AnyPluginInstance, PluginCtx } from "@moku-labs/core";
+
+//#region src/config.d.ts
+/**
+ * Global configuration of a game.
+ *
+ * @example
+ * ```ts
+ * createApp({ config: { orientation: "portrait", referenceSide: 1080, referenceLong: 2100 } });
+ * ```
+ */
+type Config$5 = {
+  /** Screen orientation the game is designed for. */orientation: "portrait" | "landscape"; /** Short side of the reference resolution in pixels. */
+  referenceSide: number;
+  /**
+   * The long side, in reference units, the layout needs inside the safe area. The viewport scale
+   * fits both sides, so a wide screen gives the layout more width instead of less height.
+   *
+   * @example
+   * ```ts
+   * // A board column of 2084 u: on a 768x1024 tablet the scale is 1024 / 2100 = 0.488 and the
+   * // reference width grows to 1575 u, so the whole column fits and nothing shrinks alone.
+   * createApp({ config: { referenceLong: 2100 } });
+   * ```
+   */
+  referenceLong: number;
+};
+/**
+ * Global events. Empty: every event belongs to a plugin.
+ */
+type Events$3 = Record<never, never>;
+/**
+ * Public API type of a plugin instance, read from its phantom carrier.
+ * Mirrors the kernel's non-exported `ExtractPluginApi`.
+ *
+ * @example
+ * ```ts
+ * type TimeApi = ApiOf<typeof timePlugin>; // the `Api` type of src/plugins/time/types.ts
+ * ```
+ */
+type ApiOf<Plugin> = Plugin extends {
+  readonly _phantom: {
+    readonly api: infer PluginApi;
+  };
+} ? PluginApi : never;
+/**
+ * Structural type of `ctx.require`, for domain factories that resolve their own dependencies.
+ * The bound repeats the kernel's plugin shape so the kernel's generic `require` is assignable to it.
+ */
+type Require = <Plugin extends {
+  readonly name: string;
+  readonly spec: unknown;
+  readonly _phantom: {
+    readonly config: unknown;
+    readonly state: unknown;
+    readonly api: unknown;
+    readonly events: Record<string, unknown>;
+  };
+}>(plugin: Plugin) => ApiOf<Plugin>;
+declare namespace types_d_exports$4 {
+  export { Api$4 as Api, ClockCtx, ClockSource, Config$4 as Config, Elapsed, FakeClock, State$4 as State };
+}
+/**
+ * Source of time and timers. The system source is the default; a game passes its own when time
+ * must come from somewhere else, for example a server.
+ *
+ * @example
+ * ```ts
+ * // Server time: the device clock only measures the distance from the last sync. The plugin keeps
+ * // at most one timer alive, so the source remembers one.
+ * const serverClock = (serverNow: number): ClockSource => {
+ *   const syncedAt = performance.now();
+ *   let timer: ReturnType<typeof setTimeout> | undefined;
+ *
+ *   return {
+ *     now: () => serverNow + (performance.now() - syncedAt),
+ *     setTimer: (callback, delayMs) => (timer = setTimeout(callback, delayMs)),
+ *     clearTimer: () => clearTimeout(timer)
+ *   };
+ * };
+ *
+ * createApp({ pluginConfigs: { clock: { source: serverClock(1_790_000_000_000) } } });
+ * ```
+ */
+type ClockSource = {
+  /**
+   * Reads the current moment.
+   *
+   * @returns Epoch milliseconds. A fraction is cut by the plugin; going back is tolerated.
+   */
+  now(): number;
+  /**
+   * Schedules one callback. The plugin keeps at most one timer alive.
+   *
+   * @param callback - Function to run when the delay has passed.
+   * @param delayMs - Delay in milliseconds, never negative.
+   * @returns A handle of any shape; the plugin only hands it back to `clearTimer`.
+   */
+  setTimer(callback: () => void, delayMs: number): unknown;
+  /**
+   * Cancels a pending timer. A handle this source did not produce must be ignored.
+   *
+   * @param handle - Handle returned by `setTimer`.
+   */
+  clearTimer(handle: unknown): void;
+};
+/**
+ * Fake source for tests, from `@moku-labs/game/testing`. It needs no real timer.
+ *
+ * @example
+ * ```ts
+ * // An energy point refills after 60 s. The test does not wait: it moves the clock.
+ * const clock = fakeClock(1000);
+ * const app = createApp({ pluginConfigs: { clock: { source: clock } } });
+ *
+ * app.clock.scheduleAt(61_000);
+ * clock.advance(60_000); // the listeners of onElapsed get { now: 61000 }
+ * ```
+ */
+type FakeClock = ClockSource & {
+  /**
+   * Moves the clock forward and fires every timer that falls due on the way, in due order.
+   *
+   * @param ms - Milliseconds to move forward. A negative amount moves nothing.
+   * @example
+   * ```ts
+   * clock.advance(5000); // now() is 5000 later, a timer due in 3000 has fired
+   * ```
+   */
+  advance(ms: number): void;
+  /**
+   * Jumps to a moment without firing any timer. Moving back is allowed: that is a player who
+   * sets the device clock by hand.
+   *
+   * @param moment - Moment in epoch milliseconds.
+   * @example
+   * ```ts
+   * clock.set(400); // the device clock went back; app.clock.now() does not decrease
+   * ```
+   */
+  set(moment: number): void;
+};
+/**
+ * Input delivered to `onElapsed` listeners when a due moment arrives or the game resumes.
+ *
+ * @example
+ * ```ts
+ * const input: Elapsed = { now: 1_790_000_060_000 };
+ * ```
+ */
+type Elapsed = {
+  now: number;
+};
+/**
+ * clock plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { clock: { source: fakeClock(1000) } } });
+ * ```
+ */
+type Config$4 = {
+  /**
+   * Time source. `undefined` means the system source: `Date.now` and `setTimeout`.
+   */
+  source: ClockSource | undefined;
+};
+/**
+ * clock plugin state.
+ */
+type State$4 = {
+  source: ClockSource;
+  last: number;
+  dueAt: number | undefined;
+  handle: unknown;
+  listeners: Array<(input: Elapsed) => void>;
+};
+/**
+ * clock plugin API, `app.clock`. Trusted time for rules that depend on real time: energy refill,
+ * generators, daily rewards. The clock holds ONE pending moment; the rules decide the next one.
+ *
+ * @example
+ * ```ts
+ * // The whole cycle: ask the rules for the nearest moment, wait for it, apply, ask again.
+ * app.clock.onElapsed(({ now }) => {
+ *   applyRefills(now);
+ *   app.clock.scheduleAt(nextRefillAt(now)); // undefined when nothing is pending
+ * });
+ * app.clock.scheduleAt(nextRefillAt(app.clock.now()));
+ * ```
+ */
+type Api$4 = {
+  /**
+   * Reads trusted time. It never decreases, whatever the device clock does, so a player who sets
+   * the clock back gains nothing.
+   *
+   * @returns The current moment in epoch milliseconds, an integer.
+   * @example
+   * ```ts
+   * // Stamp a generator when it is used, and compare later.
+   * player.generator.usedAt = app.clock.now(); // 1790000000000
+   * const ready = app.clock.now() - player.generator.usedAt >= 60_000;
+   * ```
+   */
+  now(): number;
+  /**
+   * Replaces the single pending due moment. A moment in the past is not delivered synchronously:
+   * it fires on the next macrotask of the source.
+   *
+   * @param moment - Moment in epoch milliseconds, or `undefined` to cancel.
+   * @example
+   * ```ts
+   * // A generator refills in 60 s. Only one moment is pending: the nearest one.
+   * app.clock.scheduleAt(app.clock.now() + 60_000);
+   * app.clock.scheduleAt(undefined); // nothing is due any more: cancel
+   * ```
+   */
+  scheduleAt(moment: number | undefined): void;
+  /**
+   * Registers a listener for the `elapsed` input: a due moment arrived, or `poke` was called.
+   * The clock does not reschedule by itself.
+   *
+   * @param listener - Called with `{ now }`, the trusted moment of the delivery.
+   * @returns The unsubscribe function.
+   * @example
+   * ```ts
+   * const off = app.clock.onElapsed(({ now }) => {
+   *   applyRefills(now); // now: 1790000060000
+   * });
+   *
+   * off(); // the screen that showed the timer is closed
+   * ```
+   */
+  onElapsed(listener: (input: Elapsed) => void): () => void;
+  /**
+   * Delivers `elapsed` right now, without touching the pending due moment. The engine calls it
+   * when the game resumes; a game calls it after it changed something the rules depend on.
+   *
+   * @example
+   * ```ts
+   * // The game synced with its server and the time source jumped forward: let the rules catch up.
+   * // On resume from background the engine pokes by itself, a game never does that.
+   * app.clock.poke(); // onElapsed listeners get { now } at once; the pending moment stays
+   * ```
+   */
+  poke(): void;
+  /**
+   * Reads the pending due moment, for inspection and tests.
+   *
+   * @returns The pending moment, or `undefined` when nothing is scheduled.
+   * @example
+   * ```ts
+   * app.clock.scheduleAt(1500);
+   * app.clock.dueAt(); // 1500
+   * await app.stop();
+   * app.clock.dueAt(); // undefined
+   * ```
+   */
+  dueAt(): number | undefined;
+};
+/**
+ * Domain context of the clock plugin.
+ */
+type ClockCtx = PluginCtx<Config$4, State$4> & {
+  readonly global: object;
+};
+declare namespace types_d_exports$3 {
+  export { Api$3 as Api, Config$3 as Config, Events$2 as Events, LifecycleCtx, PauseReason, State$3 as State };
+}
+/**
+ * Why the game is paused. The named reasons are the engine's own; any other string is allowed.
+ *
+ * @example
+ * ```ts
+ * const reason: PauseReason = "background";
+ * ```
+ */
+type PauseReason = "background" | "devtools" | "system-dialog" | "device-lost" | (string & {});
+/**
+ * lifecycle plugin events.
+ *
+ * @example
+ * ```ts
+ * // The payload of the first `app.lifecycle.push("background")`.
+ * const payload: Events["lifecycle:changed"] = {
+ *   reason: "background", action: "push",
+ *   reasons: ["background"], paused: true, resumed: false
+ * };
+ * ```
+ */
+type Events$2 = {
+  /**
+   * The pause stack changed. `reason` and `action` say what changed; `resumed` is true only on
+   * the change that emptied the stack.
+   */
+  "lifecycle:changed": {
+    reason: PauseReason;
+    action: "push" | "pop";
+    reasons: readonly PauseReason[];
+    paused: boolean;
+    resumed: boolean;
+  };
+};
+/**
+ * lifecycle plugin config: none. The plugin has no tunable behaviour.
+ *
+ * @example
+ * ```ts
+ * const config: Config = {};
+ * ```
+ */
+type Config$3 = Record<string, never>;
+/**
+ * lifecycle plugin state: the pause reasons in insertion order, no duplicates.
+ */
+type State$3 = {
+  reasons: PauseReason[];
+};
+/**
+ * lifecycle plugin API, `app.lifecycle`. The stack of reasons why the game is paused: the first
+ * reason pauses `time`, the last one to leave resumes it, and every real change of the stack
+ * emits `lifecycle:changed`.
+ *
+ * @example
+ * ```ts
+ * // Two reasons hold the pause, so they never cancel each other.
+ * app.lifecycle.push("background"); // time pauses
+ * app.lifecycle.push("ad"); // still one pause
+ * app.lifecycle.pop("background"); // still paused: "ad" holds
+ * app.lifecycle.pop("ad"); // time resumes
+ * ```
+ */
+type Api$3 = {
+  /**
+   * Pushes a reason why the game is paused. A reason already on the stack is ignored, so two
+   * plugins pausing for the same reason never pause twice.
+   *
+   * @param reason - Why the game is paused.
+   * @example
+   * ```ts
+   * // A rewarded ad covers the game: the world stands while it plays.
+   * app.lifecycle.push("ad"); // app.time.isPaused() is true, "lifecycle:changed" is emitted
+   * app.lifecycle.push("ad"); // already on the stack: no second pause, no event
+   * ```
+   */
+  push(reason: PauseReason): void;
+  /**
+   * Pops a reason. The game runs again only when the last reason leaves. A reason that is not
+   * on the stack is ignored.
+   *
+   * @param reason - The reason that no longer holds.
+   * @example
+   * ```ts
+   * // The tab is visible again. The game runs, unless another reason still holds.
+   * document.addEventListener("visibilitychange", () => {
+   *   if (!document.hidden) app.lifecycle.pop("background");
+   * });
+   * ```
+   */
+  pop(reason: PauseReason): void;
+  /**
+   * Reads the stack as a frozen copy, in insertion order, so a caller cannot write into it.
+   *
+   * @returns The pause reasons currently held.
+   * @example
+   * ```ts
+   * // A debug overlay shows why the game stands still.
+   * app.lifecycle.push("background");
+   * app.lifecycle.push("ad");
+   * app.lifecycle.reasons(); // ["background", "ad"]
+   * ```
+   */
+  reasons(): readonly PauseReason[];
+  /**
+   * Tells whether the game is paused: true while the stack is not empty.
+   *
+   * @returns True while at least one reason holds.
+   * @example
+   * ```ts
+   * // The idle hint must not start behind a system dialog.
+   * app.lifecycle.push("system-dialog");
+   * app.lifecycle.isPaused(); // true
+   * ```
+   */
+  isPaused(): boolean;
+};
+/**
+ * Domain context: the kernel context with `require`, used to reach `time`. `emit` is the kernel's:
+ * `index.ts` writes `events` with an annotated `register` (core spec `14` row 8), so the own event
+ * reaches a factory passed by direct reference.
+ */
+type LifecycleCtx = PluginCtx<Config$3, State$3, Events$2> & {
+  readonly require: Require;
+};
+//#endregion
+//#region src/plugins/model/rng/types.d.ts
+/**
+ * @file model/rng — type definitions.
+ */
+/**
+ * Persisted randomness: one uint32 per stream id.
+ *
+ * @example
+ * ```ts
+ * // Seed 42, one draw from the stream "chest:42".
+ * const rng: RngState = { seed: 42, streams: { "chest:42": 22541618 } };
+ * ```
+ */
+type RngState = {
+  seed: number;
+  streams: Record<string, number>;
+};
+/**
+ * One deterministic stream. Integers only, so every engine produces the same numbers.
+ *
+ * @example
+ * ```ts
+ * // Inside a node the rng view comes with the context.
+ * export const roll = defineNode({
+ *   outcomes: { done: type() },
+ *   run: ({ player, rng, out }) => {
+ *     player.coins += rng.stream("dice").range(1, 6); // 4: first draw of a save with seed 42
+ *     return out.done();
+ *   }
+ * });
+ * ```
+ */
+type RngStream = {
+  /**
+   * Draws an integer in `[0, maxExclusive)`.
+   *
+   * @param maxExclusive - Upper bound, excluded.
+   * @returns The drawn integer.
+   * @throws {Error} When the bound is not a positive integer.
+   * @example
+   * ```ts
+   * // Which of the six board columns gets the new tile.
+   * const column = rng.stream("spawn").int(6); // 0 to 5
+   * ```
+   */
+  int(maxExclusive: number): number;
+  /**
+   * Draws an integer in `[min, maxInclusive]`.
+   *
+   * @param min - Lower bound, included.
+   * @param maxInclusive - Upper bound, included.
+   * @returns The drawn integer.
+   * @throws {Error} When the span is empty.
+   * @example
+   * ```ts
+   * // A die.
+   * player.lastRoll = rng.stream("dice").range(1, 6); // 4: first draw of a save with seed 42
+   * ```
+   */
+  range(min: number, maxInclusive: number): number;
+  /**
+   * Picks one element of an array.
+   *
+   * @param items - The array to pick from.
+   * @returns The picked element.
+   * @throws {Error} When the array is empty or has holes.
+   * @example
+   * ```ts
+   * // The reward of chest 42.
+   * rng.stream("chest:42").pick(["coin", "gem", "key"]); // "gem": first draw, seed 42
+   * ```
+   */
+  pick<Item>(items: readonly Item[]): Item;
+  /**
+   * Picks one entry of a table by its integer weight. Entries of weight zero never win.
+   *
+   * @param table - Entries with integer weights.
+   * @returns The picked entry.
+   * @throws {Error} When no entry has a positive weight.
+   * @example
+   * ```ts
+   * // A coin drops three times as often as a gem.
+   * const drop = rng.stream("drop").weighted([
+   *   { id: "coin", weight: 3 },
+   *   { id: "gem", weight: 1 }
+   * ]); // { id: "gem", weight: 1 }: first draw, seed 42
+   * ```
+   */
+  weighted<Entry extends {
+    weight: number;
+  }>(table: readonly Entry[]): Entry;
+  /**
+   * Draws a `numerator` in `denominator` chance.
+   *
+   * @param numerator - How many of the outcomes are a hit.
+   * @param denominator - How many outcomes there are.
+   * @returns True when the draw is a hit.
+   * @throws {Error} When the denominator is not a positive integer.
+   * @example
+   * ```ts
+   * // One merge in twenty gives a bonus tile.
+   * const bonus = rng.stream("bonus").chance(1, 20);
+   * ```
+   */
+  chance(numerator: number, denominator: number): boolean;
+};
+/**
+ * View over an rng branch, draft or frozen: `rng` of a node context. Every draw advances
+ * `streams[id]` of the branch, so draws inside a transaction commit with it and draws inside a
+ * discarded transaction are forgotten with it.
+ */
+type RngView = {
+  /**
+   * Opens one stream. The first draw seeds it from the save's seed and the id, so opening a
+   * stream without drawing leaves the branch untouched.
+   *
+   * @param id - Stream id. One id per source, for example `"chest:42"`.
+   * @returns The stream of that id.
+   * @example
+   * ```ts
+   * // One id per source: a kill of the app before the rest node cannot re-roll chest 42.
+   * const chest = rng.stream("chest:42");
+   * chest.int(6); // 2: first draw of a save with seed 42
+   * chest.int(6); // 0
+   * ```
+   */
+  stream(id: string): RngStream;
+};
+/**
+ * rng module API, `app.model.rng`: inspection of stream state in the committed document. Draws
+ * never happen here; they happen on the `rng` view of a node context.
+ */
+type RngApi = {
+  /**
+   * Reads the committed state of one stream, for bookmarks, tools and tests. It never draws.
+   *
+   * @param id - Stream id.
+   * @returns The uint32 state of the stream, or `undefined` when it was never drawn.
+   * @example
+   * ```ts
+   * // A test checks that one roll drew from the dice stream. The save has seed 42.
+   * app.model.rng.peek("dice"); // undefined: never drawn
+   * await game.walk([{ at: "home", intent: "roll" }]);
+   * app.model.rng.peek("dice"); // 1175946015
+   * ```
+   */
+  peek(id: string): number | undefined;
+};
+//#endregion
+//#region src/plugins/model/store/types.d.ts
+/**
+ * JSON patch produced by a commit.
+ *
+ * @example
+ * ```ts
+ * const patch: Patch = { op: "replace", path: ["player", "coins"], value: 12 };
+ * ```
+ */
+type Patch = {
+  op: "add" | "remove" | "replace";
+  path: (string | number)[];
+  value?: Json;
+};
+/**
+ * The persisted document.
+ *
+ * @example
+ * ```ts
+ * const doc: SaveDoc = { player: { coins: 0 }, rng: { seed: 42, streams: {} } };
+ * ```
+ */
+type SaveDoc = {
+  player: Json;
+  rng: RngState;
+};
+/**
+ * The save seam implemented by the application layer. `state` is the whole SaveDoc.
+ *
+ * @example
+ * ```ts
+ * // A server save: the server holds the document and applies the patches it is sent.
+ * const serverSave = (url: string): PlayerStateProvider => {
+ *   const queue: { patches: Patch[]; version: number }[] = [];
+ *
+ *   const send = async (batch: typeof queue, txId?: string): Promise<void> => {
+ *     if (batch.length === 0) return;
+ *     await fetch(url, { method: "POST", body: JSON.stringify({ batch, txId }) });
+ *   };
+ *
+ *   return {
+ *     load: async () => {
+ *       const response = await fetch(url);
+ *       return response.status === 404 ? null : await response.json(); // { state, version }
+ *     },
+ *     commit: (patches, version) => {
+ *       queue.push({ patches, version }); // a rest node: accumulate, write at the next flush
+ *     },
+ *     commitDurable: async (patches, txId, version) => {
+ *       queue.push({ patches, version });
+ *       await send(queue.splice(0), txId); // a barrier node: resolve only when it is stored
+ *     },
+ *     flush: () => send(queue.splice(0))
+ *   };
+ * };
+ *
+ * createApp({ pluginConfigs: { model: { playerProvider: serverSave("/api/save") } } });
+ * ```
+ */
+type PlayerStateProvider = {
+  /**
+   * Reads the save. Called once, by `store.load()`.
+   *
+   * @returns The stored document and its schema version. `null` means a new player.
+   */
+  load(): Promise<{
+    state: Json;
+    version: number;
+  } | null>;
+  /**
+   * Called at rest nodes. The provider accumulates and debounces writes.
+   *
+   * @param patches - Doc patches since the last commit.
+   * @param version - Schema version this build writes.
+   */
+  commit(patches: Patch[], version: number): void;
+  /**
+   * Called after a barrier node. Resolves when the data is durable.
+   *
+   * @param patches - Doc patches since the last commit.
+   * @param txId - Id of the transaction that left the barrier node.
+   * @param version - Schema version this build writes.
+   * @returns Resolves when the data is durable.
+   */
+  commitDurable(patches: Patch[], txId: string, version: number): Promise<void>;
+  /**
+   * Writes what was accumulated. Called on a background pause and on stop.
+   *
+   * @returns Resolves when the provider has written.
+   */
+  flush(): Promise<void>;
+};
+/**
+ * One recorded call of the in-memory provider.
+ *
+ * @example
+ * ```ts
+ * const call: ProviderCall = {
+ *   method: "commit",
+ *   patches: [{ op: "replace", path: ["player", "coins"], value: 4 }],
+ *   version: 1
+ * };
+ * ```
+ */
+type ProviderCall = {
+  method: "load";
+} | {
+  method: "commit";
+  patches: Patch[];
+  version: number;
+} | {
+  method: "commitDurable";
+  patches: Patch[];
+  txId: string;
+  version: number;
+} | {
+  method: "flush";
+};
+/**
+ * One step of the save migration chain. `up` of `from: n` gets the whole save document of version
+ * `n` and returns the document of version `n + 1`.
+ *
+ * @example
+ * ```ts
+ * // Version 1 saved `gold`. Version 2 calls it `coins`.
+ * const renameGold: Migration = {
+ *   from: 1,
+ *   up: state => {
+ *     const doc = state as { player: { gold: number }; rng: RngState };
+ *
+ *     return { player: { coins: doc.player.gold }, rng: doc.rng };
+ *   }
+ * };
+ *
+ * createApp({ pluginConfigs: { model: { schemaVersion: 2, migrations: [renameGold] } } });
+ * ```
+ */
+type Migration = {
+  from: number;
+  up(state: Json): Json;
+};
+/**
+ * Frozen view of committed state.
+ *
+ * @example
+ * ```ts
+ * const snapshot: Snapshot = {
+ *   player: { coins: 4 },
+ *   session: { rolls: 1 },
+ *   rng: { seed: 42, streams: { dice: 1175946015 } }
+ * };
+ * ```
+ */
+type Snapshot = {
+  readonly player: Json;
+  readonly session: Json;
+  readonly rng: Readonly<RngState>;
+};
+/**
+ * Result of a commit: the patches split by tree, and the touched roots in the order `player`,
+ * `session`, `rng`.
+ *
+ * @example
+ * ```ts
+ * const result: CommitResult = {
+ *   patches: { doc: [{ op: "replace", path: ["player", "coins"], value: 4 }], session: [] },
+ *   roots: ["player"]
+ * };
+ * ```
+ */
+type CommitResult = {
+  patches: {
+    doc: Patch[];
+    session: Patch[];
+  };
+  roots: Root[];
+};
+/**
+ * Open transaction handed to one node run.
+ *
+ * @example
+ * ```ts
+ * // A game never holds a transaction: the node context carries its drafts and its rng view.
+ * export const roll = defineNode({
+ *   outcomes: { done: type() },
+ *   run: ({ player, rng, out }) => {
+ *     player.coins += rng.stream("dice").range(1, 6);
+ *     return out.done();
+ *   }
+ * });
+ * ```
+ */
+type Transaction = {
+  /** Mutable draft of the player tree. */player: Json; /** Mutable draft of the session tree. */
+  session: Json; /** Rng view bound to the draft `doc.rng`. Draws advance the draft. */
+  rng: RngView;
+  /**
+   * Commits the drafts of this transaction on the edge: finishes the drafts, swaps the frozen
+   * trees, appends the doc patches to the pending list and emits `model:committed` with cause
+   * `"edge"`.
+   *
+   * @returns The patches split by tree and the touched roots.
+   * @throws {Error} When the transaction was already committed or discarded.
+   * @example
+   * ```ts
+   * // A runner plugin commits on the edge, after the node body returned its outcome.
+   * const { store } = ctx.require(modelPlugin);
+   * const transaction = store.begin();
+   * await runNodeBody(transaction); // the node wrote coins into transaction.player
+   * transaction.commit().roots; // ["player"]
+   * ```
+   */
+  commit(): CommitResult;
+  /**
+   * Drops the drafts of this transaction. Nothing changes and nothing is emitted.
+   *
+   * @throws {Error} When the transaction was already committed or discarded.
+   * @example
+   * ```ts
+   * // The node threw or was aborted: nothing of its drafts may reach the state.
+   * transaction.discard();
+   * store.snapshot().player; // as it was before begin()
+   * ```
+   */
+  discard(): void;
+};
+/**
+ * store module state.
+ */
+type StoreState = {
+  /** Frozen save document. */doc: SaveDoc; /** Frozen session tree. */
+  session: Json; /** Frozen trees of the last rest point. */
+  restPoint: {
+    doc: SaveDoc;
+    session: Json;
+  } | undefined; /** Doc patches since the last provider commit. */
+  pending: Patch[];
+  transaction: Transaction | undefined;
+  loaded: boolean;
+  provider: PlayerStateProvider;
+};
+/**
+ * store module API, `app.model.store`. Logic changes the trees only inside a transaction, and only
+ * a rest point hands patches to the provider, so a kill between two rest nodes loses a whole
+ * transition and never half of one.
+ *
+ * @example
+ * ```ts
+ * // A game only reads the store. The flow runner loads, opens transactions and marks rest points.
+ * const { player, session } = app.model.store.snapshot();
+ * ```
+ */
+type StoreApi = {
+  /**
+   * Loads the save. A new player gets the initial player and a seed; a stored save runs through
+   * the migration chain. Nothing is written until the document is complete, so a failure leaves
+   * the state exactly as it was and the app can show a clear screen. A document the provider has
+   * no base for, a new player or a migrated save, is handed over at once: a player who leaves on
+   * the first screen is a saved player. Marks the first rest point and emits `model:committed`
+   * with cause `"load"`.
+   *
+   * @returns Resolves when the document is in place.
+   * @throws {SaveUnreadableError} When the save cannot be read by this build.
+   * @throws {unknown} The error of a provider that fails to load or refuses the first commit.
+   * @example
+   * ```ts
+   * // The flow runner loads the save once, before the first node; a game calls app.flow.run().
+   * const { store } = ctx.require(modelPlugin);
+   * await store.load(); // model:committed fires with cause "load"
+   * store.snapshot().player; // { coins: 0 } for a new player, from config.initialPlayer
+   * ```
+   */
+  load(): Promise<void>;
+  /**
+   * Hands out the committed trees. Frozen: this is the only thing a view or a projection sees.
+   * Before `load()` it shows the initial player, never a half-read save. The same object comes
+   * back while nothing was committed, so a watcher compares identities instead of trees.
+   *
+   * @returns The frozen player, session and rng trees.
+   * @example
+   * ```ts
+   * // A test plays two rolls headless and reads what was committed.
+   * await game.walk([{ at: "home", intent: "roll" }, { at: "home", intent: "roll" }]);
+   * app.model.store.snapshot().session; // { rolls: 2 }
+   *
+   * // An editor panel re-reads the model only when a commit replaced the snapshot.
+   * app.model.store.snapshot() === app.model.store.snapshot(); // true until the next commit
+   * ```
+   */
+  snapshot(): Snapshot;
+  /**
+   * Opens the drafts of one node run. One transaction at a time: a second `begin` is a bug in the
+   * runner, not a state to recover from.
+   *
+   * @returns The open transaction.
+   * @throws {Error} When a transaction is already open.
+   * @example
+   * ```ts
+   * // The flow runner opens one transaction when it enters a node and keeps it until the edge.
+   * const transaction = ctx.require(modelPlugin).store.begin();
+   * transaction.player; // a draft: writes stay invisible to snapshot() until commit()
+   * ```
+   */
+  begin(): Transaction;
+  /**
+   * Marks a rest node: the provider receives everything since the last rest point, and only then
+   * does the rest point move. A throwing provider leaves both untouched, so the next attempt
+   * still holds the whole transition.
+   *
+   * @throws {unknown} The error of a failing provider.
+   * @example
+   * ```ts
+   * // The edge led into a node with `rest: true`: the provider gets the whole transition.
+   * transaction.commit();
+   * store.markRest(); // provider.commit() receives every patch since the last rest point
+   * ```
+   */
+  markRest(): void;
+  /**
+   * Marks a barrier node: rollback cannot cross it, so the rest point moves first. The pending
+   * patches are dropped only once the provider reports the data as durable.
+   *
+   * @param txId - Id of the transaction that left the barrier node.
+   * @returns Resolves when the data is durable.
+   * @throws {unknown} The error of a failing provider.
+   * @example
+   * ```ts
+   * // The edge left a node with `barrier: true`, for example a granted purchase: wait for the disk.
+   * // The id is path#journalIndex@now, built by the runner.
+   * await store.markBarrier("shop/grant#12@1790000000000");
+   * ```
+   */
+  markBarrier(txId: string): Promise<void>;
+  /**
+   * Returns to the last rest point. It discards an open transaction first. A pointer swap to
+   * frozen trees: no inverse patch is replayed. Everything in `pending` belongs to the failed
+   * transition, because a rest point empties it. Emits `model:committed` with cause `"rollback"`.
+   *
+   * @example
+   * ```ts
+   * // A node failed after it wrote into its drafts: back to the last rest point, then retry.
+   * store.rollback(); // model:committed fires with cause "rollback"
+   * ```
+   */
+  rollback(): void;
+  /**
+   * Replaces the trees: a bookmark, a repro, a dev restore after a reload. What is omitted stays
+   * as it is. The restored trees become the new rest point. The provider receives the whole
+   * document at the next rest point, never patches on a base it no longer has. Emits
+   * `model:committed` with cause `"restore"`.
+   *
+   * @param input - The trees to put in place.
+   * @param input.player - The player tree.
+   * @param input.session - The session tree. Omitted: the current one stays.
+   * @param input.rng - The rng branch. Omitted: the current one stays.
+   * @throws {Error} When a transaction is open.
+   * @example
+   * ```ts
+   * // The flow runner enters a bookmark: the trees first, then the rest point, then the node.
+   * // A game calls app.flow.restore(bookmark), which does all three.
+   * store.restore({ player: bookmark.player, session: bookmark.session, rng: bookmark.rng });
+   * store.markRest();
+   * ```
+   */
+  restore(input: {
+    player: Json;
+    session?: Json;
+    rng?: RngState;
+  }): void;
+  /**
+   * Asks the provider to write what it has accumulated. The pending patches stay: between two
+   * rest nodes they are an unfinished transition, and a kill must lose all of it, never half.
+   * The engine calls it on a background pause and on stop.
+   *
+   * @returns Resolves when the provider has written.
+   * @throws {unknown} The error of a failing provider.
+   * @example
+   * ```ts
+   * // The game leaves the page for a payment screen: write the save first.
+   * await app.model.store.flush();
+   * window.location.assign("/checkout");
+   * ```
+   */
+  flush(): Promise<void>;
+};
+/**
+ * Thrown by `load()`, and so by `flow.run()`, when the save cannot be read by this build. The
+ * save stays untouched, so the app can show a clear screen instead of overwriting it.
+ *
+ * @example
+ * ```ts
+ * // The player opens an old build over a newer save: show "update the game", keep the save.
+ * app.flow.run().catch((error: unknown) => {
+ *   if (!(error instanceof SaveUnreadableError)) throw error;
+ *   showUpdateScreen(error.savedVersion, error.schemaVersion); // 3, 2
+ * });
+ * ```
+ */
+declare class SaveUnreadableError extends Error {
+  /** Version found in the save. */
+  readonly savedVersion: number;
+  /** Version this build writes. */
+  readonly schemaVersion: number;
+  /**
+   * Creates the error.
+   *
+   * @param savedVersion - Version found in the save.
+   * @param schemaVersion - Version this build writes.
+   * @param cause - The underlying failure.
+   * @example
+   * ```ts
+   * const error = new SaveUnreadableError(3, 2, new Error("Written by a newer build."));
+   * error.savedVersion; // 3
+   * ```
+   */
+  constructor(savedVersion: number, schemaVersion: number, cause: unknown);
+}
+declare namespace types_d_exports$2 {
+  export { Api$2 as Api, CommitResult, Config$2 as Config, Events$1 as Events, Json, Migration, ModelCtx, Patch, PlayerStateProvider, ProviderCall, RngApi, RngState, RngStream, RngView, Root, SaveDoc, Snapshot, State$2 as State, StoreApi, Transaction };
+}
+/**
+ * Plain JSON value. Everything in state is JSON.
+ *
+ * @example
+ * ```ts
+ * const player: Json = { coins: 10, inventory: ["key"] };
+ * ```
+ */
+type Json = null | boolean | number | string | Json[] | {
+  [key: string]: Json;
+};
+/**
+ * State roots reported by `model:committed`.
+ *
+ * @example
+ * ```ts
+ * const roots: Root[] = ["player", "rng"];
+ * ```
+ */
+type Root = "player" | "session" | "rng";
+/**
+ * model plugin events.
+ *
+ * @example
+ * ```ts
+ * // One node run changed the coins and drew from a stream.
+ * const payload: Events["model:committed"] = { roots: ["player", "rng"], cause: "edge" };
+ * ```
+ */
+type Events$1 = {
+  /** Committed state changed. Projections reconcile from the snapshot. */"model:committed": {
+    roots: readonly Root[];
+    cause: "edge" | "rollback" | "restore" | "load";
+  };
+};
+/**
+ * model plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { model: { initialPlayer: { coins: 0 }, seed: 42 } } });
+ * ```
+ */
+type Config$2 = {
+  /** The save seam. `undefined`: an in-memory provider, nothing is persisted. */playerProvider: PlayerStateProvider | undefined; /** Player state of a new player. Deep-cloned. */
+  initialPlayer: Json; /** Session state at every start. Deep-cloned. */
+  initialSession: Json; /** "from-save": a new player gets a random seed once; a number fixes it (tests). */
+  seed: "from-save" | number; /** Version of the save schema written by this build. */
+  schemaVersion: number; /** Ordered chain; `up` of `from: n` produces version `n + 1`. */
+  migrations: readonly Migration[];
+};
+/**
+ * model plugin state: one branch per module.
+ *
+ */
+type State$2 = {
+  store: StoreState;
+  rng: Record<string, never>;
+};
+/**
+ * model plugin API, `app.model`, grouped by module.
+ *
+ * @example
+ * ```ts
+ * app.model.store.snapshot().player; // { coins: 4 }
+ * app.model.rng.peek("chest:42"); // undefined: this chest was never opened
+ * ```
+ */
+type Api$2 = {
+  store: StoreApi;
+  rng: RngApi;
+};
+/**
+ * Domain context shared by the modules. `emit` is the kernel's: `index.ts` writes `events` with
+ * an annotated `register` (core spec `14` row 8), so the own event reaches a factory passed by
+ * direct reference.
+ */
+type ModelCtx = PluginCtx<Config$2, State$2, Events$1> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+};
+declare namespace types_d_exports$1 {
+  export { Api$1 as Api, Config$1 as Config, FrameCallback, Phase, State$1 as State, Time, TimeCtx };
+}
+/**
+ * Frame phases, in call order.
+ *
+ * @example
+ * ```ts
+ * const phase: Phase = "animate";
+ * ```
+ */
+type Phase = "input" | "animate" | "layout" | "sync" | "signals" | "render";
+/**
+ * The Time resource, in scaled milliseconds. `idle` tells whether the loop currently runs at the
+ * lowered idle cap.
+ *
+ * @example
+ * ```ts
+ * const time: Time = { delta: 16, elapsed: 1600, scale: 1, frame: 100, idle: false };
+ * ```
+ */
+type Time = {
+  delta: number;
+  elapsed: number;
+  scale: number;
+  frame: number;
+  idle: boolean;
+};
+/**
+ * Callback run once per frame in its phase.
+ *
+ * @example
+ * ```ts
+ * const advanceTweens: FrameCallback = time => tweens.advance(time.delta);
+ * ```
+ */
+type FrameCallback = (time: Readonly<Time>) => void;
+/**
+ * time plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { time: { maxFps: 30 } } });
+ * ```
+ */
+type Config$1 = {
+  /**
+   * Frame rate cap. The default is 60. 120 is for WebViews that really deliver 120 Hz frames:
+   * Android today; WKWebView on iOS and macOS is capped at 60 by WebKit (bug 294338).
+   */
+  maxFps: 30 | 60 | 120;
+  /**
+   * Upper bound of one frame's delta in milliseconds.
+   */
+  maxDeltaMs: number;
+  /**
+   * Frame rate cap of an idle screen, when nothing woke the clock for `idleAfterMs`. The default
+   * is 30; 0 turns the idle cap off and every frame runs at `maxFps`.
+   */
+  idleFps: 0 | 30;
+  /**
+   * Unscaled milliseconds without a `wake()` after which the loop drops to `idleFps`.
+   */
+  idleAfterMs: number;
+};
+/**
+ * time plugin state.
+ */
+type State$1 = {
+  callbacks: Record<Phase, FrameCallback[]>;
+  /**
+   * Scratch array of a frame: the six callback lists as they were when the frame started.
+   */
+  captured: (readonly FrameCallback[])[];
+  time: Time;
+  paused: boolean;
+  running: boolean;
+  /**
+   * True while a frame runs; guards `step` re-entry.
+   */
+  stepping: boolean;
+  rafId: number | undefined;
+  lastTimestamp: number | undefined;
+  /**
+   * Elapsed time of the frame source in unscaled milliseconds, the clock of the idle timer: it
+   * keeps running while `scale` is 0.
+   */
+  unscaledElapsedMs: number;
+  /**
+   * Unscaled elapsed time of the last wake.
+   */
+  lastWakeMs: number;
+  /**
+   * True while the loop runs at `idleFps`.
+   */
+  idle: boolean;
+};
+/**
+ * time plugin API, `app.time`. The one clock of the screen: frame callbacks per phase, the `Time`
+ * resource, the time scale, and `step` for tests and tools.
+ *
+ * @example
+ * ```ts
+ * // Frame work is a callback in a phase. A test has no frame source: it drives the frames itself.
+ * const off = app.time.onFrame("animate", time => counter.advance(time.delta));
+ *
+ * app.time.step(16);
+ * // the callback gets { delta: 16, elapsed: 16, scale: 1, frame: 1, idle: false }
+ * off();
+ * ```
+ */
+type Api$1 = {
+  /**
+   * Registers a frame callback. Callbacks of one phase run in registration order; a callback
+   * registered during a frame runs from the next frame on.
+   *
+   * @param phase - Phase the callback belongs to.
+   * @param callback - Function called once per frame with the current `Time`.
+   * @returns Unsubscribe function; calling it twice is a no-op.
+   * @example
+   * ```ts
+   * // The coin counter rolls up while the reward popup is open.
+   * const off = app.time.onFrame("animate", time => counter.advance(time.delta));
+   *
+   * off(); // the popup is closed
+   * ```
+   */
+  onFrame(phase: Phase, callback: FrameCallback): () => void;
+  /**
+   * Returns a snapshot of the current `Time`, so a caller cannot write into the frame state.
+   *
+   * @returns A copy of the current `Time`.
+   * @example
+   * ```ts
+   * // Stamp the start of a combo window in game time, which stands still during a pause.
+   * const startedAt = app.time.snapshot().elapsed; // 1600
+   * app.time.snapshot(); // { delta: 16, elapsed: 1600, scale: 1, frame: 100, idle: false }
+   * ```
+   */
+  snapshot(): Readonly<Time>;
+  /**
+   * Sets the time scale. Every frame delta is multiplied by it; 0 freezes the game time
+   * while the frames keep running. A negative scale is clamped to 0.
+   *
+   * @param scale - New time scale, 0 or greater.
+   * @example
+   * ```ts
+   * // Slow motion while the last match of the level resolves.
+   * app.time.setScale(0.5); // a frame of 20 ms now has delta 10
+   * app.time.setScale(1);
+   * ```
+   */
+  setScale(scale: number): void;
+  /**
+   * Pauses the clock: no phase runs and `elapsed` stops advancing. Called by `lifecycle`.
+   *
+   * @example
+   * ```ts
+   * // The lifecycle plugin owns the pause policy: the first pause reason stops the clock.
+   * // A game pauses through app.lifecycle.push(reason), never here.
+   * const time = ctx.require(timePlugin);
+   * if (reasons.length === 1) time.pause(); // app.time.isPaused() is true, no phase runs
+   * ```
+   */
+  pause(): void;
+  /**
+   * Resumes the clock and drops the stale timestamp, so the first frame after the pause has
+   * a normal delta instead of the whole pause. Called by `lifecycle`.
+   *
+   * @example
+   * ```ts
+   * // The lifecycle plugin resumes when the last pause reason is gone.
+   * const time = ctx.require(timePlugin);
+   * if (reasons.length === 0) time.resume(); // the next frame has a normal delta, not the whole pause
+   * ```
+   */
+  resume(): void;
+  /**
+   * Tells whether the clock is paused.
+   *
+   * @returns True while paused.
+   * @example
+   * ```ts
+   * // A test checks that a pause reason really stopped the frames.
+   * app.lifecycle.push("background");
+   * app.time.isPaused(); // true
+   * ```
+   */
+  isPaused(): boolean;
+  /**
+   * Tells whether a real frame source drives the loop. False in plain Bun, where a test
+   * drives the frames with `step`.
+   *
+   * @returns True while the loop runs.
+   * @example
+   * ```ts
+   * // Without a frame source no frame ever comes: finish the fly-in at once instead of waiting.
+   * if (!app.time.isRunning()) coin.moveTo(target); // false in plain Bun, true in a browser
+   * ```
+   */
+  isRunning(): boolean;
+  /**
+   * Resets the idle timer: the next frame runs at `maxFps` again, even after a long idle. Cheap,
+   * idempotent and safe inside a frame callback. Every plugin that gives the player something to
+   * look at calls it: a pointer sample, a starting animation, a flow edge, a finished load, a
+   * scene switch, a locale change, a reconcile.
+   *
+   * @example
+   * ```ts
+   * // The flow runner walked an edge, so the screen has work again and the cap goes back up.
+   * const time = ctx.require(timePlugin);
+   *
+   * time.wake(); // app.time.snapshot().idle is false from here on
+   * ```
+   */
+  wake(): void;
+  /**
+   * Runs exactly one frame with the given unscaled delta, ignoring the fps cap, the pause
+   * flag and `maxDeltaMs`. The time scale still applies. For tests and tools.
+   *
+   * @param deltaMs - Unscaled delta of the frame in milliseconds.
+   * @throws {Error} When called from inside a frame callback.
+   * @example
+   * ```ts
+   * // A test plays two frames without a browser.
+   * app.time.step(16);
+   * app.time.step(4);
+   * app.time.snapshot(); // { delta: 4, elapsed: 20, scale: 1, frame: 2, idle: false }
+   * ```
+   */
+  step(deltaMs: number): void;
+};
+/**
+ * Domain context of the time plugin.
+ */
+type TimeCtx = PluginCtx<Config$1, State$1> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+};
+//#endregion
+//#region src/plugins/flow/gate/types.d.ts
+/**
+ * One answer of the player, of an agent or of a test.
+ *
+ * @example
+ * ```ts
+ * const answer: Answer = { intent: "merge", payload: { from: "c2", to: "c3" } };
+ * ```
+ */
+type Answer = {
+  intent: string;
+  payload?: Json;
+};
+/**
+ * The one answer a `guide` lets through. `payload` is compared by deep equality when present.
+ *
+ * @example
+ * ```ts
+ * const allow: Allow = { intent: "merge", payload: { from: "c2", to: "c3" } };
+ * ```
+ */
+type Allow = {
+  intent: string;
+  payload?: Json;
+};
+/**
+ * What an open gate accepts.
+ */
+type GateSpec = {
+  allowed: readonly string[];
+};
+/**
+ * gate module state.
+ */
+type GateState = {
+  /** The spec of the open gate. `undefined`: the gate is closed. */open: GateSpec | undefined; /** Resolver of the promise returned by `open`. */
+  resolve: ((answer: Answer) => void) | undefined; /** An answer given while the gate was closed, kept for one frame. */
+  held: {
+    answer: Answer;
+    frame: number;
+  } | undefined; /** The one answer a running `guide` lets through. */
+  narrow: Allow | undefined; /** True while a pointer is down. Entering an `over` node waits for false. */
+  pointerActive: boolean; /** Ends the pending pointer wait of the runner. Set while the wait runs, so a stop needs no frame. */
+  wake: (() => void) | undefined;
+};
+/**
+ * gate module API, `app.flow.gate`: the single entry of player answers.
+ *
+ * @example
+ * ```ts
+ * // The screen turns a tap into an answer. A double tap is safe: the gate closes before the
+ * // first answer is handed on.
+ * app.flow.gate.answer({ intent: "play" }); // true: "home" rests and lists "play"
+ * app.flow.gate.answer({ intent: "play" }); // false: the second tap hits a closed door
+ * ```
+ */
+type GateApi = {
+  /**
+   * Gives one answer. Accepted only while the gate is open and the intent is allowed. An answer
+   * to a closed gate is held for one frame and re-offered when the gate opens within it.
+   *
+   * @param answer - Intent and optional payload.
+   * @returns Whether the answer was accepted.
+   * @example
+   * ```ts
+   * // The player dropped the item of cell c2 onto c3 while the board rests.
+   * app.flow.gate.answer({ intent: "merge", payload: { from: "c2", to: "c3" } }); // true
+   * app.flow.gate.answer({ intent: "quit" }); // false: the resting node does not list "quit"
+   * ```
+   */
+  answer(answer: Answer): boolean;
+  /**
+   * Records that a pointer is down. While true the runner delays entering an `over` node, so a
+   * popup never appears mid-drag.
+   *
+   * @param active - True while the pointer is down.
+   * @example
+   * ```ts
+   * // The input layer reports a drag on the board.
+   * app.flow.gate.pointer(true); // pointer down: an `over` node that comes next waits
+   * app.flow.gate.pointer(false); // pointer up: the node is entered in the next `signals` phase
+   * ```
+   */
+  pointer(active: boolean): void;
+  /**
+   * Reads what the gate takes right now.
+   *
+   * @returns Whether the gate is open, the allowed intents and whether a `guide` narrows it.
+   * @example
+   * ```ts
+   * // The screen greys out a button whose intent the resting node does not take.
+   * app.flow.gate.state(); // { open: true, allowed: ["play", "shop"], narrowed: false }
+   * ```
+   */
+  state(): {
+    open: boolean;
+    allowed: readonly string[];
+    narrowed: boolean;
+  };
+};
+//#endregion
+//#region src/plugins/flow/fx/types.d.ts
+/**
+ * An effect a node awaits. With `answers` the runner opens the gate for those intents.
+ * `cosmetic: true` swallows a handler error and resolves `undefined`.
+ *
+ * @example
+ * ```ts
+ * const descriptor: Descriptor = { kind: "popup", payload: { name: "Retry" }, answers: ["again"] };
+ * ```
+ */
+type Descriptor = {
+  kind: string;
+  payload?: Json;
+  answers?: readonly string[];
+  cosmetic?: boolean;
+};
+/**
+ * A fire-and-forget cosmetic effect. Released only after the commit of its transaction.
+ *
+ * @example
+ * ```ts
+ * const sparkle: Hint = { kind: "sparkle", payload: { cell: "c3" }, hint: true };
+ * ```
+ */
+type Hint = {
+  kind: string;
+  payload?: Json;
+  hint: true;
+};
+/**
+ * Options of the `guide` descriptor: the one allowed answer and its visual part. `target` names
+ * the keyed element the visual hole of `ui` is cut over.
+ *
+ * @example
+ * ```ts
+ * const options: GuideOptions = {
+ *   allow: { intent: "merge" },
+ *   target: { projection: "board", key: "c3" },
+ *   hand: "drag"
+ * };
+ * ```
+ */
+type GuideOptions = {
+  allow: Allow;
+  target?: {
+    projection: string;
+    key: string;
+  };
+  highlight?: readonly string[];
+  hand?: "tap" | "drag";
+  text?: string;
+};
+/**
+ * Handler of one effect kind, registered by a plugin above `flow`. `signal` is the node's abort
+ * signal, except for a descriptor with `answers` and for `guide`: those get a signal of their own,
+ * aborted when the answer arrives or the narrow is lifted, so the handler unmounts what it showed.
+ *
+ * @example
+ * ```ts
+ * // The handler of "sfx": start the sound the node named, stop it when the node is aborted.
+ * const playSound: FxHandler = (descriptor, { signal }) => {
+ *   const sound = sounds.play(descriptor.payload); // payload: { name: "merge" }
+ *
+ *   signal.addEventListener("abort", () => sound.stop());
+ * };
+ *
+ * app.flow.fx.handle("sfx", playSound);
+ * ```
+ */
+type FxHandler = (descriptor: Descriptor | Hint, ctx: {
+  signal: AbortSignal;
+  mode: "live" | "fast";
+}) => unknown | Promise<unknown>;
+/**
+ * Listener of released hints, registered with `fx.onHint`. Every listener hears every hint, so it
+ * reads `kind` itself.
+ *
+ * @example
+ * ```ts
+ * // The world plugin plays a motion for the hints it knows and ignores the rest.
+ * const playMotion: HintListener = released => {
+ *   if (released.kind === "merged") playMergeInto(released.payload);
+ * };
+ * ```
+ */
+type HintListener = (hint: Hint) => void;
+/**
+ * fx module state.
+ */
+type FxState = {
+  /** One handler per effect kind. */handlers: Map<string, {
+    run: FxHandler;
+    runInFast: boolean;
+  }>; /** Hints of the open transaction. */
+  buffered: Hint[]; /** Listeners of released hints, in registration order. */
+  hintListeners: HintListener[]; /** Completions waiting for the `signals` phase, in start order. */
+  settled: Array<() => void>; /** The child controllers of the `guide` handlers that are showing something right now. */
+  guides: AbortController[];
+  mode: "live" | "fast";
+};
+/**
+ * fx module API, `app.flow.fx`: the effects gateway.
+ *
+ * @example
+ * ```ts
+ * // The popup layer owns the kind "popup". It shows the UI; the answer comes through the gate.
+ * app.flow.fx.handle("popup", descriptor => showPopup(descriptor.payload));
+ *
+ * // A node then writes: await fx({ kind: "popup", answers: ["close"] });
+ * ```
+ */
+type FxApi = {
+  /**
+   * Registers the single handler of one effect kind. A second handler for the same kind throws:
+   * an effect has exactly one owner.
+   *
+   * @param kind - Effect kind, for example `"sfx"`.
+   * @param handler - Called with the descriptor and `{ signal, mode }`.
+   * @param options - Registration options.
+   * @param options.runInFast - `true` makes the handler run in fast mode too.
+   * @returns The unregister function. It removes only the handler it registered.
+   * @throws {Error} When the kind already has a handler.
+   * @example
+   * ```ts
+   * // Preloading is real work, so it runs in a fast walk too. Sounds and popups do not.
+   * const off = app.flow.fx.handle("load", preload, { runInFast: true });
+   *
+   * off(); // "load" has no handler again: the kind is free for another owner
+   * ```
+   */
+  handle(kind: string, handler: FxHandler, options?: {
+    runInFast?: boolean;
+  }): () => void;
+  /**
+   * Delivers a descriptor or a released hint to its handler and forgets about it. In fast mode
+   * only a handler registered with `runInFast` is called, exactly as for an awaited effect. A
+   * missing handler is not an error and a failing handler is logged, never thrown.
+   *
+   * @param descriptor - The descriptor or hint to deliver.
+   * @example
+   * ```ts
+   * // The screen wants a haptic tick outside any node. Nothing waits for it.
+   * app.flow.fx.dispatch({ kind: "haptic", payload: { style: "light" } });
+   * ```
+   */
+  dispatch(descriptor: Descriptor | Hint): void;
+  /**
+   * Registers a listener for every released hint. A hint reaches it after the commit of its edge,
+   * in the order the node emitted them; a discarded transaction sends nothing, and fast mode drops
+   * hints altogether. The handler `handle` registered for the same kind is served as well: a
+   * listener displaces nobody.
+   *
+   * @param listener - Called with each released hint.
+   * @returns The unregister function. It removes only the listener it registered.
+   * @example
+   * ```ts
+   * // The world plugin turns the hints of a committed edge into projection motions.
+   * const off = app.flow.fx.onHint(hint => {
+   *   if (hint.kind === "merged") playMergeInto(hint.payload); // payload: { from: "c1", to: "c2" }
+   * });
+   *
+   * off(); // the plugin stopped: no hint reaches it any more
+   * ```
+   */
+  onHint(listener: HintListener): () => void;
+};
+/**
+ * The `fx` of a node context: awaited effects by call, cosmetic hints by `emit`.
+ *
+ * @example
+ * ```ts
+ * // Inside a node body: wait for the player's pick, then sparkle once the edge has committed.
+ * const pick = await fx({ kind: "popup", payload: { name: "Retry" }, answers: ["again", "home"] });
+ * // pick: { intent: "again" }
+ * fx.emit(hint("sparkle", { cell: "c3" }));
+ * ```
+ */
+type NodeFx = ((descriptor: Descriptor) => Promise<unknown>) & {
+  emit(hint: Hint): void;
+};
+//#endregion
+//#region src/plugins/flow/inbox/types.d.ts
+/**
+ * One event of the world: time that passed, a push message, a purchase that arrived.
+ *
+ * @example
+ * ```ts
+ * const event: WorldEvent = { type: "elapsed", payload: { now: 1000 } };
+ * ```
+ */
+type WorldEvent = {
+  type: string;
+  payload?: Json;
+};
+/**
+ * inbox module state.
+ */
+type InboxState = {
+  /** Undelivered events, oldest first. One entry per `type`. */queue: WorldEvent[]; /** Callbacks woken by every `post`. Kept in state so every API instance over this state shares them. */
+  listeners: Array<() => void>;
+};
+/**
+ * inbox module API, `app.flow.inbox`: world events wait here until a rest node that lists their
+ * type is active.
+ *
+ * @example
+ * ```ts
+ * // The shop SDK confirms a purchase at any moment. The graph takes it at the next rest node
+ * // that declares `inbox: ["purchased"]`, as the outcome "purchased" of that node.
+ * app.flow.inbox.post({ type: "purchased", payload: { sku: "coins100" } });
+ * ```
+ */
+type InboxApi = {
+  /**
+   * Queues one world event. It is delivered only when the active node is a rest node whose
+   * `inbox` lists the type; until then it waits. Duplicates of one type collapse to the latest.
+   *
+   * @param event - Type and optional payload.
+   * @example
+   * ```ts
+   * // Two push messages arrive while a transit node runs. The next rest node gets one event.
+   * app.flow.inbox.post({ type: "gift", payload: { coins: 50 } });
+   * app.flow.inbox.post({ type: "gift", payload: { coins: 75 } }); // delivered: { coins: 75 }
+   * ```
+   */
+  post(event: WorldEvent): void;
+};
+//#endregion
+//#region src/plugins/flow/runner/types.d.ts
+/**
+ * A value that carries only a type. Invariant in `Payload`, so `{ stars }` never passes for
+ * `{ stars, moves }` in either direction.
+ *
+ * @example
+ * ```ts
+ * const stars: TypeTag<{ stars: number }> = type<{ stars: number }>();
+ * ```
+ */
+type TypeTag<Payload> = {
+  readonly kind: "type";
+  readonly $type?: (value: Payload) => Payload;
+};
+/**
+ * Any type tag. The bound of tag records: it names no payload, so `type()` infers nothing from it.
+ */
+type AnyTypeTag = {
+  readonly kind: "type";
+};
+/**
+ * Outcome name to the type tag of its payload.
+ *
+ * @example
+ * ```ts
+ * const outcomes = { done: type(), failed: type<{ reason: string }>() } satisfies OutcomeTags;
+ * ```
+ */
+type OutcomeTags = Readonly<Record<string, AnyTypeTag>>;
+/**
+ * The payload type carried by a type tag.
+ *
+ * @example
+ * ```ts
+ * type Reason = PayloadOf<TypeTag<{ reason: string }>>; // { reason: string }
+ * ```
+ */
+type PayloadOf<Tag> = Tag extends TypeTag<infer Payload> ? Payload : never;
+/**
+ * The part of the game types a node sees. Inside the engine both trees are `Json`;
+ * `defineGame<Types>()` narrows them for the game at the type level only.
+ *
+ * @example
+ * ```ts
+ * const game: GameState = { player: { lives: 3 }, session: { visits: 0 } };
+ * ```
+ */
+type GameState = {
+  player: Json;
+  session: Json;
+  scenes?: string;
+};
+/**
+ * The scene ids a game declared, `string` when it declared none.
+ *
+ * @example
+ * ```ts
+ * type Ids = SceneIdOf<{ player: {}; session: {}; scenes: "home" | "board" }>; // "home" | "board"
+ * ```
+ */
+type SceneIdOf<Game extends GameState> = Game extends {
+  scenes: infer Ids extends string;
+} ? Ids : string;
+/**
+ * Whether a payload or input type is `void`: an outcome without data, a node without input.
+ *
+ * @example
+ * ```ts
+ * type Empty = IsVoid<PayloadOf<TypeTag<void>>>; // true
+ * ```
+ */
+type IsVoid<Payload> = [Payload] extends [void] ? true : false;
+/**
+ * What `out.name(data)` returns. `run` must return one of these; a bare string is not accepted.
+ * `Name` is the union of the node's outcome names; without a type argument it is the widened
+ * result the runner reads.
+ *
+ * @example
+ * ```ts
+ * // What `out.rejected({ reason: "empty" })` returns, and what the journal keeps of the edge.
+ * const result: Result = { outcome: "rejected", payload: { reason: "empty" } };
+ * ```
+ */
+type Result<Name extends string = string> = {
+  readonly outcome: Name;
+  readonly payload: Json;
+};
+/**
+ * The `out` of a node context: one method per declared outcome, without an argument when the
+ * payload is `void`.
+ *
+ * @example
+ * ```ts
+ * // In a node with outcomes { done: type(), rejected: type<{ reason: string }>() }:
+ * out.done(); // { outcome: "done", payload: null }
+ * out.rejected({ reason: "empty" }); // { outcome: "rejected", payload: { reason: "empty" } }
+ * ```
+ */
+type Out<Tags extends OutcomeTags> = { readonly [Name in keyof Tags]: IsVoid<PayloadOf<Tags[Name]>> extends true ? () => Result<keyof Tags & string> : (data: PayloadOf<Tags[Name]>) => Result<keyof Tags & string> };
+/**
+ * The one object a node body receives. `player` and `session` are drafts of the open
+ * transaction, `rng` is its view, `now` is `clock.now()` read once at node entry.
+ *
+ * @example
+ * ```ts
+ * // The "roll" node of a dice game: the drafts are written in place, the edge commits them.
+ * run: ({ player, session, rng, out }) => {
+ *   player.coins += rng.stream("dice").range(1, 6);
+ *   session.rolls += 1;
+ *   return out.done();
+ * }
+ * ```
+ */
+type NodeContext<Game extends GameState = GameState, Input = void, Tags extends OutcomeTags = OutcomeTags> = {
+  input: Input;
+  player: Game["player"];
+  session: Game["session"];
+  rng: RngView;
+  fx: NodeFx;
+  out: Out<Tags>;
+  signal: AbortSignal;
+  now: number;
+};
+/**
+ * The body of a node: plain `await` code that ends with `out.name(data)`.
+ */
+type NodeRun<Game extends GameState, Input, Tags extends OutcomeTags> = (ctx: NodeContext<Game, Input, Tags>) => Result<keyof Tags & string> | Promise<Result<keyof Tags & string>>;
+/**
+ * The part of a node, or of a flow used as a node, that an edge table looks at.
+ */
+type Wired<Input, Tags extends OutcomeTags> = {
+  readonly input: TypeTag<Input>;
+  readonly outcomes: Tags;
+};
+/**
+ * Anything that can sit in the `nodes` of a flow: a node, a sub-flow or a slot.
+ */
+type AnyWired = {
+  readonly input: AnyTypeTag;
+  readonly outcomes: OutcomeTags;
+};
+/**
+ * Node name to node: the `nodes` of one flow.
+ */
+type NodeTable = Readonly<Record<string, AnyWired>>;
+/**
+ * A node as `defineNode` returns it: plain data plus the optional body.
+ *
+ * @example
+ * ```ts
+ * // What defineNode({ outcomes: { play: type() }, rest: true, checkpoint: true }) returns:
+ * // { kind: "node", input: { kind: "type" }, outcomes: { play: { kind: "type" } }, rest: true,
+ * //   over: false, checkpoint: true, barrier: false, inbox: [] }
+ * ```
+ */
+type NodeDefinition<Input, Tags extends OutcomeTags, Game extends GameState = GameState> = Wired<Input, Tags> & {
+  readonly kind: "node";
+  readonly rest: boolean;
+  readonly over: boolean;
+  readonly checkpoint: boolean;
+  readonly barrier: boolean;
+  readonly inbox: readonly (keyof Tags & string)[]; /** Id of the scene the node is shown on. Absent: the node keeps the current scene. */
+  readonly scene?: string;
+  readonly run?: NodeRun<Game, Input, Tags>;
+};
+/**
+ * What the author passes to `defineNode`. `run` is required unless `rest: true`: a rest node
+ * without a body is a pure wait.
+ *
+ * @example
+ * ```ts
+ * const spec: NodeSpec<Game, void, { play: TypeTag<void> }> = {
+ *   rest: true,
+ *   checkpoint: true,
+ *   scene: "home",
+ *   outcomes: { play: type() }
+ * };
+ * ```
+ */
+type NodeSpec<Game extends GameState, Input, Tags extends OutcomeTags> = {
+  input?: TypeTag<Input>;
+  outcomes: Tags;
+  over?: boolean;
+  checkpoint?: boolean;
+  barrier?: boolean;
+  inbox?: readonly (keyof Tags & string)[]; /** Id of the scene this node is shown on. Without it the node keeps the current scene. */
+  scene?: SceneIdOf<Game>;
+} & ({
+  rest: true;
+  run?: NodeRun<Game, Input, Tags>;
+} | {
+  rest?: false;
+  run: NodeRun<Game, Input, Tags>;
+});
+/**
+ * The signature of `defineNode` bound to one game. `defineGame<Types>()` returns it.
+ *
+ * @example
+ * ```ts
+ * const defineGameNode: DefineNode<{ player: Player; session: Session }> = defineNode;
+ * ```
+ */
+type DefineNode<Game extends GameState> = <Input = void, const Tags extends OutcomeTags = OutcomeTags>(spec: NodeSpec<Game, Input, Tags>) => NodeDefinition<Input, Tags, Game>;
+/**
+ * An extension point inside a flow: a node whose body is "run the contributions in order".
+ * Its single outcome is `done`.
+ *
+ * @example
+ * ```ts
+ * const afterOrder: SlotNode = slot("afterOrder");
+ * // { kind: "slot", name: "afterOrder", input: { kind: "type" },
+ * //   outcomes: { done: { kind: "type" } } }
+ * ```
+ */
+type SlotNode = Wired<void, {
+  readonly done: TypeTag<void>;
+}> & {
+  readonly kind: "slot";
+  readonly name: string;
+};
+/**
+ * Edge target that leaves the sub-flow with this outcome. The payload passes through.
+ *
+ * @example
+ * ```ts
+ * const leave: Exit<"left"> = exit("left"); // { kind: "exit", outcome: "left" }
+ * ```
+ */
+type Exit<Name extends string = string> = {
+  readonly kind: "exit";
+  readonly outcome: Name;
+};
+/**
+ * Edge target that adapts the payload on the edge. `map` is a property on purpose: the mapper's
+ * parameter annotation is checked strictly against the outcome payload.
+ *
+ * @example
+ * ```ts
+ * const adapt: Mapped<"retry", { reason: string }, { why: string }> = to(
+ *   "retry",
+ *   (failure: { reason: string }) => ({ why: failure.reason })
+ * );
+ * ```
+ */
+type Mapped<TargetName extends string = string, Payload = never, Output = unknown> = {
+  readonly kind: "map";
+  readonly target: TargetName;
+  readonly map: (payload: Payload) => Output;
+};
+/**
+ * A mapped target as the runner calls it. `map` is a method on purpose: method parameters are
+ * compared bivariantly, so every checked `Mapped` fits and the runner calls it without a cast.
+ * The result is `unknown`: a mapper into a node without input returns nothing, and the runner
+ * checks that a mapped payload is plain JSON before it becomes the next input.
+ */
+type AnyMapped = {
+  readonly kind: "map";
+  readonly target: string;
+  map(payload: unknown): unknown;
+};
+/**
+ * Any edge target as the runner reads it: a node name, an exit or a mapped target.
+ *
+ * @example
+ * ```ts
+ * const next: Target = "home"; // a node of the same flow
+ * const leave: Target = exit("left"); // { kind: "exit", outcome: "left" }
+ * ```
+ */
+type Target = string | Exit | AnyMapped;
+/**
+ * Whether a receiver with input `Input` takes `Payload`. A receiver without input ignores the
+ * payload, so it accepts anything; a void outcome into a node with input is an error.
+ *
+ * @example
+ * ```ts
+ * type Fits = Accepts<{ stars: number }, void>; // true
+ * ```
+ */
+type Accepts<Payload, Input> = IsVoid<Input> extends true ? true : [Payload] extends [Input] ? true : false;
+/**
+ * The input type of a node or sub-flow.
+ *
+ * @example
+ * ```ts
+ * type MergeInput = InputOf<typeof merge>; // { from: string; to: string }
+ * ```
+ */
+type InputOf<Node extends AnyWired> = PayloadOf<Node["input"]>;
+/**
+ * Names of the nodes whose input accepts `Payload`.
+ *
+ * @example
+ * ```ts
+ * type Starts = NodeNamesFor<{ boot: typeof boot; merge: typeof merge }, void>; // "boot"
+ * ```
+ */
+type NodeNamesFor<Nodes extends NodeTable, Payload> = { [Name in keyof Nodes & string]: Accepts<Payload, InputOf<Nodes[Name]>> extends true ? Name : never }[keyof Nodes & string];
+/**
+ * Names of the flow outcomes whose payload accepts `Payload`.
+ *
+ * @example
+ * ```ts
+ * type Exits = ExitNamesFor<{ win: TypeTag<{ stars: number }> }, { stars: number }>; // "win"
+ * ```
+ */
+type ExitNamesFor<FlowTags extends OutcomeTags, Payload> = { [Name in keyof FlowTags & string]: Accepts<Payload, PayloadOf<FlowTags[Name]>> extends true ? Name : never }[keyof FlowTags & string];
+/**
+ * Every correctly typed `to(node, map)` for `Payload`.
+ */
+type MappedFor<Nodes extends NodeTable, Payload> = { [Name in keyof Nodes & string]: Mapped<Name, Payload, InputOf<Nodes[Name]>> }[keyof Nodes & string];
+/**
+ * Descriptive type: every legal target of an outcome that carries `Payload`.
+ */
+type TargetFor<Nodes extends NodeTable, FlowTags extends OutcomeTags, Payload> = NodeNamesFor<Nodes, Payload> | Exit<ExitNamesFor<FlowTags, Payload>> | MappedFor<Nodes, Payload>;
+/**
+ * Descriptive type of an edge table: one entry per outcome of every node. Stored on
+ * `FlowDefinition` and read by tools; the check with readable errors is `CheckedEdges`.
+ *
+ * @example
+ * ```ts
+ * const edges: Edges<{ boot: typeof boot; home: typeof home }, Record<never, never>> = {
+ *   boot: { ready: "home" },
+ *   home: { play: "boot" }
+ * };
+ * ```
+ */
+type Edges<Nodes extends NodeTable, FlowTags extends OutcomeTags> = { readonly [Name in keyof Nodes]: { readonly [Outcome in keyof Nodes[Name]["outcomes"]]: TargetFor<Nodes, FlowTags, PayloadOf<Nodes[Name]["outcomes"][Outcome]>> } };
+/**
+ * A branded sentence. The compiler prints it in the "is not assignable to" position, so a wrong
+ * edge reads as a message with node and outcome names.
+ *
+ * @example
+ * ```ts
+ * type Problem = GraphError<'No node "awaitIntnet" in this flow (edge of outcome "done" of node "merge").'>;
+ * ```
+ */
+type GraphError<Message extends string> = {
+  readonly $graphError: Message;
+};
+/**
+ * The loosest legal target of a flow: what a missing entry is expected to be.
+ */
+type AnyTargetOf<Nodes extends NodeTable, FlowTags extends OutcomeTags> = (keyof Nodes & string) | Exit<keyof FlowTags & string> | Mapped<keyof Nodes & string, never, unknown>;
+/**
+ * Checks one entry `Value` of the inferred edge table. A legal entry stays itself; a wrong one
+ * becomes a `GraphError` sentence.
+ */
+type CheckTarget<Nodes extends NodeTable, FlowTags extends OutcomeTags, NodeName extends string, OutcomeName extends string, Payload, Value> = Value extends string ? Value extends keyof Nodes ? Accepts<Payload, InputOf<Nodes[Value]>> extends true ? Value : GraphError<`Payload of outcome "${OutcomeName}" of node "${NodeName}" does not fit the input of node "${Value}". Use to("${Value}", payload => ...).`> : GraphError<`No node "${Value}" in this flow (edge of outcome "${OutcomeName}" of node "${NodeName}").`> : Value extends Exit<infer ExitName> ? ExitName extends keyof FlowTags ? Accepts<Payload, PayloadOf<FlowTags[ExitName]>> extends true ? Value : GraphError<`Payload of outcome "${OutcomeName}" of node "${NodeName}" does not fit flow outcome "${ExitName}".`> : GraphError<`exit("${ExitName}"): the flow declares no outcome "${ExitName}".`> : Value extends Mapped<infer TargetName, never, unknown> ? TargetName extends keyof Nodes ? Mapped<TargetName, Payload, InputOf<Nodes[TargetName]>> : GraphError<`to("${TargetName}", ...): no node "${TargetName}" in this flow.`> : AnyTargetOf<Nodes, FlowTags>;
+/**
+ * Checking type: validates the inferred edge table `Table` entry by entry. It reports a missing
+ * edge, an unknown target, a payload that does not fit, an edge of an unknown outcome and an
+ * edge table row of an unknown node.
+ *
+ * @example
+ * ```ts
+ * type Spec = { edges: Table & CheckedEdges<Nodes, FlowTags, Table> };
+ * ```
+ */
+type CheckedEdges<Nodes extends NodeTable, FlowTags extends OutcomeTags, Table> = { readonly [Name in keyof Nodes & string]: { readonly [Outcome in keyof Nodes[Name]["outcomes"] & string]: Name extends keyof Table ? Outcome extends keyof Table[Name] ? CheckTarget<Nodes, FlowTags, Name, Outcome, PayloadOf<Nodes[Name]["outcomes"][Outcome]>, Table[Name][Outcome]> : AnyTargetOf<Nodes, FlowTags> : AnyTargetOf<Nodes, FlowTags> } & (Name extends keyof Table ? { readonly [Extra in Exclude<keyof Table[Name], keyof Nodes[Name]["outcomes"]> & string]: GraphError<`Node "${Name}" has no outcome "${Extra}".`> } : unknown) } & { readonly [Extra in Exclude<keyof Table, keyof Nodes> & string]: GraphError<`"${Extra}" is not a node of this flow.`> };
+/**
+ * A flow as `defineFlow` returns it: plain data. A flow that declares `input` and `outcomes`
+ * is used as a node of another flow.
+ *
+ * @example
+ * ```ts
+ * // What defineFlow("main", { nodes: { boot, home }, start: "boot", edges }) returns:
+ * // { kind: "flow", id: "main", input: { kind: "type" }, outcomes: {}, nodes: { boot, home },
+ * //   start: "boot", edges: { boot: { ready: "home" }, home: { play: "boot" } } }
+ * ```
+ */
+type FlowDefinition<Input, FlowTags extends OutcomeTags, Nodes extends NodeTable = NodeTable> = Wired<Input, FlowTags> & {
+  readonly kind: "flow";
+  readonly id: string;
+  readonly nodes: Nodes;
+  readonly start: keyof Nodes & string;
+  readonly edges: Edges<Nodes, FlowTags>;
+};
+/**
+ * What the author passes to `defineFlow`. `start` must name a node whose input accepts the flow
+ * input; `edges` is inferred as written and validated by `CheckedEdges`.
+ *
+ * @example
+ * ```ts
+ * // The spec of a sub-flow: `outcomes` makes it usable as a node, exit() leaves it.
+ * defineFlow("rewardPopup", {
+ *   nodes: { show, grant },
+ *   start: "show",
+ *   outcomes: { done: type() },
+ *   edges: { show: { claim: "grant" }, grant: { done: exit("done") } }
+ * });
+ * ```
+ */
+type FlowSpec<Nodes extends NodeTable, Input, FlowTags extends OutcomeTags, Table> = {
+  nodes: Nodes;
+  start: NodeNamesFor<NoInfer<Nodes>, NoInfer<Input>>;
+  edges: Table & CheckedEdges<NoInfer<Nodes>, NoInfer<FlowTags>, NoInfer<Table>>;
+  input?: TypeTag<Input>;
+  outcomes?: FlowTags;
+};
+/**
+ * The node context as the runner builds it. Every typed `NodeContext` is assignable to it.
+ */
+type AnyNodeContext = {
+  input: unknown;
+  player: unknown;
+  session: unknown;
+  rng: RngView;
+  fx: NodeFx;
+  out: Readonly<Record<string, (payload: never) => Result>>;
+  signal: AbortSignal;
+  now: number;
+};
+/**
+ * Any node as the runner holds it. `run` is a method on purpose: method parameters are compared
+ * bivariantly, so every typed `NodeDefinition` fits and the runner calls the body without a cast.
+ *
+ * @example
+ * ```ts
+ * const nodes: readonly AnyNode[] = [catchUp, merge];
+ * ```
+ */
+type AnyNode = AnyWired & {
+  readonly kind: "node";
+  readonly rest: boolean;
+  readonly over: boolean;
+  readonly checkpoint: boolean;
+  readonly barrier: boolean;
+  readonly inbox: readonly string[]; /** Id of the scene the node is shown on. Absent: the node keeps the current scene. */
+  readonly scene?: string;
+  run?(ctx: AnyNodeContext): Result | Promise<Result>;
+};
+/**
+ * One entry of a flow's `nodes`: a node, a sub-flow or a slot. The `kind` field tells them apart.
+ */
+type FlowEntry = AnyNode | AnyFlow | SlotNode;
+/**
+ * Any flow as the runner holds it. Every typed `FlowDefinition` fits.
+ *
+ * @example
+ * ```ts
+ * const flows: readonly AnyFlow[] = [mainFlow, boardFlow, rewardFlow];
+ * ```
+ */
+type AnyFlow = AnyWired & {
+  readonly kind: "flow";
+  readonly id: string;
+  readonly nodes: Readonly<Record<string, FlowEntry>>;
+  readonly start: string;
+  readonly edges: Readonly<Record<string, Readonly<Record<string, Target>>>>;
+};
+/**
+ * One level of the position. The path is the frames joined: `"board/awaitIntent"`.
+ *
+ * @example
+ * ```ts
+ * const frame: Frame = { flow: "board", node: "awaitIntent", input: null };
+ * ```
+ */
+type Frame = {
+  flow: string;
+  node: string;
+  input: Json;
+};
+/**
+ * One taken edge. `hash` covers `path + outcome + next`, so a replay against edited code fails
+ * loudly in dev.
+ *
+ * @example
+ * ```ts
+ * // The play button on "home" led into the board sub-flow.
+ * const entry: JournalEntry = {
+ *   index: 1, path: "home", outcome: "play", payload: null,
+ *   next: "board/awaitIntent", now: 1_790_000_000_000, hash: "fbeb1a2f"
+ * };
+ * ```
+ */
+type JournalEntry = {
+  index: number;
+  path: string;
+  outcome: string;
+  payload: Json;
+  next: string;
+  now: number;
+  hash: string;
+};
+/**
+ * One step of a fast walk: a player answer at a rest node, or a substituted sub-flow result.
+ *
+ * @example
+ * ```ts
+ * const route: RouteStep[] = [
+ *   { at: "home", intent: "play" }, // the answer "play" at the rest node "home"
+ *   { at: "board", result: { outcome: "left" } } // the sub-flow "board" is skipped with "left"
+ * ];
+ * ```
+ */
+type RouteStep = {
+  at: string;
+  intent: string;
+  payload?: Json;
+} | {
+  at: string;
+  result: {
+    outcome: string;
+    payload?: Json;
+  };
+};
+/**
+ * A rest node plus a state that really existed there. Serialisable. `graph` is the hash of
+ * `describe()`.
+ *
+ * @example
+ * ```ts
+ * const bookmark: Bookmark = {
+ *   path: "board/awaitIntent", input: null,
+ *   player: { coins: 7 }, session: { taps: 0 },
+ *   rng: { seed: 42, streams: {} }, graph: "fe4d257a"
+ * };
+ * ```
+ */
+type Bookmark = {
+  path: string;
+  input: Json;
+  player: Json;
+  session: Json;
+  rng: RngState;
+  graph: string;
+};
+/**
+ * What `onEnter` callbacks learn about the node being entered.
+ *
+ * @example
+ * ```ts
+ * // The rest node "awaitIntent" of the sub-flow "board" is being entered.
+ * const node: NodeInfo = {
+ *   path: "board/awaitIntent", flow: "board", node: "awaitIntent",
+ *   rest: true, over: false, checkpoint: false, barrier: false, scene: "board"
+ * };
+ * ```
+ */
+type NodeInfo = {
+  path: string;
+  flow: string;
+  node: string;
+  rest: boolean;
+  over: boolean;
+  checkpoint: boolean;
+  barrier: boolean; /** Id of the scene the node is shown on: `scenes` switches on it, `assets` pins its bundle. */
+  scene?: string;
+};
+/**
+ * The whole graph as JSON. Edge targets are rendered as strings: `"node"`, `"exit:win"`,
+ * `"map:node"`.
+ *
+ * @example
+ * ```ts
+ * const graph: FlowGraph = app.flow.describe();
+ *
+ * graph.main; // "main"
+ * graph.flows.board?.edges.awaitIntent?.leave; // "exit:left"; a mapped target reads "map:node"
+ * graph.slots.afterOrder; // [{ feature: "reward", flow: "rewardPopup", order: 10 }]
+ * ```
+ */
+type FlowGraph = {
+  main: string;
+  flows: Record<string, {
+    nodes: Record<string, GraphNode>;
+    start: string;
+    edges: Record<string, Record<string, string>>;
+  }>;
+  slots: Record<string, {
+    feature: string;
+    flow: string;
+    order: number;
+  }[]>;
+};
+/**
+ * One node of `describe()`: its flags, its scene, its outcome names and, when it is one, the slot
+ * it opens, the sub-flow it enters and the feature that brought it. It has no `path`: a static
+ * description has no runtime position, and `flow` plus `node` address it.
+ *
+ * @example
+ * ```ts
+ * // app.flow.describe().flows.main?.nodes.board: the sub-flow "board" used as a node of "main".
+ * const node: GraphNode = {
+ *   flow: "main", node: "board",
+ *   rest: false, over: false, checkpoint: false, barrier: false,
+ *   outcomes: ["orderComplete", "left"], subFlow: "board"
+ * };
+ * ```
+ */
+type GraphNode = Omit<NodeInfo, "path"> & {
+  outcomes: string[];
+  slot?: string;
+  subFlow?: string;
+  owner?: string;
+};
+/**
+ * Inspection of the running graph.
+ *
+ * @example
+ * ```ts
+ * // The graph rests at "home" and waits for the intent "play".
+ * const state: FlowState = {
+ *   running: true, path: "home", stack: [{ flow: "main", node: "home", input: null }],
+ *   pending: { gate: ["play"] }, mode: "live"
+ * };
+ * ```
+ */
+type FlowState = {
+  running: boolean;
+  path: string;
+  stack: readonly Frame[];
+  pending: {
+    fx?: string;
+    gate?: readonly string[];
+  };
+  mode: "live" | "fast";
+};
+/**
+ * Stages of entering a node: `assets` preloads at `load`, `scenes` switches at `scene`.
+ *
+ * @example
+ * ```ts
+ * const stage: Stage = "load";
+ * ```
+ */
+type Stage = "load" | "scene";
+/**
+ * Callback of `onEnter`. Called before `node.run`, awaited.
+ *
+ * @example
+ * ```ts
+ * // The "load" stage of a game plugin: the loop waits for it before the body of the node runs.
+ * const preloadNode: EnterCallback = async (node, { signal }) => {
+ *   if (node.flow === "board") await preloadBoard(signal); // node.path: "board/awaitIntent"
+ * };
+ *
+ * app.flow.onEnter("load", preloadNode);
+ * ```
+ */
+type EnterCallback = (node: NodeInfo, ctx: {
+  mode: "live" | "fast";
+  signal: AbortSignal;
+}) => void | Promise<void>;
+/**
+ * The seam the fast walk and `restore` steer the running loop with. It stays absent while the
+ * game just runs: `walk.ts` and `restore` create it through `loopSeam` when they need it.
+ */
+type LoopSeam = {
+  /** Sub-flow results a walk substitutes, by path. The loop takes each one once. */substitutions: Map<string, Result>; /** Called with the path every time the loop enters a rest node. */
+  rest: ((path: string) => void)[]; /** Called every time the loop opens the gate of a rest node. The walk waits on it. */
+  gateOpen: (() => void)[]; /** The bookmark the loop enters at the next turn. */
+  restoring: Bookmark | undefined;
+};
+/**
+ * runner module state.
+ */
+type RunnerState = {
+  /** Flush started by a background pause. `onStop` awaits it. */flushing: Promise<void> | undefined; /** Every flow of the graph by id, collected at `run()`. */
+  flows: Map<string, AnyFlow>;
+  enterCallbacks: Record<Stage, EnterCallback[]>; /** The position: one frame per nesting level. */
+  stack: Frame[]; /** The stack of the last rest node: the rollback target. */
+  restFrame: Frame[] | undefined; /** Inside a slot: the contribution the loop just finished. The slot continues after it. */
+  slotAfter: string | undefined; /** Edges since the last checkpoint. */
+  journal: JournalEntry[];
+  journalIndex: number; /** The promise of `run()`. `undefined`: not started. */
+  running: Promise<void> | undefined; /** Aborts the active node. */
+  abort: AbortController | undefined; /** Failed transitions in a row. */
+  failures: number; /** How `walk` and `restore` steer the loop. Absent until one of them needs it. */
+  seam?: LoopSeam; /** The last `state()` and what it was read from. Absent until the first `state()`. */
+  view?: StateView;
+};
+/**
+ * The last `flow.state()` and the fields it was built from. `state()` hands the same frozen
+ * object out again while none of them moved, so a watcher compares identities.
+ */
+type StateView = {
+  running: boolean;
+  depth: number;
+  top: Frame | undefined;
+  open: GateSpec | undefined;
+  mode: "live" | "fast";
+  journalIndex: number;
+  state: FlowState;
+};
+/**
+ * runner module API. Its methods are spread onto the plugin root: `app.flow.run()`. `run` owns
+ * the one loop, `walk` and `restore` enter a position through it, `describe`, `state` and
+ * `history` inspect it.
+ *
+ * @example
+ * ```ts
+ * // A live game starts the graph once and then only reads it: answers go through the gate.
+ * app.flow.run().catch(showFatal);
+ * app.flow.state().path; // "home", once the transit node "boot" was played out
+ * ```
+ */
+type RunnerApi = {
+  /**
+   * Validates the graph, seals the features, loads the save and runs the one loop until `onStop`
+   * aborts it. A fatal error rejects: the consumer catches it.
+   *
+   * @returns The promise of the running graph. It resolves when the app stops.
+   * @throws {Error} When `run()` was already called.
+   * @example
+   * ```ts
+   * // The game starts the graph from onStart and does not await it: the loop never ends.
+   * createApp({
+   *   pluginConfigs: { flow: { mainFlow, safeNode: "home" } },
+   *   onStart: ctx => {
+   *     ctx.flow.run().catch(showFatal); // a broken graph or an unreadable save ends up here
+   *   }
+   * });
+   * ```
+   */
+  run(): Promise<void>;
+  /**
+   * Registers a callback run before every node body: `assets` preloads at `load`, `scenes`
+   * switches at `scene`. Every `load` callback runs before the first `scene` callback, in
+   * registration order, each awaited.
+   *
+   * @param stage - `"load"` or `"scene"`.
+   * @param callback - Called with the node and `{ mode, signal }`, awaited.
+   * @returns The unregister function.
+   * @example
+   * ```ts
+   * // A scenes plugin switches the screen when the graph enters a node.
+   * const off = app.flow.onEnter("scene", node => showScene(node.path)); // node.path: "home"
+   *
+   * off(); // the plugin stops: the callback is not called any more
+   * ```
+   */
+  onEnter(stage: Stage, callback: EnterCallback): () => void;
+  /**
+   * Walks a route in fast mode through the running loop: it answers the gate at each step's `at`
+   * and substitutes the result of every sub-flow node the route skips. A `from` bookmark is
+   * entered through the same check as `restore`. The mode of the caller is put back afterwards.
+   *
+   * @param route - The player's answers and substituted sub-flow results, in order.
+   * @param options - Walk options.
+   * @param options.from - Bookmark restored before the first step.
+   * @returns The state the walk ended in.
+   * @throws {Error} Before `run()` was called, when the bookmark is refused, and when a step's
+   *   `at` is never reached.
+   * @example
+   * ```ts
+   * // A test skips the menu and stands on the board, without a screen and without waiting.
+   * const state = await app.flow.walk([{ at: "home", intent: "play" }]);
+   * state.path; // "board/awaitIntent"
+   *
+   * // Devtools jump back to a saved position and leave the board from there.
+   * await app.flow.walk([{ at: "board/awaitIntent", intent: "leave" }], { from: bookmark });
+   * ```
+   */
+  walk(route: readonly RouteStep[], options?: {
+    from?: Bookmark;
+  }): Promise<FlowState>;
+  /**
+   * Makes a bookmark of the current rest point: the rest node plus the committed state.
+   *
+   * @returns The bookmark, ready for JSON.
+   * @throws {Error} When the graph has no position yet.
+   * @example
+   * ```ts
+   * // A devtools button keeps the position while the board rests.
+   * const bookmark = app.flow.bookmark();
+   * bookmark.path; // "board/awaitIntent"
+   * JSON.stringify(bookmark); // plain data: path, input, player, session, rng and the graph hash
+   * ```
+   */
+  bookmark(): Bookmark;
+  /**
+   * Replaces the state with the bookmark's and enters its node. A checkpoint is always
+   * accepted; any other rest node only while the graph is unchanged.
+   *
+   * @param bookmark - The bookmark to enter.
+   * @returns A promise that resolves once the graph rests at the bookmark's node.
+   * @throws {Error} When the bookmark names no rest node of this graph, when the graph changed
+   *   since a bookmark of a plain rest node, and before `run()`.
+   * @example
+   * ```ts
+   * // The next session opens where the last one stopped: state and position come back together.
+   * await app.flow.restore(bookmark);
+   * app.flow.state().path; // "board/awaitIntent"
+   * ```
+   */
+  restore(bookmark: Bookmark): Promise<void>;
+  /**
+   * Renders the whole graph as JSON, without running the game. It reads the flows as data, so
+   * it works before `run()`.
+   *
+   * @returns Nodes, flags, outcomes, edges, slots and who contributed.
+   * @example
+   * ```ts
+   * // A devtools panel draws the graph of the merge game.
+   * const graph = app.flow.describe();
+   *
+   * graph.flows.main?.edges.home; // { play: "board" }
+   * graph.flows.board?.nodes.merge?.outcomes; // ["done", "rejected"]
+   * ```
+   */
+  describe(): FlowGraph;
+  /**
+   * Reads where the graph stands. Frozen, and the same object while the graph did not move: no
+   * edge, no gate opened or closed, no mode switch.
+   *
+   * @returns Whether it runs, the path, the stack, what it waits for and the mode.
+   * @example
+   * ```ts
+   * // The screen enables only the buttons the resting node takes.
+   * const { path, pending } = app.flow.state();
+   * // path: "home", pending: { gate: ["play"] }
+   *
+   * // An editor panel redraws the position only when the graph moved.
+   * app.flow.state() === app.flow.state(); // true while "home" rests
+   * ```
+   */
+  state(): FlowState;
+  /**
+   * Reads the edges taken since the last checkpoint.
+   *
+   * @returns A copy of the journal.
+   * @example
+   * ```ts
+   * // A bug report says why the last move was refused.
+   * const last = app.flow.history().at(-1);
+   * // last?.path: "board/merge", last?.outcome: "rejected", last?.payload: { reason: "empty" }
+   * ```
+   */
+  history(): readonly JournalEntry[];
+  /**
+   * Switches between live and fast mode. Legal before `run()` and while the graph rests.
+   *
+   * @param mode - `"live"` or `"fast"`.
+   * @throws {Error} When a transit node is running.
+   * @example
+   * ```ts
+   * // A headless run plays without effects: fast mode before the app starts.
+   * app.flow.setMode("fast");
+   * await app.start();
+   * app.flow.state().mode; // "fast"
+   * ```
+   */
+  setMode(mode: "live" | "fast"): void;
+};
+//#endregion
+//#region src/plugins/flow/features/types.d.ts
+/**
+ * One animation of a feature, as `defineAnimation` returns it. Structural on purpose: `flow`
+ * stores what the game brought and never imports `anim`, which reads the rest of the object.
+ *
+ * @example
+ * ```ts
+ * const coinsFly: FeatureAnimation = { id: "coinsFly" };
+ * ```
+ */
+type FeatureAnimation = {
+  readonly id: string;
+};
+/**
+ * One interface component of a feature, as `defineComponent` returns it. Structural on purpose:
+ * `ui` reads the rest of the object, `flow` only carries it.
+ *
+ * @example
+ * ```ts
+ * const rewardPopup: FeatureComponent = { name: "RewardPopup" };
+ * ```
+ */
+type FeatureComponent = {
+  readonly name: string;
+};
+/**
+ * The compiled messages of one locale: message key to what `compileStrings` wrote for it. The
+ * value stays opaque here because only `i18n` calls it; `flow` passes the module on untouched.
+ *
+ * @example
+ * ```ts
+ * const en: CompiledMessagesLike = { "board.title": () => [{ kind: "text", text: "Board" }] };
+ * ```
+ */
+type CompiledMessagesLike = {
+  readonly [key: string]: unknown;
+};
+/**
+ * The text styles of a feature, as `defineTextStyles` returns them. Structural on purpose: `text`
+ * reads the fields of each style, `flow` only carries the map.
+ *
+ * @example
+ * ```ts
+ * const styles: FeatureTextStyles = { kind: "textStyles", map: { title: { size: 24 } } };
+ * ```
+ */
+type FeatureTextStyles = {
+  readonly kind: "textStyles";
+  readonly map: Record<string, object>;
+};
+/**
+ * What a feature brings to the game. The logic keys are typed here; the keys of later milestones
+ * pass through the index signature until their plugin types them. `flow` stores them untouched,
+ * and `logicOnly` drops them. The V2 screen plugins read five of them through the index signature:
+ * `projections`, `systems` and `components` (`world`), `scenes` (`scenes`, `assets`, and the
+ * scene-id check of `flow`) and `assets` (`assets`). The V3 interface keys are typed below.
+ *
+ * @example
+ * ```ts
+ * const description: FeatureDescription = {
+ *   flows: [rewardFlow],
+ *   contribute: { afterWin: { flow: rewardFlow, order: 10 } }
+ * };
+ * ```
+ */
+type FeatureDescription = {
+  /** Nodes the feature owns. Recorded for `describe()` and hot swap. */nodes?: readonly AnyNode[]; /** Flows the feature owns. */
+  flows?: readonly AnyFlow[]; /** Slot name to the sub-flow run in that slot. */
+  contribute?: Record<string, {
+    flow: AnyFlow;
+    order: number;
+    when?: (snapshot: Snapshot) => boolean;
+  }>; /** Animations the feature owns, read by `anim`. */
+  animations?: readonly FeatureAnimation[]; /** Interface components the feature owns, read by `ui`. `components` stays the ECS key. */
+  ui?: readonly FeatureComponent[]; /** Compiled messages per locale, ready or lazy, read by `i18n`. */
+  strings?: Record<string, CompiledMessagesLike | (() => Promise<unknown>)>; /** Text styles the feature owns, read by `text`. */
+  textStyles?: FeatureTextStyles;
+  [later: string]: unknown;
+};
+/**
+ * One sub-flow contributed to a slot.
+ *
+ * @example
+ * ```ts
+ * const contribution: Contribution = { feature: "reward", flow: rewardFlow, order: 10 };
+ * ```
+ */
+type Contribution = {
+  feature: string;
+  flow: AnyFlow;
+  order: number;
+  when?: (snapshot: Snapshot) => boolean;
+};
+/**
+ * features module state.
+ */
+type FeaturesState = {
+  byName: Map<string, FeatureDescription>; /** True after `run()`: `register` throws. */
+  sealed: boolean;
+};
+/**
+ * features module API, `app.flow.features`: the registry every feature plugin writes itself into.
+ *
+ * @example
+ * ```ts
+ * // The game composed `rewardFeature`. A plugin above asks in its onStart what the game brought.
+ * app.flow.features.all().map(feature => feature.name); // ["reward"]
+ * ```
+ */
+type FeaturesApi = {
+  /**
+   * Records what a feature brings. Called from the feature plugin's `onInit`, so every feature
+   * is known before the graph is validated.
+   *
+   * @param name - Feature name. Shares the namespace with plugin names.
+   * @param description - Nodes, flows and slot contributions of the feature.
+   * @throws {Error} After `run()` sealed the registry, and for a duplicate name.
+   * @example
+   * ```ts
+   * // A hand-written feature plugin registers itself in onInit. `defineFeature` does the same.
+   * const rewardPlugin = createPlugin("reward", {
+   *   depends: [flowPlugin],
+   *   onInit: ctx => ctx.require(flowPlugin).features.register("reward", { flows: [rewardFlow] })
+   * });
+   * ```
+   */
+  register(name: string, description: FeatureDescription): void;
+  /**
+   * Lists every registered feature in registration order. Plugins above read it in their
+   * `onStart` to pick up what they own.
+   *
+   * @returns A fresh list of name and description.
+   * @example
+   * ```ts
+   * // A plugin above collects the flows of every feature.
+   * app.flow.features.all(); // [{ name: "reward", description: { flows: [rewardFlow] } }]
+   * ```
+   */
+  all(): readonly {
+    name: string;
+    description: FeatureDescription;
+  }[];
+  /**
+   * Lists the sub-flows contributed to one slot, lowest `order` first. Two equal orders in one
+   * slot stay in registration order here and are reported by `validate`.
+   *
+   * @param slotName - Name of the slot node.
+   * @returns The contributions of that slot, sorted by `order`.
+   * @example
+   * ```ts
+   * // What runs when the graph enters slot("afterOrder").
+   * app.flow.features.contributions("afterOrder");
+   * // [{ feature: "reward", flow: rewardFlow, order: 10 }]
+   * app.flow.features.contributions("afterLoss"); // []: no feature contributes to this slot
+   * ```
+   */
+  contributions(slotName: string): readonly Contribution[];
+};
+//#endregion
+//#region src/plugins/flow/runner/define.d.ts
+/**
+ * Creates a type tag: a value that carries only a payload type. Without a type argument the
+ * payload is `void`. The tag never infers its type from the place it is written in.
+ *
+ * @returns A tag that carries the payload type and no value.
+ * @example
+ * ```ts
+ * // The outcomes of a node: `done` carries nothing, `orderComplete` carries the reward id.
+ * const outcomes = { done: type(), orderComplete: type<{ rewardId: string }>() };
+ * // outcomes.done: { kind: "type" }. The payload type exists for the compiler only.
+ * ```
+ */
+declare function type<Payload = void>(): TypeTag<NoInfer<Payload>>;
+/**
+ * Defines a flow. The edge table is inferred as written and checked entry by entry: a missing
+ * edge, an unknown target and a payload that does not fit are compile errors with a sentence.
+ *
+ * @param id - Flow id, unique in the game.
+ * @param spec - Nodes, start node, edge table, and input and outcomes when used as a node.
+ * @returns The flow as plain data.
+ * @example
+ * ```ts
+ * // The main flow of a dice game. A missing edge or an unknown target is a compile error.
+ * const mainFlow = defineFlow("main", {
+ *   nodes: { home, roll },
+ *   start: "home",
+ *   edges: { home: { roll: "roll" }, roll: { done: "home" } }
+ * });
+ * ```
+ */
+declare function defineFlow<Nodes extends NodeTable, Input = void, const FlowTags extends OutcomeTags = Record<never, never>, const Table = Record<never, never>>(id: string, spec: FlowSpec<Nodes, Input, FlowTags, Table>): FlowDefinition<Input, FlowTags, Nodes>;
+/**
+ * Edge target: leave the sub-flow with this outcome. The payload passes through to the parent.
+ *
+ * @param outcome - Outcome declared by the flow.
+ * @returns The exit target as plain data.
+ * @example
+ * ```ts
+ * // Inside the sub-flow "board": the intent "leave" ends the flow with its outcome "left".
+ * edges: { awaitIntent: { leave: exit("left") } } // the target: { kind: "exit", outcome: "left" }
+ * // The parent flow then follows its own edge: board: { left: "home" }.
+ * ```
+ */
+declare function exit<const Name extends string>(outcome: Name): Exit<Name>;
+/**
+ * Edge target: adapt the payload on the edge. The mapper's parameter is annotated by the author;
+ * the annotation is checked against the outcome payload, the result against the target's input.
+ *
+ * @param target - Name of a node of the same flow.
+ * @param map - Pure function from the outcome payload to the target's input.
+ * @returns The mapped target as plain data.
+ * @example
+ * ```ts
+ * // "loadCore" fails with { reason }, "retry" takes { why }: the edge adapts the payload.
+ * edges: { loadCore: { failed: to("retry", (failure: { reason: string }) => ({ why: failure.reason })) } }
+ * // to("retry", map): { kind: "map", target: "retry", map }
+ * ```
+ */
+declare function to<const TargetName extends string, Payload, Output>(target: TargetName, map: (payload: Payload) => Output): Mapped<TargetName, Payload, Output>;
+/**
+ * Defines an extension point: a node whose body is "run the contributions of this slot in order".
+ * Its single outcome is `done`.
+ *
+ * @param name - Slot name features contribute to.
+ * @returns The slot node as plain data.
+ * @example
+ * ```ts
+ * // The main flow leaves room after a finished order. Features contribute sub-flows to it.
+ * nodes: { boot, home, board: boardFlow, afterOrder: slot("afterOrder") }
+ * // slot("afterOrder"): { kind: "slot", name: "afterOrder", input: …, outcomes: { done: … } }
+ * ```
+ */
+declare function slot(name: string): SlotNode;
+declare namespace types_d_exports {
+  export { Allow, Answer, AnyFlow, AnyNode, AnyNodeContext, Api, Bookmark, BundlesOf, CheckedEdges, Config, Contribution, DefineNode, Deps, Descriptor, Edges, EnterCallback, Events, Exit, FeatureDescription, FeaturePlugin, FeaturesApi, FlowCtx, FlowDefinition, FlowGraph, FlowKit, FlowSpec, FlowState, FxApi, FxHandler, GameState, GameTypes, GateApi, GraphError, GraphNode, GuideOptions, Hint, InboxApi, JournalEntry, KernelSlice, LifecycleChanged, Mapped, NodeContext, NodeDefinition, NodeFx, NodeInfo, NodeSpec, OutcomeTags, Position, Result, RouteStep, RunnerApi, SceneIdOf, SlotNode, Stage, State, Target, TextStylesOf, TypeTag, WorldEvent };
+}
+/**
+ * flow plugin events.
+ *
+ * @example
+ * ```ts
+ * // A plugin that depends on flowPlugin logs every edge the player takes.
+ * createPlugin("edgeLog", {
+ *   depends: [flowPlugin],
+ *   hooks: ctx => ({ "flow:edge": ({ node, outcome }) => ctx.log.info("edge", { node, outcome }) })
+ * }); // the play button on "home" logs { node: "home", outcome: "play" }
+ * ```
+ */
+type Events = {
+  /** An edge was taken and its state committed. */"flow:edge": {
+    flow: string;
+    node: string;
+    outcome: string;
+    payload: Json;
+    next: string;
+    patches: {
+      doc: Patch[];
+      session: Patch[];
+    };
+    index: number;
+    now: number;
+  }; /** The graph reached a rest node. */
+  "flow:rest": {
+    path: string;
+    checkpoint: boolean;
+  }; /** A node failed and the graph rolled back. */
+  "flow:error": {
+    path: string;
+    error: unknown;
+    rolledBackTo: string;
+    retry: boolean;
+  };
+};
+/**
+ * flow plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { flow: { mainFlow, safeNode: "home" } } });
+ * ```
+ */
+type Config = {
+  /** The top-level flow. Required before `run()`. */mainFlow: AnyFlow | undefined; /** Path of the checkpoint entered after a failed retry. `undefined`: the main flow's `start`. */
+  safeNode: string | undefined; /** Retries of a failed transition before going to `safeNode`. */
+  retries: number; /** How long `onStop` waits for the active node to settle after abort, in real milliseconds. */
+  settleTimeoutMs: number; /** Journal entries kept between checkpoints. */
+  journalLimit: number;
+};
+/**
+ * flow plugin state: one branch per module.
+ */
+type State = {
+  features: FeaturesState;
+  fx: FxState;
+  gate: GateState;
+  inbox: InboxState;
+  runner: RunnerState;
+};
+/**
+ * flow plugin API, `app.flow`: the runner on the root, the other modules grouped.
+ *
+ * @example
+ * ```ts
+ * // The game starts the graph once. After that only answers and world events move it.
+ * app.flow.run().catch(showFatal);
+ *
+ * app.flow.gate.answer({ intent: "play" }); // the play button: true when "home" rests
+ * app.flow.inbox.post({ type: "purchased" }); // the shop SDK: waits for a node that lists it
+ * ```
+ */
+type Api = RunnerApi & {
+  gate: GateApi;
+  inbox: InboxApi;
+  fx: FxApi;
+  features: FeaturesApi;
+};
+/**
+ * The APIs flow requires from below (`time`, `model`, `clock`), resolved once in `onInit` and
+ * shared by the runner, gate, inbox and fx.
+ */
+type Deps = {
+  time: Api$1;
+  model: Api$2;
+  clock: Api$4;
+};
+/**
+ * What the kernel context offers before the deps are attached. `emit` is the kernel's: `index.ts`
+ * writes `events` with an annotated `register` (core spec `14` row 8), so the own events reach a
+ * factory passed by direct reference (`api`, `hooks`, `onInit`, `onStart`).
+ */
+type KernelSlice = PluginCtx<Config, State, Events> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the modules.
+ */
+type FlowCtx = KernelSlice & {
+  readonly deps: Deps;
+};
+/**
+ * Payload of the one event flow listens to.
+ */
+type LifecycleChanged = Events$2["lifecycle:changed"];
+/**
+ * The types of one game. `player` and `session` type the node context; `assets` and `bundles`
+ * are the key unions the asset scanner generates (`string` while a game has none); `strings`
+ * is used from V3. Every plugin binds its own helpers to them through its `…For` binder.
+ *
+ * @example
+ * ```ts
+ * type Types = { player: Player; session: Session; assets: AssetKey; bundles: BundleKey; strings: StringTable };
+ * ```
+ */
+type GameTypes = {
+  player: Json;
+  session: Json;
+  assets: string;
+  bundles?: string;
+  scenes?: string;
+  strings: Record<string, unknown>;
+  textStyles?: string;
+};
+/**
+ * The text style key union of a game, `string` when the game passed none.
+ *
+ * @example
+ * ```ts
+ * type Keys = TextStylesOf<{ player: {}; session: {}; assets: string; strings: {}; textStyles: "hud.digits" }>; // "hud.digits"
+ * ```
+ */
+type TextStylesOf<Types extends GameTypes> = Types extends {
+  textStyles: infer Keys extends string;
+} ? Keys : string;
+/**
+ * The bundle key union of a game, `string` when the game passed none.
+ *
+ * @example
+ * ```ts
+ * type Keys = BundlesOf<{ player: {}; session: {}; assets: string; bundles: "board"; strings: {} }>; // "board"
+ * ```
+ */
+type BundlesOf<Types extends GameTypes> = Types extends {
+  bundles: infer Keys extends string;
+} ? Keys : string;
+/**
+ * A feature is an ordinary plugin with no API of its own; `AnyPluginInstance` is the kernel's
+ * widened type for plugin lists. `logicOnly` is the same plugin reduced to the V1 keys.
+ *
+ * @example
+ * ```ts
+ * createApp({ plugins: [boardFeature.logicOnly] });
+ * ```
+ */
+type FeaturePlugin = AnyPluginInstance & {
+  readonly logicOnly: AnyPluginInstance;
+};
+/**
+ * What `flowFor` binds to a game: the node helper with the game's `player` and `session`, and
+ * the flow and feature helpers, which take no game types.
+ *
+ * @example
+ * ```ts
+ * const { defineNode } = flowFor<{ player: Player; session: Session }>();
+ * defineNode({ rest: true, outcomes: { play: type() }, run: ({ player }) => player.coins }); // player: Player
+ * ```
+ */
+type FlowKit<Game extends GameState> = {
+  defineNode: DefineNode<Game>;
+  defineFlow: typeof defineFlow;
+  defineFeature: (name: string, description: FeatureDescription) => FeaturePlugin;
+};
+/**
+ * Where the graph rests, as the `game.position` source reads it: the path, the flow and node on
+ * top of the stack, and the intents the open gate waits for.
+ *
+ * @example
+ * ```ts
+ * // The board rests and waits for a tap or for leaving.
+ * const position: Position = {
+ *   path: "board/awaitIntent", flow: "board", node: "awaitIntent", waiting: ["tap", "leave"]
+ * };
+ * ```
+ */
+type Position = {
+  path: string;
+  flow: string | undefined;
+  node: string | undefined;
+  waiting: readonly string[];
+};
+//#endregion
+export { PauseReason as $, Config$1 as A, types_d_exports$2 as B, SceneIdOf as C, Hint as D, GuideOptions as E, Config$2 as F, SaveUnreadableError as G, PlayerStateProvider as H, Events$1 as I, RngApi as J, Snapshot as K, Json as L, Time as M, types_d_exports$1 as N, Answer as O, Api$2 as P, Events$2 as Q, Root as R, RouteStep as S, Descriptor as T, ProviderCall as U, Patch as V, SaveDoc as W, Api$3 as X, RngState as Y, Config$3 as Z, DefineNode as _, GameTypes as a, State$4 as at, JournalEntry as b, TextStylesOf as c, Events$3 as ct, exit as d, State$3 as et, slot as f, Bookmark as g, FeatureDescription as h, FeaturePlugin as i, FakeClock as it, State$1 as j, Api$1 as k, types_d_exports as l, Require as lt, type as m, BundlesOf as n, Api$4 as nt, Position as o, types_d_exports$4 as ot, to as p, StoreApi as q, Config as r, Config$4 as rt, State as s, Config$5 as st, Api as t, types_d_exports$3 as tt, defineFlow as u, FlowGraph as v, TypeTag as w, NodeInfo as x, FlowState as y, State$2 as z };