@patterkit/runtime 0.16.0 → 0.18.0

package/dist/index.d.cts

@@ -459,6 +459,10 @@ declare 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: string, opts?: OpenFlowOptions): Flow;
     /**
@@ -490,6 +494,13 @@ declare class Engine {
      *  it opens (or the save as it loads), before anything changes. By then a game has built all of its
      *  engines, whatever order it built them in. The same message on every runtime. */
     private assertExternalScopes;
+    /**
+     * `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.
+     */
+    private resolveOpenAddress;
     /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
     private resolveSceneRef;
     /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
@@ -673,10 +684,13 @@ declare class Flow {
     private activeSnippet;
     private beatIndex;
     private pendingChoice;
-    /** When `replayPromptOnChoose`, the chosen option's prompt beat to deliver before its content. */
-    private pendingPromptBeat;
-    /** 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. */
+    private pendingPrompt;
+    /** 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). */
     private pendingPromptOwnerId;
     private selectors;
     /** Per-node entry counts for this flow (node id -> times entered). */
@@ -896,6 +910,11 @@ declare class Flow {
      * option's first content line. NO look-ahead. Undefined only when even that is absent.
      */
     private promptFor;
+    /** An option's AUTHORED prompt beat: an Option group's own `prompt`. The only prompt a replay speaks. */
+    private authoredPromptOf;
+    /** A replayed prompt as a step: the beat's id, gameData, and tags, and the text and speaker fields the
+     *  choice showed. */
+    private promptResult;
     /** The prompt BEAT of an option: the Option group's `prompt`, else (tolerance) its first content line. */
     private promptBeatOf;
     /** The first snippet with a line/text beat within a child list, depth-first in authored order. */

package/dist/index.d.ts

@@ -459,6 +459,10 @@ declare 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: string, opts?: OpenFlowOptions): Flow;
     /**
@@ -490,6 +494,13 @@ declare class Engine {
      *  it opens (or the save as it loads), before anything changes. By then a game has built all of its
      *  engines, whatever order it built them in. The same message on every runtime. */
     private assertExternalScopes;
+    /**
+     * `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.
+     */
+    private resolveOpenAddress;
     /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
     private resolveSceneRef;
     /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
@@ -673,10 +684,13 @@ declare class Flow {
     private activeSnippet;
     private beatIndex;
     private pendingChoice;
-    /** When `replayPromptOnChoose`, the chosen option's prompt beat to deliver before its content. */
-    private pendingPromptBeat;
-    /** 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. */
+    private pendingPrompt;
+    /** 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). */
     private pendingPromptOwnerId;
     private selectors;
     /** Per-node entry counts for this flow (node id -> times entered). */
@@ -896,6 +910,11 @@ declare class Flow {
      * option's first content line. NO look-ahead. Undefined only when even that is absent.
      */
     private promptFor;
+    /** An option's AUTHORED prompt beat: an Option group's own `prompt`. The only prompt a replay speaks. */
+    private authoredPromptOf;
+    /** A replayed prompt as a step: the beat's id, gameData, and tags, and the text and speaker fields the
+     *  choice showed. */
+    private promptResult;
     /** The prompt BEAT of an option: the Option group's `prompt`, else (tolerance) its first content line. */
     private promptBeatOf;
     /** The first snippet with a line/text beat within a child list, depth-first in authored order. */

package/dist/index.js

@@ -299,11 +299,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`);
@@ -364,6 +367,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;
@@ -818,10 +843,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). */
@@ -983,7 +1011,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;
@@ -1003,7 +1031,7 @@ var Flow = class {
       return true;
     }
     this.pendingChoice = null;
-    this.pendingPromptBeat = null;
+    this.pendingPrompt = null;
     this.pendingPromptOwnerId = null;
     this.activeSnippet = null;
     this.beatIndex = 0;
@@ -1030,7 +1058,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
@@ -1040,10 +1068,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). */
@@ -1061,11 +1089,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" };
@@ -1184,8 +1212,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() {
@@ -1251,6 +1280,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)
       }
     };
@@ -1301,12 +1332,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 ------------------------------------------
@@ -1701,6 +1733,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;
@@ -1824,6 +1877,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) {