@patterkit/runtime 0.17.0 → 0.19.0

package/dist/index.js

@@ -21,6 +21,7 @@ function buildTagIndex(bundle) {
   const visit = (node, inherited) => {
     const acc = dedupe([...inherited, ...node.tags ?? []]);
     index.set(node.id, acc);
+    if (node.type === "group" && node.prompt) index.set(node.prompt.id, dedupe([...acc, ...node.prompt.tags ?? []]));
     if (node.type === "group") {
       for (const child of node.children) visit(child, acc);
     } else {
@@ -85,6 +86,8 @@ var Engine = class _Engine {
   /** The run's ordered stream: every flow's events, each naming its flow. Empty and
    *  unwritten unless `options.log` asked for it. */
   engineLog = [];
+  /** The next engine-log `seq`: its own counter, since the log's length restarts after a clear. */
+  engineSeq = 0;
   engineTraceHandlers = /* @__PURE__ */ new Set();
   constructor(bundle, options = {}) {
     this.creationOptions = options;
@@ -182,6 +185,7 @@ var Engine = class _Engine {
       journal: null,
       customRng: options.rng,
       onDryChoice: options.onDryChoice,
+      onError: options.onError ?? ((e) => console.warn(`Patterplay: ${e.kind} on ${e.node} in flow '${e.flow}' failed, played through: ${e.message}`)),
       replayPromptOnChoose: options.replayPromptOnChoose ?? false,
       captionsOn: options.closedCaptions ?? true,
       // captions shown by default (full text)
@@ -375,10 +379,10 @@ var Engine = class _Engine {
    */
   resolveOpenAddress(scene, block) {
     if (scene !== void 0) {
-      const sceneId = this.resolveSceneRef(scene);
-      if (!this.host.bundle.scenes[sceneId]) throw new Error(`unknown scene: ${scene}`);
+      const sceneId = resolveScene(this.host, scene);
+      if (sceneId === void 0) 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);
+      const blockId = resolveBlock(this.host, sceneId, block);
       if (blockId === void 0) throw new Error(`unknown block: ${block}`);
       return { sceneId, blockId };
     }
@@ -389,21 +393,19 @@ var Engine = class _Engine {
     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. */
+  /** Resolve a scene reference to its internal id by the one address rule (see resolveScene); an
+   *  unknown one passes through, for the caller to find nothing. */
   resolveSceneRef(ref) {
     if (ref == null) return void 0;
-    if (this.host.bundle.scenes[ref]) return ref;
-    return this.sceneGameIdToId.get(ref) ?? ref;
+    return resolveScene(this.host, ref) ?? ref;
   }
-  /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
+  /** Resolve a block reference to its internal id by the one address rule (see resolveBlock): within its
+   *  scene, so a block of another scene resolves to nothing. With no scene, only an internal id resolves,
+   *  since a block's gameId is only unique within its scene. */
   resolveBlockRef(sceneId, ref) {
     if (ref == null) return void 0;
-    if (this.host.blockById.has(ref)) return ref;
-    if (sceneId != null) {
-      const id = this.blockGameIdToId.get(sceneId)?.get(ref);
-      if (id) return id;
-    }
-    return ref;
+    if (sceneId == null) return ref;
+    return resolveBlock(this.host, sceneId, ref);
   }
   /** The host-facing address (gameId) of a scene / block by internal id, or undefined if unknown.
    *  The inverse of the resolve helpers - for a host that wants to display / log the address. */
@@ -730,7 +732,7 @@ var Engine = class _Engine {
   emitEngine(flow, event, scene) {
     for (const h of this.engineTraceHandlers) h(flow, event);
     if (!this.host.logEnabled) return;
-    this.engineLog.push({ ...event, flow, seq: this.engineLog.length, ...scene ? { scene } : {} });
+    this.engineLog.push({ ...event, flow, seq: this.engineSeq++, ...scene ? { scene } : {} });
   }
   listProperties() {
     return this.host.patterSharedDecls.map((d) => ({
@@ -796,6 +798,8 @@ var Engine = class _Engine {
     this.refuseInCheckpoint("loadGame");
     const version = save.version;
     if (version !== 2 && version !== SAVE_VERSION) throw new Error(`unsupported save version: ${String(version)}`);
+    const flows = save.flows;
+    if (typeof flows !== "object" || flows === null || Array.isArray(flows)) throw new Error("malformed save: no flows");
     this.assertExternalScopes();
     const reg = this.host.registry;
     for (const [id, flow] of this.flowsById) {
@@ -843,10 +847,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). */
@@ -1008,7 +1015,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;
@@ -1016,11 +1023,11 @@ var Flow = class {
       this.stack = [];
       return true;
     }
-    const sceneId = this.host.sceneGameIdToId.get(scene) ?? (this.host.bundle.scenes[scene] ? scene : void 0);
+    const sceneId = resolveScene(this.host, scene);
     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);
+      blockId = resolveBlock(this.host, sceneId, block);
       if (blockId === void 0) return false;
     }
     if (!this.started) {
@@ -1028,7 +1035,7 @@ var Flow = class {
       return true;
     }
     this.pendingChoice = null;
-    this.pendingPromptBeat = null;
+    this.pendingPrompt = null;
     this.pendingPromptOwnerId = null;
     this.activeSnippet = null;
     this.beatIndex = 0;
@@ -1055,7 +1062,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
@@ -1065,10 +1072,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). */
@@ -1086,11 +1093,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" };
@@ -1130,7 +1137,7 @@ var Flow = class {
       if (this.flowEnded || this.pendingChoice) return;
       if (this.activeSnippet) {
         if (this.beatIndex < (this.activeSnippet.beats?.length ?? 0)) return;
-        this.runEffects(this.activeSnippet.onExit);
+        this.runEffects(this.activeSnippet.onExit, this.activeSnippet.id);
         const jump = this.activeSnippet.jump;
         this.activeSnippet = null;
         this.beatIndex = 0;
@@ -1209,8 +1216,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() {
@@ -1276,6 +1284,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)
       }
     };
@@ -1326,12 +1336,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 ------------------------------------------
@@ -1342,7 +1353,7 @@ var Flow = class {
     this.currentSceneId = sceneId;
     this.enter(sceneId);
     this.seedScene(scene);
-    this.runEffects(scene.onEntry);
+    this.runEffects(scene.onEntry, scene.id);
   }
   /**
    * Play one child of the active run. A snippet begins delivering. A group is
@@ -1378,7 +1389,7 @@ var Flow = class {
     return void 0;
   }
   beginSnippet(snippet) {
-    this.runEffects(snippet.onEnter);
+    this.runEffects(snippet.onEnter, snippet.id);
     this.activeSnippet = snippet;
     this.beatIndex = 0;
   }
@@ -1398,7 +1409,7 @@ var Flow = class {
       options.push({ id: child.id, prompt: this.promptFor(child), eligible, gameData: child.gameData });
       byId.set(child.id, child);
     }
-    if (options.length > 0) {
+    if (options.some((o) => o.eligible)) {
       this.emit({ type: "choice", group: group.id, options: options.map((o) => ({ id: o.id, eligible: o.eligible })) });
       this.pendingChoice = { groupId: group.id, options, byId };
       return;
@@ -1456,7 +1467,7 @@ var Flow = class {
   // -- Selectors ------------------------------------------------------------
   selectChild(group) {
     const verdicts = group.children.map((c) => ({ id: c.id, eligible: this.eligible(c) }));
-    const eligible = group.children.filter((c) => this.eligible(c));
+    const eligible = group.children.filter((_, i) => verdicts[i].eligible);
     const order = group.options?.order ?? "sequential";
     const exhaust = group.options?.exhaust ?? "once";
     const trace = (picked) => {
@@ -1503,8 +1514,9 @@ var Flow = class {
     const len = eligible.length;
     const stick = exhaust === "stick";
     const fill = () => (stick ? eligible.slice(0, len - 1) : eligible).map((c) => c.id);
+    const eligibleIds = new Set(eligible.map((c) => c.id));
     if (st.bag === void 0) st.bag = fill();
-    if (st.bag.length === 0) {
+    if (!st.bag.some((id2) => eligibleIds.has(id2))) {
       if (exhaust === "once") return null;
       if (stick) {
         const last = eligible[len - 1];
@@ -1512,13 +1524,14 @@ var Flow = class {
         return last;
       }
       st.bag = fill();
+      if (st.bag.length === 0) return null;
     }
-    const pool = st.bag;
+    const pool = st.bag.filter((id2) => eligibleIds.has(id2));
     const p = st.last !== void 0 && pool.length > 1 ? pool.indexOf(st.last) : -1;
     let i = Math.floor(this.rng() * (p >= 0 ? pool.length - 1 : pool.length));
     if (p >= 0 && i >= p) i++;
     const id = pool[i];
-    pool.splice(i, 1);
+    st.bag.splice(st.bag.indexOf(id), 1);
     st.last = id;
     return eligible.find((c) => c.id === id);
   }
@@ -1567,7 +1580,7 @@ var Flow = class {
   /** A child's Best-match score against the current state: 0 when it has no condition (the filler
    *  tier), else the specificity of its (already-passing) condition. */
   specScore(node) {
-    return node.condition ? this.matchedSpec(this.conditionAst(node.condition), true) : 0;
+    return node.condition ? this.matchedSpec(this.conditionAst(node.condition), true, node) : 0;
   }
   /**
    * The **matched-specificity** metric (parity contract): how many atomic constraints are actively
@@ -1577,8 +1590,15 @@ var Flow = class {
    * to hold?" (true at the root). Only `and`/`or`/`not`/`check_flags` are structural; every other
    * node (comparisons, scoped vars, literals, other calls) is an atom, evaluated whole.
    */
-  matchedSpec(node, want) {
-    const evalTruthy = (n) => truthy(evaluate(n, this.context(), patterDialect));
+  matchedSpec(node, want, owner) {
+    const evalTruthy = (n) => {
+      try {
+        return truthy(evaluate(n, this.context(), patterDialect));
+      } catch (err) {
+        this.reportError("best-match", owner.id, owner.condition, err);
+        return false;
+      }
+    };
     return scoreSpecificity(node, evalTruthy, { want });
   }
   /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
@@ -1610,17 +1630,36 @@ var Flow = class {
     return st;
   }
   // -- Effects + expressions ------------------------------------------------
-  runEffects(effects) {
+  /** Run an effect list. `owner` is the snippet or scene it belongs to, for an error report. */
+  runEffects(effects, owner) {
     for (const e of effects ?? []) {
-      const value = this.evalExpr(e.value);
-      const prev = this.host.logEnabled ? this.getProperty(e.target) : void 0;
-      this.writeProperty(e.target, value, false);
-      this.emit({ type: "write", target: e.target, value, ...prev !== void 0 ? { prev } : {} });
+      let value;
+      try {
+        value = this.evalExpr(e.value);
+        const prev = this.host.logEnabled ? this.getProperty(e.target) : void 0;
+        this.writeProperty(e.target, value, false);
+        this.emit({ type: "write", target: e.target, value, ...prev !== void 0 ? { prev } : {} });
+      } catch (err) {
+        this.reportError("effect", owner, e.value, err);
+      }
     }
   }
+  /** Whether a node's condition holds. A condition that fails to evaluate counts as false (see PlayError). */
   eligible(node) {
     if (!node.condition) return true;
-    return truthy(this.evalExpr(node.condition));
+    try {
+      return truthy(this.evalExpr(node.condition));
+    } catch (err) {
+      this.reportError("condition", node.id, node.condition, err);
+      return false;
+    }
+  }
+  /** Report a content error the engine is playing through: to the host's onError, and to the log. */
+  reportError(kind, node, expr, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const source = expr?.src;
+    this.host.onError({ flow: this.id, kind, node, ...source ? { source } : {}, message });
+    this.emit({ type: "diagnostic", kind, node, ...source ? { source } : {}, message });
   }
   evalExpr(expr) {
     return evaluate(this.conditionAst(expr), this.context(), patterDialect);
@@ -1726,6 +1765,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;
@@ -1795,23 +1855,23 @@ var Flow = class {
     if (!this.sceneBags.has(s)) {
       const bag = new PropertyBag(props.filter((d) => !shared.has(d.name.toLowerCase())), { pathPrefix: "@scene." });
       const key = keys.flowScene(this.id, s);
-      this.host.registry.mountOwned(key, bag, { owner: OWNER });
+      const claimed = mountClaims(this.host.registry, key, bag, journal !== null);
       this.registered.add(key);
       this.sceneBags.set(s, bag);
       if (journal) journal.undo.push(() => {
         if (this.sceneBags.get(s) !== bag) return;
-        this.host.registry.remove(key);
+        this.host.registry.remove(key, claimed ? { keep: true } : void 0);
         this.registered.delete(key);
         this.sceneBags.delete(s);
       });
     }
     if (!this.host.stageBags.has(s)) {
       const bag = new PropertyBag(props.filter((d) => shared.has(d.name.toLowerCase())), { pathPrefix: "@scene." });
-      this.host.registry.mountOwned(keys.stage(s), bag, { owner: OWNER });
+      const claimed = mountClaims(this.host.registry, keys.stage(s), bag, journal !== null);
       this.host.stageBags.set(s, bag);
       if (journal) journal.undo.push(() => {
         if (this.host.stageBags.get(s) !== bag) return;
-        this.host.registry.remove(keys.stage(s));
+        this.host.registry.remove(keys.stage(s), claimed ? { keep: true } : void 0);
         this.host.stageBags.delete(s);
       });
     }
@@ -1849,6 +1909,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) {
@@ -1871,6 +1938,11 @@ function deserialiseSelectors(rec) {
   }
   return map;
 }
+function mountClaims(registry, key, bag, ask) {
+  const before = ask ? JSON.stringify(bag.save()) : "";
+  registry.mountOwned(key, bag, { owner: OWNER });
+  return ask && JSON.stringify(bag.save()) !== before;
+}
 function toDecl(decl) {
   return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default };
 }
@@ -1882,6 +1954,12 @@ function selfBackedDecl(decl, scopeWritable) {
   const writable = decl.writable ?? scopeWritable;
   return writable === void 0 ? d : { ...d, writable };
 }
+function resolveScene(host, ref) {
+  return host.sceneGameIdToId.get(ref) ?? (host.bundle.scenes[ref] ? ref : void 0);
+}
+function resolveBlock(host, sceneId, ref) {
+  return host.blockGameIdToId.get(sceneId)?.get(ref) ?? (host.blockIndex.get(ref)?.sceneId === sceneId ? ref : void 0);
+}
 function splitHostRef(host, ref) {
   if (host.refSplitRevision !== host.registry.revision) {
     host.refSplitCache.clear();