@patterkit/runtime 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -33,6 +33,26 @@ 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

package/dist/index.cjs

@@ -876,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). */
@@ -1041,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;
@@ -1061,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;
@@ -1088,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
@@ -1098,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). */
@@ -1119,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" };
@@ -1242,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() {
@@ -1309,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)
       }
     };
@@ -1359,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 ------------------------------------------
@@ -1759,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;
@@ -1882,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) {