@patterkit/runtime 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -33,6 +33,37 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-10-05
+
+### Changed
+
+- **`replayPromptOnChoose` speaks back only an authored prompt, and exactly what the choice showed.** A game that
+  turns the option on will see the difference, which is why this is a minor release rather than a patch:
+  - An option whose prompt the choice borrowed from its own first content line (a bare-snippet option,
+    or an Option group with no prompt of its own) is no longer spoken back. That line used to play twice
+    in a row, once as the replay and once as content. It now plays once.
+  - The replayed prompt carries the text, `character`, `characterName`, and `direction` the choice
+    displayed, instead of resolving the prompt again when it is delivered. So if choosing runs effects
+    first (an Option group that picks a snippet runs its onEnter at once), or the language changes
+    between `choose()` and the next `advance()`, the replay still says what the player saw. In a voiced
+    project a replayed line prompt is now interpolated, as the choice showed it.
+  - A save taken between `choose()` and the next `advance()` carries that prompt as shown, in a new
+    optional `pendingPrompt` on the flow's cursor, so the replay after a load is the same. Every
+    Patterplay runtime writes and reads it. A save from an earlier version, without it, still loads and
+    resolves the prompt when it is delivered, as before.
+    The save shape's `FlowCursor.pendingPrompt` is typed in `@patterkit/model`.
+
+## [0.17.0] - 2026-10-05
+
+### Fixed
+
+- **`openFlow` at an address that does not resolve changes nothing.** It threw, but only after closing
+  any flow already open under that name and putting a broken one in its place. It now throws before
+  anything changes. The block must be in the scene you named, as `goto` has always required: a block
+  from another scene used to open there, and now throws. Held across all four runtimes by the
+  conformance corpus, which now also pins a choice step whole (its `groupId` and each option's
+  `prompt`), as this runtime already gave it.
+
 ## [0.16.0] - 2026-10-04
 
 ### Added

package/dist/index.cjs

@@ -332,11 +332,14 @@ var Engine = class _Engine {
    *
    * 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.
+   *
+   * THROWS on an address that does not resolve (an unknown scene, or a block that is not in the named
+   * scene), before anything changes: nothing is opened, and a flow already open under `id` carries on
+   * exactly as it was.
    */
   openFlow(id, opts = {}) {
     this.assertExternalScopes();
-    const sceneId = this.resolveSceneRef(opts.scene);
-    const blockId = this.resolveBlockRef(sceneId, opts.block);
+    const { sceneId, blockId } = this.resolveOpenAddress(opts.scene, opts.block);
     const prior = this.flowsById.get(id);
     const journal = this.host.journal;
     if (journal && prior && !prior.isClosed) throw new Error(`openFlow would replace the open flow '${id}', which can't be undone while a checkpoint is open`);
@@ -397,6 +400,28 @@ var Engine = class _Engine {
       }
     }
   }
+  /**
+   * `openFlow`'s address as internal ids, or a throw when it does not resolve. With a scene, the block is
+   * scene-scoped exactly as {@link Flow.goto} resolves it (a gameId address in that scene, or the internal
+   * id of a block in that scene), so a block from another scene does not resolve. With no scene, the block
+   * is an internal id from any scene. Neither: the bundle's first scene. The same rule on every runtime.
+   */
+  resolveOpenAddress(scene, block) {
+    if (scene !== void 0) {
+      const sceneId = this.resolveSceneRef(scene);
+      if (!this.host.bundle.scenes[sceneId]) throw new Error(`unknown scene: ${scene}`);
+      if (block === void 0) return { sceneId };
+      const blockId = this.blockGameIdToId.get(sceneId)?.get(block) ?? (this.host.blockIndex.get(block)?.sceneId === sceneId ? block : void 0);
+      if (blockId === void 0) throw new Error(`unknown block: ${block}`);
+      return { sceneId, blockId };
+    }
+    if (block !== void 0) {
+      if (!this.host.blockIndex.has(block)) throw new Error(`unknown block: ${block}`);
+      return { blockId: block };
+    }
+    if (Object.keys(this.host.bundle.scenes).length === 0) throw new Error("no scenes in bundle");
+    return {};
+  }
   /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
   resolveSceneRef(ref) {
     if (ref == null) return void 0;
@@ -851,10 +876,13 @@ var Flow = class {
   activeSnippet = null;
   beatIndex = 0;
   pendingChoice = null;
-  /** When `replayPromptOnChoose`, the chosen option's prompt beat to deliver before its content. */
-  pendingPromptBeat = null;
-  /** The chosen option that owns `pendingPromptBeat`, so a save taken between choose() and the next
-   *  advance() can re-derive the prompt on load (the beat isn't otherwise reachable by id). */
+  /** When `replayPromptOnChoose`, the chosen option's AUTHORED prompt to deliver before its content: its
+   *  beat (id, gameData, tags) and the prompt exactly as the choice showed it (text and speaker fields).
+   *  `shown` is missing only after loading a save written before saves carried it: the beat is then
+   *  resolved when it is delivered, as it always was. */
+  pendingPrompt = null;
+  /** The chosen option that owns `pendingPrompt`, so a save taken between choose() and the next
+   *  advance() can find the prompt beat again on load (it isn't otherwise reachable by id). */
   pendingPromptOwnerId = null;
   selectors = /* @__PURE__ */ new Map();
   /** Per-node entry counts for this flow (node id -> times entered). */
@@ -1016,7 +1044,7 @@ var Flow = class {
     if (scene === "END") {
       this.started = true;
       this.pendingChoice = null;
-      this.pendingPromptBeat = null;
+      this.pendingPrompt = null;
       this.pendingPromptOwnerId = null;
       this.activeSnippet = null;
       this.beatIndex = 0;
@@ -1036,7 +1064,7 @@ var Flow = class {
       return true;
     }
     this.pendingChoice = null;
-    this.pendingPromptBeat = null;
+    this.pendingPrompt = null;
     this.pendingPromptOwnerId = null;
     this.activeSnippet = null;
     this.beatIndex = 0;
@@ -1063,7 +1091,7 @@ var Flow = class {
     this.activeSnippet = null;
     this.beatIndex = 0;
     this.pendingChoice = null;
-    this.pendingPromptBeat = null;
+    this.pendingPrompt = null;
     this.pendingPromptOwnerId = null;
   }
   /** Inside a checkpoint, the first change to this flow records its cursor and PRNG, so a rollback can
@@ -1073,10 +1101,10 @@ var Flow = class {
     const journal = this.host.journal;
     if (!journal || journal.flows.has(this)) return;
     journal.flows.add(this);
-    const { rngState, started, flowEnded, currentSceneId, activeSnippet, beatIndex, pendingChoice, pendingPromptBeat, pendingPromptOwnerId } = this;
+    const { rngState, started, flowEnded, currentSceneId, activeSnippet, beatIndex, pendingChoice, pendingPrompt, pendingPromptOwnerId } = this;
     const stack = this.stack.map((f) => ({ ...f }));
     journal.undo.push(() => {
-      Object.assign(this, { rngState, started, flowEnded, currentSceneId, activeSnippet, beatIndex, pendingChoice, pendingPromptBeat, pendingPromptOwnerId, stack });
+      Object.assign(this, { rngState, started, flowEnded, currentSceneId, activeSnippet, beatIndex, pendingChoice, pendingPrompt, pendingPromptOwnerId, stack });
     });
   }
   /** True once the engine has closed this flow (closed, dropped by `reset()`, or replaced by name). */
@@ -1094,11 +1122,11 @@ var Flow = class {
     if (this.closed) return { type: "end" };
     if (!this.started) throw new Error("flow has not been started");
     this.touch();
-    if (this.pendingPromptBeat) {
-      const b = this.pendingPromptBeat;
-      this.pendingPromptBeat = null;
+    if (this.pendingPrompt) {
+      const p = this.pendingPrompt;
+      this.pendingPrompt = null;
       this.pendingPromptOwnerId = null;
-      return this.beatResult(b);
+      return p.shown ? this.promptResult(p.beat, p.shown) : this.beatResult(p.beat);
     }
     this.settle();
     if (this.flowEnded) return { type: "end" };
@@ -1217,8 +1245,9 @@ var Flow = class {
     const node = choice.byId.get(id);
     this.emit({ type: "chose", group: choice.groupId, option: id });
     this.pendingChoice = null;
-    this.pendingPromptBeat = this.host.replayPromptOnChoose ? this.promptBeatOf(node) ?? null : null;
-    this.pendingPromptOwnerId = this.pendingPromptBeat ? node.id : null;
+    const authored = this.host.replayPromptOnChoose ? this.authoredPromptOf(node) : void 0;
+    this.pendingPrompt = authored && option.prompt ? { beat: authored, shown: { ...option.prompt } } : null;
+    this.pendingPromptOwnerId = this.pendingPrompt ? node.id : null;
     this.enterChild(node);
   }
   isEnded() {
@@ -1284,6 +1313,8 @@ var Flow = class {
         beatIndex: this.beatIndex,
         pendingChoice: this.pendingChoice ? { groupId: this.pendingChoice.groupId, options: this.pendingChoice.options.map((o) => ({ ...o })) } : null,
         pendingPromptOwnerId: this.pendingPromptOwnerId,
+        // The prompt still to be replayed, as the choice showed it: present only in the choose -> advance window.
+        ...this.pendingPrompt?.shown ? { pendingPrompt: savedPrompt(this.pendingPrompt.shown) } : {},
         selectors: serialiseSelectors(this.selectors)
       }
     };
@@ -1334,12 +1365,13 @@ var Flow = class {
       }
       if (options.length > 0) this.pendingChoice = { groupId: c.pendingChoice.groupId, options, byId };
     }
-    this.pendingPromptBeat = null;
+    this.pendingPrompt = null;
     this.pendingPromptOwnerId = c.pendingPromptOwnerId ?? null;
     if (this.pendingPromptOwnerId) {
       const owner = this.host.nodeIndex.get(this.pendingPromptOwnerId);
-      this.pendingPromptBeat = owner ? this.promptBeatOf(owner) ?? null : null;
-      if (!this.pendingPromptBeat) this.pendingPromptOwnerId = null;
+      const beat = owner ? this.authoredPromptOf(owner) : void 0;
+      if (beat) this.pendingPrompt = { beat, ...c.pendingPrompt ? { shown: { ...c.pendingPrompt } } : {} };
+      else this.pendingPromptOwnerId = null;
     }
   }
   // -- Scene / block / node entry ------------------------------------------
@@ -1734,6 +1766,27 @@ var Flow = class {
     const text = this.interpolate(this.resolveString(beat.id));
     return beat.kind === "line" ? { kind: "line", text: this.captionLine(text), character: beat.character, characterName: this.resolveCharacterName(beat.character), direction: beat.direction } : { kind: "text", text };
   }
+  /** An option's AUTHORED prompt beat: an Option group's own `prompt`. The only prompt a replay speaks. */
+  authoredPromptOf(node) {
+    return node.type === "group" ? node.prompt : void 0;
+  }
+  /** A replayed prompt as a step: the beat's id, gameData, and tags, and the text and speaker fields the
+   *  choice showed. */
+  promptResult(beat, shown) {
+    const tags = this.host.tagIndex.get(beat.id);
+    const withTags = tags && tags.length ? { tags } : {};
+    if (shown.kind === "text") return { type: "text", id: beat.id, text: shown.text, gameData: beat.gameData, ...withTags };
+    return {
+      type: "line",
+      id: beat.id,
+      text: shown.text,
+      character: shown.character,
+      characterName: shown.characterName,
+      direction: shown.direction,
+      gameData: beat.gameData,
+      ...withTags
+    };
+  }
   /** The prompt BEAT of an option: the Option group's `prompt`, else (tolerance) its first content line. */
   promptBeatOf(node) {
     if (node.type === "group" && node.prompt) return node.prompt;
@@ -1857,6 +1910,13 @@ function collectCast(nodes, out) {
 function gameDataField(gameData) {
   return gameData && Object.keys(gameData).length ? { gameData } : {};
 }
+function savedPrompt(p) {
+  const out = { kind: p.kind, text: p.text };
+  if (p.character !== void 0) out.character = p.character;
+  if (p.characterName !== void 0) out.characterName = p.characterName;
+  if (p.direction !== void 0) out.direction = p.direction;
+  return out;
+}
 function serialiseSelectors(map) {
   const out = {};
   for (const [id, st] of map) {