@patterkit/runtime 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -17,6 +17,29 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-21
+
+### Added
+- **Host navigation.** `flow.goto(scene, block?)` sends a running flow to a Game ID address, behaving
+  exactly like an authored `go` jump: the target scene's `onEntry` runs, arriving counts as a visit, and
+  the callstack is replaced (pending call-returns discarded). Being a host action it lands immediately -
+  the rest of the snippet being delivered is abandoned and a pending choice dropped - and it MOVES the
+  cursor without resetting the flow, so variation, visit counts and per-flow properties carry on. Returns
+  `false` with the cursor untouched when the address does not resolve; a block address is scene-scoped.
+- **`engine.runFlow(name, scene, block?)`**, the one-call form: opens the named flow if it does not
+  exist, moves it if it does, runs to the next stop and returns the beats played. Reusing the name is the
+  point - a flow owns its selector cursors, so a shuffle keeps its bag and a "once each" list keeps its
+  place from call to call. `[]` means the address has nothing left to give; an unresolvable address
+  throws, so the two are never confused.
+- `flow.isClosed`, and `engine.sceneAddress` / `engine.blockAddress` are now matched by all four runtimes
+  (they were JS-only).
+
+### Changed
+- Dropping a flow now FINISHES it. `closeFlow`, `engine.reset()` and re-opening a name all leave the old
+  `Flow` inert (`advance()` reports the end, `goto()` refuses), so a stale reference a game still holds
+  can no longer keep running scene entry effects and moving shared state. Re-opening a name still
+  replaces (and so resets) that flow - use `runFlow` when a speaker's variation state should carry on.
+
 ## [0.2.2] - 2026-07-13
 
 ### Changed

package/dist/index.cjs

@@ -153,6 +153,9 @@ var Engine = class _Engine {
       nodeIndex,
       blockIndex,
       blockById,
+      sceneGameIdToId: this.sceneGameIdToId,
+      blockGameIdToId: this.blockGameIdToId,
+      // same instances the engine resolves with
       tagIndex: buildTagIndex(bundle),
       shared,
       patterSharedDecls,
@@ -261,16 +264,56 @@ var Engine = class _Engine {
   /**
    * Open (and start) a named flow. Each flow has its own cursor, PRNG, and per-flow
    * half of the scopes (not-shared `@patter`/`@scene`); all flows share the shared
-   * half. Re-opening an existing id replaces it with a fresh flow.
+   * half.
+   *
+   * Re-opening an existing id REPLACES it with a fresh flow, and CLOSES the old one
+   * ({@link Flow.close}) so a host still holding it cannot keep driving the shared world. Replacing is
+   * therefore a reset: that name's cursor, visit counts, selector cursors (so any shuffle / once-each
+   * position) and per-flow properties all start over.
+   *
+   * Contrast {@link runFlow}, which REUSES a flow of the same name instead of replacing it - that is the
+   * call to reach for when you want a speaker's variation state to carry on.
    */
   openFlow(id, opts = {}) {
     const sceneId = this.resolveSceneRef(opts.scene);
     const blockId = this.resolveBlockRef(sceneId, opts.block);
+    this.flowsById.get(id)?.close();
     const flow = new Flow(id, this.host, opts.seed ?? this.defaultSeed);
     this.flowsById.set(id, flow);
     flow.start(sceneId, blockId);
     return flow;
   }
+  /**
+   * "Play this address and give me everything it produced" - the one-call form of the bark / one-shot
+   * pattern. The NAMED flow is reused if it already exists (moved with {@link Flow.goto}) and opened at
+   * the address if not, then run to its next stop, returning every beat it played.
+   *
+   * Calling it again with the SAME NAME does NOT replace the flow - it reuses it, and that is the whole
+   * point. A flow owns its selector cursors, visit counts and per-flow properties, so reusing one lets a
+   * **shuffle keep its bag** and an **"once each" list keep its place**: successive calls give the next
+   * variation instead of replaying the first forever. (A fresh flow each time would reset all of it,
+   * unless every such group happened to be authored `shared`.) Use one name per independent speaker;
+   * different names never share per-flow state.
+   *
+   * This is exactly where it differs from {@link openFlow}, which REPLACES a flow of the same name and
+   * so resets that variation state. Never mix the two on one name unless you mean to start over.
+   *
+   * Returns the played beats in order - `[]` means the address had nothing left to give (an exhausted
+   * variation list, say), which is the signal to fall back to other content. It THROWS on an address
+   * that does not resolve: unlike `goto` (a navigation primitive, where probing is legitimate), naming a
+   * location here asserts it exists, and keeping `[]` unambiguous is worth more than a soft failure.
+   *
+   * A run that stops at a CHOICE returns the beats up to it and leaves the choice pending on the flow -
+   * fetch it with `engine.getFlow(name)?.getChoices()`.
+   */
+  runFlow(flow, scene, block) {
+    const existing = this.flowsById.get(flow);
+    if (!existing) return this.openFlow(flow, { scene, block }).advanceToStop().played;
+    if (!existing.goto(scene, block)) {
+      throw new Error(`runFlow: address not found: ${scene}${block === void 0 ? "" : ` / ${block}`}`);
+    }
+    return existing.advanceToStop().played;
+  }
   /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
   resolveSceneRef(ref) {
     if (ref == null) return void 0;
@@ -408,8 +451,10 @@ var Engine = class _Engine {
   flows() {
     return [...this.flowsById.values()];
   }
-  /** Close (remove) a flow. */
+  /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
+   *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
   closeFlow(id) {
+    this.flowsById.get(id)?.close();
     this.flowsById.delete(id);
   }
   /**
@@ -419,6 +464,7 @@ var Engine = class _Engine {
    * After reset, open fresh flows with `openFlow`.
    */
   reset() {
+    for (const flow of this.flowsById.values()) flow.close();
     this.flowsById.clear();
     this.host.shared.reseedOwned("patter", this.host.patterSharedDecls);
     this.host.sharedVisits.clear();
@@ -510,6 +556,9 @@ var Flow = class {
   // `activeSnippet`/`beatIndex`.
   started = false;
   flowEnded = false;
+  /** Closed by the engine (see `close()`). Terminal, and distinct from `flowEnded`: an ENDED flow is
+   *  merely out of content and `goto` revives it; a CLOSED one is finished for good. */
+  closed = false;
   currentSceneId = null;
   stack = [];
   activeSnippet = null;
@@ -616,6 +665,81 @@ var Flow = class {
   reset(sceneId, blockId) {
     this.start(sceneId, blockId);
   }
+  /**
+   * Send this flow's cursor to an ADDRESS, exactly as an authored `go` jump would: the target scene's
+   * `onEntry` effects run, entering counts as a visit, and the callstack is REPLACED - any pending
+   * `call` returns are discarded, just as a goto inside a call does.
+   *
+   * `scene` and `block` are host-facing gameIds (spec §6) or internal ids; `block` is scene-scoped, so
+   * it is looked up within `scene`. `"END"` ends the flow. To move within the current scene, pass the
+   * current scene's address again (`flow.currentScene` -> `engine.sceneAddress`).
+   *
+   * This is HOST navigation, not authoring, and it takes effect IMMEDIATELY: any beats left in the
+   * snippet being delivered are abandoned, and a pending choice is dropped. The format stops an AUTHOR
+   * writing a divert into the middle of a snippet; a host teleport is out-of-band, like `reset()` or
+   * `loadGame()`. A flow that never started starts here; one that already ended resumes here.
+   *
+   * Returns false - leaving the cursor exactly where it was - if the address does not resolve. Per-flow
+   * state (properties, visit counts, selector cursors) is untouched either way: this MOVES, never resets.
+   */
+  goto(scene, block) {
+    if (this.closed) return false;
+    if (scene === "END") {
+      this.started = true;
+      this.pendingChoice = null;
+      this.pendingPromptBeat = null;
+      this.pendingPromptOwnerId = null;
+      this.activeSnippet = null;
+      this.beatIndex = 0;
+      this.flowEnded = true;
+      this.stack = [];
+      return true;
+    }
+    const sceneId = this.host.sceneGameIdToId.get(scene) ?? (this.host.bundle.scenes[scene] ? scene : void 0);
+    if (sceneId === void 0) return false;
+    let blockId;
+    if (block !== void 0) {
+      blockId = this.host.blockGameIdToId.get(sceneId)?.get(block) ?? (this.host.blockIndex.get(block)?.sceneId === sceneId ? block : void 0);
+      if (blockId === void 0) return false;
+    }
+    if (!this.started) {
+      this.start(sceneId, blockId);
+      return true;
+    }
+    this.pendingChoice = null;
+    this.pendingPromptBeat = null;
+    this.pendingPromptOwnerId = null;
+    this.activeSnippet = null;
+    this.beatIndex = 0;
+    this.flowEnded = false;
+    this.enterTarget(blockId ?? sceneId, "jump");
+    this.settle();
+    return true;
+  }
+  /**
+   * Finish this flow for good. Engine-managed: `engine.closeFlow(id)`, `engine.reset()`, and re-opening
+   * a name with `engine.openFlow` all call it on the flow being dropped.
+   *
+   * A dropped flow used to stay fully live: unregistered and invisible to `engine.flows()`, but a host
+   * still holding the object could keep advancing it, and every scene `onEntry`, shared property, world
+   * visit count and shared selector cursor it touched still landed on the engine. Closing makes that
+   * stale reference inert - `advance()` reports the end and `goto()` refuses - so a forgotten reference
+   * cannot quietly mutate the world. Terminal: unlike ending, a close is never revived.
+   */
+  close() {
+    this.closed = true;
+    this.flowEnded = true;
+    this.stack = [];
+    this.activeSnippet = null;
+    this.beatIndex = 0;
+    this.pendingChoice = null;
+    this.pendingPromptBeat = null;
+    this.pendingPromptOwnerId = null;
+  }
+  /** True once the engine has closed this flow (closed, dropped by `reset()`, or replaced by name). */
+  get isClosed() {
+    return this.closed;
+  }
   /** The scene the cursor is currently in - set on entry and whenever a jump crosses scenes. Read
    *  right after `advance()` to know which scene the just-played beat lives in (tooling that mirrors
    *  the playhead, e.g. an editor following a cross-scene jump). `null` before the flow has started. */
@@ -624,6 +748,7 @@ var Flow = class {
   }
   /** Run until the next line, game event, choice, or the end of the flow. */
   advance() {
+    if (this.closed) return { type: "end" };
     if (!this.started) throw new Error("flow has not been started");
     if (this.pendingPromptBeat) {
       const b = this.pendingPromptBeat;