@moku-labs/game 0.13.2 → 0.13.3

package/dist/testing.d.mts

@@ -1,7 +1,7 @@
-import { Dt as AnyFlow, Ht as ClockSource, Nt as NodeTable, Wt as FakeClock, Xt as Json, ht as FeaturePlugin } from "./types-C6y8EfEB.mjs";
-import { t as createApp } from "./index-CdbE_jGs.mjs";
-import { n as saveOf, t as memory } from "./memory-DJ2sPExv.mjs";
-import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro, r as Repro, s as stepFrames, t as HeadlessApp } from "./headless-Dgxvp6Ym.mjs";
+import { Dt as AnyFlow, Ht as ClockSource, Nt as NodeTable, Wt as FakeClock, Xt as Json, ht as FeaturePlugin } from "./types-BSMmnpFm.mjs";
+import { t as createApp } from "./index-CjuObHhF.mjs";
+import { n as saveOf, t as memory } from "./memory-DKo9rRWW.mjs";
+import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro, r as Repro, s as stepFrames, t as HeadlessApp } from "./headless-CYgYzro0.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/clock/fake.d.ts

package/dist/testing.mjs

@@ -1,7 +1,7 @@
-import { Kt as type, Ut as exit, t as createApp } from "./src-CltFFKtc.mjs";
+import { Kt as type, Ut as exit, t as createApp } from "./src-DlyYl_9X.mjs";
 import { n as saveOf, t as memory } from "./memory-CWlqhS7l.mjs";
 import { t as fakeClock } from "./fake-MpzwZhIZ.mjs";
-import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-BsNdJs9W.mjs";
+import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-BA6ffzqD.mjs";
 //#region src/testing/isolate.ts
 const noPayload = null;
 /** Id of the harness main flow. */

package/dist/{types-C6y8EfEB.d.mts → types-BSMmnpFm.d.mts}

@@ -836,7 +836,9 @@ type StoreState = {
 /**
  * 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.
+ * transition and never half of one. One restore differs: `flow.restore` of a bookmark taken at a
+ * transit node marks a rest point there, so the provider receives a document from between two rest
+ * nodes, and a kill right after it loads that state at the start node.
  *
  * @example
  * ```ts
@@ -2139,20 +2141,21 @@ type RouteStep = {
   };
 };
 /**
- * A rest node plus a state that really existed there. Serialisable. `graph` is the hash of
- * `describe()`.
+ * A node plus a state that really existed there. Serialisable. `path` names a rest node, or a
+ * transit node that waited at the gate for the answer of an effect (a popup); for the second the
+ * state is the one committed when the node was entered. `graph` is the hash of `describe()`.
  *
  * @example
  * ```ts
+ * // Taken while the info popup of the mini game waits for its answer, opened from "home".
  * const bookmark: Bookmark = {
- *   path: "board/awaitIntent", input: null,
- *   player: { coins: 7 }, session: { taps: 0 },
- *   rng: { seed: 42, streams: {} }, graph: "fe4d257a"
+ *   path: "info/show", input: null, player: { count: 0 }, session: { opened: 0 },
+ *   rng: { seed: 42, streams: {} }, graph: "0e0d2aa8", rest: { path: "home", input: null }
  * };
  * ```
  */
 type Bookmark = {
-  path: string;
+  /** Path of a rest node, or of a transit node that waited at the gate. */path: string;
   input: Json;
   player: Json;
   session: Json;
@@ -2163,6 +2166,15 @@ type Bookmark = {
    * `game.restore`; `flow.restore` ignores it.
    */
   scene?: string;
+  /**
+   * The rest point before a transit `path`: the last rest node and its input. `restore` enters
+   * it instead when the graph changed since the bookmark. Absent for a bookmark of a rest node,
+   * and when no rest node came before the transit node.
+   */
+  rest?: {
+    path: string;
+    input: Json;
+  };
 };
 /**
  * What `onEnter` callbacks learn about the node being entered.
@@ -2286,8 +2298,16 @@ type EnterCallback = (node: NodeInfo, ctx: {
  * 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. */
+  /** 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, and once when it enters the
+   * node of a bookmark, which may be a transit node. `restore` resolves on the second.
+   */
+  rest: ((path: string) => void)[];
+  /**
+   * Called every time the loop opens a gate: the wait of a rest node, or an effect with answers
+   * inside any node. The walk waits on it, and so does `restore` after it entered a transit node.
+   */
   gateOpen: (() => void)[]; /** The bookmark the loop enters at the next turn. */
   restoring: Bookmark | undefined;
 };
@@ -2298,7 +2318,12 @@ 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. */
+  stack: Frame[];
+  /**
+   * The frames a failed node is retried from, paired with the state a rollback returns to: the
+   * last rest node, or the node the graph started at or a restore entered. The last two may be
+   * transit nodes, so `bookmark()` writes its `rest` only when these frames name a rest node.
+   */
   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[];
@@ -2373,7 +2398,10 @@ type RunnerApi = {
   /**
    * 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.
+   * entered through the same check as `restore`, with the same fallback. A rest node is entered
+   * before the switch to fast mode: its stages see the mode of the caller. A transit node is
+   * entered after the switch and without the wait `restore` adds for it: its popup is not shown,
+   * the route answers it. 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.
@@ -2395,32 +2423,57 @@ type RunnerApi = {
     from?: Bookmark;
   }): Promise<FlowState>;
   /**
-   * Makes a bookmark of the current rest point: the rest node plus the committed state.
+   * Makes a bookmark of where the graph stands: the last rest node plus the committed state.
+   * While a transit node waits at the gate for the answer of an effect (a `popup`, or any
+   * descriptor with `answers`), the bookmark names that node instead. Its state is the one
+   * committed when the node was entered: what the node wrote before the wait is not in it, the
+   * node writes it again when it is restored. `rest` then names the rest point before the node.
+   * While a transit node awaits anything else (an animation, a request) the bookmark still names
+   * the last rest node.
    *
    * @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
+   * // A devtools button keeps the position. The board rests: the bookmark names its rest node.
+   * const atBoard = app.flow.bookmark(); // plain data, ready for JSON.stringify
+   * atBoard.path; // "board/awaitIntent"
+   * // The mini game with its info popup open: the bookmark names the node that waits.
+   * const atPopup = app.flow.bookmark();
+   * atPopup.path; // "info/show"
+   * atPopup.rest; // { path: "home", input: null }: the rest point before it
    * ```
    */
   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.
+   * Replaces the state with the bookmark's and enters its node. A rest checkpoint is always
+   * accepted; any other node only while the graph is unchanged. A transit node is never taken
+   * for a checkpoint: when the graph changed, such a bookmark is entered at its `rest` point
+   * instead, if that is a checkpoint, and the log gets `flow:restore-fell-back`. A renamed or
+   * removed node is a changed graph too: a bookmark with `rest` whose path names no node takes
+   * the same fallback.
+   *
+   * A rest node: the promise resolves when the node is entered, before its scene stage ran. A
+   * transit node runs again from its first line, live, with the bookmark's input, so its effects
+   * before the gate play again; the promise resolves when its gate is open, or at the rest node
+   * or the end of the loop it reaches without one. A node that does none of these keeps the
+   * promise pending. An open gate is not a drawn popup: the popup shows on the next frame. And
+   * `setMode` still throws there, since the graph waits inside a transit node.
    *
    * @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()`.
+   * @returns A promise that resolves once a rest node is entered, or a transit node waits at
+   *   its gate.
+   * @throws {Error} When the bookmark names no node of this graph and has no `rest`, when the
+   *   graph changed since the bookmark and neither it nor its `rest` point is a rest checkpoint,
+   *   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);
+   * await app.flow.restore(atBoard);
    * app.flow.state().path; // "board/awaitIntent"
+   * // A bookmark the mini game took at its info popup: the popup waits again when this resolves.
+   * await app.flow.restore(atPopup);
+   * app.flow.state().pending.gate; // ["ok", "close"], and state().path is "info/show"
    * ```
    */
   restore(bookmark: Bookmark): Promise<void>;
@@ -2468,7 +2521,9 @@ type RunnerApi = {
    */
   history(): readonly JournalEntry[];
   /**
-   * Switches between live and fast mode. Legal before `run()` and while the graph rests.
+   * Switches between live and fast mode. Legal before `run()` and while the graph rests. A
+   * transit node that waits at the gate for a popup does not rest: it throws there too, also
+   * right after a `restore` into such a node.
    *
    * @param mode - `"live"` or `"fast"`.
    * @throws {Error} When a transit node is running.
@@ -2773,7 +2828,12 @@ type Events$3 = {
     };
     index: number;
     now: number;
-  }; /** The graph reached a rest node. */
+  };
+  /**
+   * The graph reached a rest node, or entered the node of a bookmark. The second also happens
+   * for a transit node that waited at the gate: `path` is then no rest node and `checkpoint` is
+   * false.
+   */
   "flow:rest": {
     path: string;
     checkpoint: boolean;

package/dist/{types-zRGJdFGX.d.mts → types-B_Bp2tWK.d.mts}

@@ -1,5 +1,5 @@
-import { A as Api$1, B as ComponentType, D as FilterSlot, H as Entity, O as Point, R as ComponentHandle, Sn as Require, _ as PixiFilter, b as PixiTexture, dt as Api, h as Api$2, s as Events, t as Api$3, v as PixiModule, xn as Events$1, y as PixiSprite } from "./types-C6y8EfEB.mjs";
-import { x as AnimApi } from "./types-B3T2X6To.mjs";
+import { A as Api$1, B as ComponentType, D as FilterSlot, H as Entity, O as Point, R as ComponentHandle, Sn as Require, _ as PixiFilter, b as PixiTexture, dt as Api, h as Api$2, s as Events, t as Api$3, v as PixiModule, xn as Events$1, y as PixiSprite } from "./types-BSMmnpFm.mjs";
+import { x as AnimApi } from "./types-dJMOXXL3.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 

package/dist/{types-D57SntUt.d.mts → types-Bonifz5M.d.mts}

@@ -1,5 +1,5 @@
-import { Xt as Json, an as Snapshot } from "./types-C6y8EfEB.mjs";
-import { t as HeadlessApp } from "./headless-Dgxvp6Ym.mjs";
+import { Xt as Json, an as Snapshot } from "./types-BSMmnpFm.mjs";
+import { t as HeadlessApp } from "./headless-CYgYzro0.mjs";
 import { Log } from "@moku-labs/common/browser";
 
 //#region src/plugins/flow/doors/types.d.ts

package/dist/{types-DGIkfZB7.d.mts → types-DkO3s9YX.d.mts}

@@ -1,7 +1,7 @@
-import { Dt as AnyFlow, Ht as ClockSource, Jt as Config, Wt as FakeClock, Xt as Json, a as Config$3, g as Config$2, ht as FeaturePlugin, n as AssetsIo, pt as Config$1, tn as PlayerStateProvider, u as Manifest, v as PixiModule } from "./types-C6y8EfEB.mjs";
-import { o as AudioContextLike, s as Config$4 } from "./types-B3T2X6To.mjs";
-import { _t as audioPlugin, ct as PlatformProvider, ht as effectsPlugin, i as screen, ot as platformPlugin, t as createApp } from "./index-CdbE_jGs.mjs";
-import { t as memory } from "./memory-DJ2sPExv.mjs";
+import { Dt as AnyFlow, Ht as ClockSource, Jt as Config, Wt as FakeClock, Xt as Json, a as Config$3, g as Config$2, ht as FeaturePlugin, n as AssetsIo, pt as Config$1, tn as PlayerStateProvider, u as Manifest, v as PixiModule } from "./types-BSMmnpFm.mjs";
+import { o as AudioContextLike, s as Config$4 } from "./types-dJMOXXL3.mjs";
+import { _t as audioPlugin, ct as PlatformProvider, ht as effectsPlugin, i as screen, ot as platformPlugin, t as createApp } from "./index-CjuObHhF.mjs";
+import { t as memory } from "./memory-DKo9rRWW.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/app/types.d.ts

package/dist/{types-CmuwAjkV.d.mts → types-Dm5Oh5bH.d.mts}

@@ -1,4 +1,4 @@
-import { A as Api$2, B as ComponentType, F as AnyComponent, H as Entity, I as AnyComponentType, L as AnyComponentValue, Lt as Descriptor, O as Point$2, Q as ChangeHook, Sn as Require, V as ComponentValue, Vt as Api$5, Xt as Json, at as NumericFields, dt as Api$1, h as Api$3, hn as Api, it as MotionHandle, k as ViewportSize, ot as ProjectionMotion, rt as Motion, s as Events$1, t as Api$4, ut as ViewHandle, zt as Hint } from "./types-C6y8EfEB.mjs";
+import { A as Api$2, B as ComponentType, F as AnyComponent, H as Entity, I as AnyComponentType, L as AnyComponentValue, Lt as Descriptor, O as Point$2, Q as ChangeHook, Sn as Require, V as ComponentValue, Vt as Api$5, Xt as Json, at as NumericFields, dt as Api$1, h as Api$3, hn as Api, it as MotionHandle, k as ViewportSize, ot as ProjectionMotion, rt as Motion, s as Events$1, t as Api$4, ut as ViewHandle, zt as Hint } from "./types-BSMmnpFm.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 

package/dist/{types-B3T2X6To.d.mts → types-dJMOXXL3.d.mts}

@@ -1,5 +1,5 @@
-import { A as Api$2, B as ComponentType, F as AnyComponent, H as Entity, It as TypeTag, L as AnyComponentValue, Lt as Descriptor, R as ComponentHandle, Sn as Require, Xt as Json, Yt as Events$2, at as NumericFields, ct as TrackOptions, dn as Events$3, dt as Api$1, et as Ease, h as Api$5, hn as Api, it as MotionHandle, lt as TrackSegment, nt as LayerSpec, q as Owner, qt as Api$4, s as Events$4, t as Api$3, tt as LayerSort, xn as Events$5 } from "./types-C6y8EfEB.mjs";
-import { A as InputApi, c as UiNode, i as Finding, n as ElementChange, o as JsxState, q as I18nApi, r as ElementMotion, rt as StylesState, x as TextApi } from "./types-CmuwAjkV.mjs";
+import { A as Api$2, B as ComponentType, F as AnyComponent, H as Entity, It as TypeTag, L as AnyComponentValue, Lt as Descriptor, R as ComponentHandle, Sn as Require, Xt as Json, Yt as Events$2, at as NumericFields, ct as TrackOptions, dn as Events$3, dt as Api$1, et as Ease, h as Api$5, hn as Api, it as MotionHandle, lt as TrackSegment, nt as LayerSpec, q as Owner, qt as Api$4, s as Events$4, t as Api$3, tt as LayerSort, xn as Events$5 } from "./types-BSMmnpFm.mjs";
+import { A as InputApi, c as UiNode, i as Finding, n as ElementChange, o as JsxState, q as I18nApi, r as ElementMotion, rt as StylesState, x as TextApi } from "./types-Dm5Oh5bH.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 import { Node, Yoga } from "yoga-layout/load";
@@ -1297,9 +1297,10 @@ type State$2 = {
   /** Scene id to its declaration, filled in `onStart` from `flow.features`. */scenes: Map<string, SceneDefinition>; /** Id of the scene that is mounted now. */
   current: string | undefined;
   /**
-   * The scene the next rest node without its own `scene` mounts: the one a transit node named in
-   * fast mode, or the one the restore door expected with `expect`. A rest node clears it; an over
-   * rest node takes it only while nothing is mounted.
+   * The scene the next node without its own `scene` mounts, at a rest node or at a transit node
+   * in live mode: the one a transit node named in fast mode, or the one the restore door expected
+   * with `expect`. A rest node clears it; a transit node clears it only when it took it; an over
+   * node takes it only while nothing is mounted.
    */
   pending: string | undefined;
   owner: SceneOwner; /** The remover of the `onEnter` callback: set in `onStart`, run in `onStop`. */
@@ -1348,19 +1349,22 @@ type ScenesApi = {
    */
   current(): string | undefined;
   /**
-   * Names the scene the next rest node without its own `scene` mounts. The restore door calls it
-   * with the scene of a bookmark, so a bookmark at a popup comes back with the scene under it.
-   * An over rest node takes the expected scene only while nothing is mounted; it never switches a
+   * Names the scene the next node without its own `scene` mounts. A rest node reads it, and so
+   * does a transit node in live mode; a transit node of a fast walk leaves it for the rest point.
+   * The restore door calls it with the scene of a bookmark, so a bookmark at a popup comes back
+   * with the scene under it, also when the popup is a transit node that waits for its answer:
+   * the scene of such a popup is mounted before `flow.restore` resolves.
+   * An over node takes the expected scene only while nothing is mounted; it never switches a
    * mounted one.
    *
    * @param id - Id of a scene a feature declared.
    * @throws {Error} For an id no feature declared, also before `onStart` filled the registry.
    * @example
    * ```ts
-   * // A fresh page restores a bookmark taken at the Settings popup over Home.
+   * // A fresh page restores a bookmark taken at the Settings popup over Home, a transit node
+   * // that waits for its answer.
    * app.scenes.expect("home");
-   * await app.flow.restore(bookmark);
-   * await app.flow.walk([]); // the scene stage runs after restore resolves
+   * await app.flow.restore(bookmark); // resolves when the popup's gate is open
    * app.scenes.current(); // "home"
    * ```
    */

package/dist/visual.d.mts

@@ -1,9 +1,9 @@
-import { A as Api$1, h as Api, ln as Api$3, qt as Api$2 } from "./types-C6y8EfEB.mjs";
-import { r as UiApi, x as AnimApi } from "./types-B3T2X6To.mjs";
-import { A as InputApi } from "./types-CmuwAjkV.mjs";
-import { r as Repro } from "./headless-Dgxvp6Ym.mjs";
-import { a as InputOf, r as ControlApp } from "./types-D57SntUt.mjs";
-import { t as commands } from "./commands-BrgeMP5y.mjs";
+import { A as Api$1, h as Api, ln as Api$3, qt as Api$2 } from "./types-BSMmnpFm.mjs";
+import { r as UiApi, x as AnimApi } from "./types-dJMOXXL3.mjs";
+import { A as InputApi } from "./types-Dm5Oh5bH.mjs";
+import { r as Repro } from "./headless-CYgYzro0.mjs";
+import { a as InputOf, r as ControlApp } from "./types-Bonifz5M.mjs";
+import { t as commands } from "./commands-DRhJ_LIH.mjs";
 
 //#region src/visual/types.d.ts
 /** The base commands of the `/control` door, keyed by their short names. */

package/dist/visual.mjs

@@ -1,5 +1,5 @@
 import { n as read, t as sources } from "./sources-Duzj6lhV.mjs";
-import { n as commands, t as run } from "./run-wYty_Lwo.mjs";
+import { n as commands, t as run } from "./run-BtyrJjmW.mjs";
 import path from "node:path";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";

package/llms.txt

@@ -474,14 +474,15 @@ The graph. Modules `runner`, `gate`, `inbox`, `fx`, `features`. Runner methods s
 - `fx.handle(kind, handler, options?: { runInFast?: boolean }): () => void` registers the single handler of one effect kind. `fx.dispatch(descriptor)` is fire-and-forget. An awaited effect without a handler resolves `undefined` at once.
 - `features.register(name, description)`, `features.all()`, `features.contributions(slotName)`.
 - `FlowState` is `{ running, path, stack, pending: { fx?, gate? }, mode }`.
-- `Bookmark` is `{ path, input, player, session, rng, graph, scene? }`. Serialisable. `scene` is written by the `game.bookmark` door and read by `game.restore`; `flow.restore` ignores it. `restore` needs a running graph and the path of a rest node. A checkpoint is always accepted. Any other rest node is accepted only when the graph did not change since the bookmark.
+- `Bookmark` is `{ path, input, player, session, rng, graph, scene?, rest? }`. Serialisable. `scene` is written by the `game.bookmark` door and read by `game.restore`; `flow.restore` ignores it. `path` names a rest node, or the transit node that waits at the gate for an effect that takes answers (a `popup`, or a hand-written descriptor with `answers`); `rest: { path, input }` then names the rest point before it (left out when the graph started at that node or a restore entered it), and the state is the one committed when that node was entered. `restore` needs a running graph. A rest checkpoint is always accepted. Any other node is accepted only when the graph did not change since the bookmark; with another graph a transit bookmark is entered at `rest` instead when that is a checkpoint, and the log gets `flow:restore-fell-back`.
+- `restore` of a rest node resolves when the node is entered. `restore` of a transit node runs it again from its start, so its effects before the gate play again, and resolves once its gate is open. The open gate is not the draw: the popup shows on the next frame.
 - Events: `flow:edge` `{ flow, node, outcome, payload, next, patches: { doc, session }, index, now }` after the commit of an edge. `flow:rest` `{ path, checkpoint }`. `flow:error` `{ path, error, rolledBackTo, retry }`.
 - Config: `mainFlow` default `undefined` and required before `run()`, `safeNode: string | undefined` default `undefined` which means the main flow's `start`, `retries` default `1`, `settleTimeoutMs` default `2000`, `journalLimit` default `500`.
 
 ### Screen plugins (V2, built)
 
 `world`, `renderer`, `input`, `assets`, `scenes`. Each has a README at `src/plugins/<name>/README.md`; the root README lists their APIs, events and config. Rendering: WebGPU preferred, with Pixi's WebGL fallback.
-- `app.scenes`: `current()` the mounted scene id, `expect(id)` the scene the next rest node without its own `scene` mounts (the restore door calls it; an unknown id throws).
+- `app.scenes`: `current()` the mounted scene id, `expect(id)` the scene the next node without its own `scene` mounts, a rest node or a transit node in live mode (the restore door calls it; an unknown id throws).
 - `resource(name, defaults)` clones plain JSON defaults into every world. `resource(name, () => value)` calls the factory once per world on first read, so the value may hold a `Map` or a function: `const Looks = resource("boardLooks", () => ({ shown: new Map<World.Entity, { look: string }>() }))`. A system keeps its own state there; `snapshot()` leaves a value that is not JSON out.
 - `app.world.projection.replace(spec)` swaps the spec of a registered projection; a mounted one runs its new `view` on the next frame. An unknown name throws. The caller is the dev hot swap.
 
@@ -592,7 +593,7 @@ Two subpaths, neither on the root (V4). An editor, MCP tools and e2e scripts rea
 - `@moku-labs/game/inspect`: `read(app, source, input?)` reads once; `watch(app, source, input, fn)` reads on the `signals` phase when the source changes and returns the stop function; `defineSource`; the frozen catalogue `sources`; the types `Source`, `InputSchema`, `InputOf`. Every source only reads, so the door is safe in a production build. Keys of `sources`: `graph`, `position`, `history`, `tainted`, `cheats`, `model`, `entities`, `projections`, `ui`, `locate`, `render`, `sounds`, `audioMuted`, `effects`, `assets`, `log`, `explain`, `diff`, `schema`, `at`; their ids are `game.<key>`. `locate` takes `{ key }` (a ui element) or `{ target }` (a view by projection key) and answers its box in CSS px, the numbers Playwright clicks. `at` takes `{ x, y }` in CSS px and lists the views under that point, topmost first. `explain` takes `{ entity }` and answers that entity in full, `undefined` for a stale id. `diff` takes `{ from, to }` frames and answers what changed per entity; it throws in a production build and for a frame outside the last 120. `schema` lists every component and tag type the world met, with the JSON kind of each field. `audioMuted` answers whether the master bus is muted. `sounds` throws `[game] The source game.sounds needs audioPlugin.`, `audioMuted` throws `[game] The source game.audioMuted needs audioPlugin.` and `effects` throws `[game] The source game.effects needs effectsPlugin.` when that plugin is not installed; the editor lists such a source as not installed.
 - `@moku-labs/game/control`: `run(app, command, input?)` resolves `{ value, state }`, `state` being `{ path, frame, tainted }`; `defineCommand`; `controlRefused`; the frozen catalogue `commands`; the types `Command`, `Ran`. Keys of `commands`: `answer`, `tap`, `drag`, `key`, `fill`, `walk`, `bookmark`, `restore`, `step`, `pause`, `resume`, `capture`, `debug`, `reducedMotion`, `timeScale`, `mute`, `trace`. `capture` resolves `{ png }`, and `{ png, legend }` with `legend: true`; `undefined` while the renderer is inert. `timeScale` takes `{ scale }`; 0 freezes game time while the frames keep running. `mute` takes `{ muted }`, mutes the master bus and answers the flag. Without `audioPlugin` it throws `[game] The command game.mute needs audioPlugin.` `trace` takes `{ path }`, a list of views by projection key, and answers whether the gate took the answer.
 - Commands run in dev builds only. Only `__MOKU_GAME_DEV__ === true` turns the dev build on: `moku-game dev` defines it `true` and sets the global in `.moku/dev.ts`, `moku-game build` defines it `false`; a game without the shell uses a bundler `define`; a test uses `vi.stubGlobal("__MOKU_GAME_DEV__", true)`. Otherwise `run` throws `[game] Control commands run in dev builds only.`
-- A command's effect is `read`, `route`, `cosmetic`, `cheat` or `raw`. A `cheat` or `raw` command taints the session and is journaled; read it with `sources.tainted` and `sources.cheats`. Of the base commands only `restore` is `raw`. `bookmark` answers `flow.bookmark()` plus `scene`, the mounted scene; `restore` calls `scenes.expect(scene)` before `flow.restore`, so a bookmark at a popup restores the scene under it.
+- A command's effect is `read`, `route`, `cosmetic`, `cheat` or `raw`. A `cheat` or `raw` command taints the session and is journaled; read it with `sources.tainted` and `sources.cheats`. Of the base commands only `restore` is `raw`. `bookmark` answers `flow.bookmark()` plus `scene`, the mounted scene; `restore` calls `scenes.expect(scene)` before `flow.restore`, so a bookmark at a popup restores the scene under it. A bookmark taken while an effect that takes answers waits names the waiting transit node (`info/show` in the mini game) and carries `rest`; `restore` of it answers once that node's gate is open, with `pending.gate` in its value, and the popup shows on the next frame.
 - A game's own: `defineSource({ id, title, input, changes, read })` with `changes` `"frame"`, `"commit"` or `"edge"`, and `defineCommand({ id, title, input, effect, run })`. The id is camelCase words joined by dots, at least two: `dice.rolls`. An input schema maps field names to `"string"`, `"number"`, `"boolean"` or `"json"`; a trailing `?` makes one optional. A command body starts with `if (typeof __MOKU_GAME_DEV__ === "undefined" || !__MOKU_GAME_DEV__) throw controlRefused();`. Keep them in `.dev` modules that only the dev page and the tests import: the editor's dev page (`preparePage` with agents) imports every `**/*.dev.ts`, `moku-game build` none.
 
 ## Project index

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/game",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "2D puzzle game engine on TypeScript and PixiJS, built on @moku-labs/core.",
   "type": "module",
   "sideEffects": [