@patterkit/runtime 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -33,6 +33,29 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-10-14
+
+### Added
+
+- **`flow.stepFor(beatId)`**: the step this flow would deliver for a beat right now, built by the same function
+  `advance` uses, so it carries the text in the active locale (interpolated, unless the project is voiced, with
+  closed captions applied) and the speaker's names and label, its pause, Game Data, and tags. It doesn't move the
+  flow, count a visit, or run an effect. Undefined for an id that is neither a beat nor an option's prompt. The
+  conformance corpus pins it on every runtime.
+
+## [0.25.0] - 2026-10-14
+
+### Added
+
+- **Speaker labels**: a line step, a line choice prompt, and a beat's info carry `speakerLabel`, the name to
+  show for the speaker, localised. With a qualifier it is the character's own label for that pair when the
+  project gives one (`speaker:<NAME>:<qualifier>`), else the project's speaker pattern (`speaker:pattern`,
+  `{name} ({qualifier})` by default) filled with the shown name and the qualifier's shown name; with none, the
+  shown name (the token when the cast gives none). Each piece follows the active locale, then the default, then
+  the authored value. A translated pair label counts only for a pair the project overrides. Absent with no
+  speaker, on a silenced line, and in IDs-only mode. Saved choice prompts carry it, and an older save works it
+  out again on load.
+
 ## [0.24.0] - 2026-10-11
 
 ### Added

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -134,6 +134,25 @@ function padIndexFor(bundle) {
   }
   return index;
 }
+var beatIndexCache = /* @__PURE__ */ new WeakMap();
+function beatIndexFor(bundle) {
+  let index = beatIndexCache.get(bundle);
+  if (index) return index;
+  index = /* @__PURE__ */ new Map();
+  for (const scene of Object.values(bundle.scenes)) {
+    for (const block of scene.blocks) {
+      (0, import_model2.walkNodes)(block.children, (n) => {
+        if (n.type === "group") {
+          if (n.prompt) index.set(n.prompt.id, n.prompt);
+          return;
+        }
+        for (const beat of n.beats ?? []) index.set(beat.id, beat);
+      });
+    }
+  }
+  beatIndexCache.set(bundle, index);
+  return index;
+}
 function tagsOf(host, id) {
   return host.tagIndex.get(id)?.slice();
 }
@@ -202,6 +221,9 @@ var Engine = class _Engine {
     for (const c of bundle.cast ?? []) if (c.displayName) castDisplay.set(c.name, c.displayName);
     const qualifierDisplay = /* @__PURE__ */ new Map();
     for (const q of bundle.qualifiers ?? []) if (q?.gameId) qualifierDisplay.set(q.gameId, q.name);
+    const speakerLabels = /* @__PURE__ */ new Map();
+    for (const c of bundle.cast ?? []) for (const [q, label] of Object.entries(c.qualifierLabels ?? {})) if (typeof label === "string") speakerLabels.set(`${c.name}\0${q}`, label);
+    const speakerPattern = bundle.speakerPattern ?? import_model2.DEFAULT_SPEAKER_PATTERN;
     this.defaultSeed = (options.seed ?? 2654435769) >>> 0;
     const nodeIndex = /* @__PURE__ */ new Map();
     const blockIndex = /* @__PURE__ */ new Map();
@@ -263,6 +285,8 @@ var Engine = class _Engine {
       defaultStrings,
       castDisplay,
       qualifierDisplay,
+      speakerLabels,
+      speakerPattern,
       nodeIndex,
       blockIndex,
       blockById,
@@ -673,6 +697,8 @@ var Engine = class _Engine {
         const name = this.host.defaultStrings[(0, import_model2.qualifierStringKey)(beat.qualifier)] ?? this.host.qualifierDisplay.get(beat.qualifier);
         if (name !== void 0) info.qualifierName = name;
       }
+      const label = speakerLabelOf(this.host, beat.character, beat.qualifier, true);
+      if (label !== void 0) info.speakerLabel = label;
     }
     if (beat.kind === "line" || beat.kind === "text") {
       const pad = this.host.padIndex.get(beat.id);
@@ -1379,6 +1405,18 @@ var Flow = class {
   getVisitCounts() {
     return Object.fromEntries(this.visitCounts);
   }
+  /**
+   * The step this flow would deliver for beat `beatId` right now, as `advance` would give it: its text in the
+   * active locale, interpolated against this flow's values (unless the project is voiced), closed captions
+   * applied, and the speaker's names and label, its pause, Game Data, and tags. Built by the same function that
+   * builds a delivered step, so the two can't differ. It doesn't move the flow, count a visit, or run an effect.
+   * Undefined for an id that is neither a beat nor an option's prompt. For a game that keeps lines by id and
+   * shows them again (after a load, or a language switch).
+   */
+  stepFor(beatId) {
+    const beat = beatIndexFor(this.host.bundle).get(beatId);
+    return beat ? this.beatResult(beat) : void 0;
+  }
   /** The options of a pending choice (empty when not at a choice point). */
   getChoices() {
     return this.pendingChoice?.options ?? [];
@@ -1511,7 +1549,8 @@ var Flow = class {
         if (!node) continue;
         byId.set(o.id, node);
         const { prompt: saved, ...rest } = o;
-        options.push({ ...rest, ...saved ? { prompt: { ...saved, padAfter: saved.padAfter ?? this.promptPadOf(node) } } : {} });
+        const label = saved?.kind === "line" && saved.speakerLabel === void 0 ? speakerLabelOf(this.host, saved.character, saved.qualifier) : void 0;
+        options.push({ ...rest, ...saved ? { prompt: { ...saved, padAfter: saved.padAfter ?? this.promptPadOf(node), ...label !== void 0 ? { speakerLabel: label } : {} } } : {} });
       }
       if (options.length > 0) this.pendingChoice = { groupId: c.pendingChoice.groupId, options, byId };
     }
@@ -1520,7 +1559,9 @@ var Flow = class {
     if (this.pendingPromptOwnerId) {
       const owner = this.host.nodeIndex.get(this.pendingPromptOwnerId);
       const beat = owner ? this.authoredPromptOf(owner) : void 0;
-      if (beat) this.pendingPrompt = { beat, ...c.pendingPrompt ? { shown: { ...c.pendingPrompt, padAfter: c.pendingPrompt.padAfter ?? this.padOf(beat.id) } } : {} };
+      const saved = c.pendingPrompt;
+      const label = saved?.kind === "line" && saved.speakerLabel === void 0 ? speakerLabelOf(this.host, saved.character, saved.qualifier) : void 0;
+      if (beat) this.pendingPrompt = { beat, ...saved ? { shown: { ...saved, padAfter: saved.padAfter ?? this.padOf(beat.id), ...label !== void 0 ? { speakerLabel: label } : {} } } : {} };
       else this.pendingPromptOwnerId = null;
     }
   }
@@ -1906,6 +1947,7 @@ var Flow = class {
           direction: silent ? void 0 : beat.direction,
           qualifier: silent ? void 0 : beat.qualifier,
           qualifierName: silent ? void 0 : this.resolveQualifierName(beat.qualifier),
+          speakerLabel: silent ? void 0 : speakerLabelOf(this.host, beat.character, beat.qualifier),
           padAfter: this.padOf(beat.id),
           // a silent line still fires, so it still carries its pause
           gameData: beat.gameData,
@@ -1955,6 +1997,7 @@ var Flow = class {
       direction: beat.direction,
       qualifier: beat.qualifier,
       qualifierName: this.resolveQualifierName(beat.qualifier),
+      speakerLabel: speakerLabelOf(this.host, beat.character, beat.qualifier),
       padAfter
     } : { kind: "text", text, padAfter };
   }
@@ -1977,6 +2020,7 @@ var Flow = class {
       direction: shown.direction,
       qualifier: shown.qualifier,
       qualifierName: shown.qualifierName,
+      speakerLabel: shown.speakerLabel,
       padAfter: this.padOf(beat.id),
       gameData: beat.gameData,
       ...withTags
@@ -2122,6 +2166,16 @@ function collectCast(nodes, out) {
     for (const beat of n.beats ?? []) if (beat.kind === "line" && beat.character) out.add(beat.character);
   });
 }
+function speakerLabelOf(host, character, qualifier, source = false) {
+  if (!character || host.emitIds) return void 0;
+  const lookup = (key) => (source ? void 0 : host.strings[key]) ?? host.defaultStrings[key];
+  const name = lookup((0, import_model2.castStringKey)(character)) ?? host.castDisplay.get(character) ?? character;
+  if (qualifier === void 0) return name;
+  const own = host.speakerLabels.get(`${character}\0${qualifier}`);
+  if (own !== void 0) return lookup((0, import_model2.speakerLabelKey)(character, qualifier)) ?? own;
+  const shown = lookup((0, import_model2.qualifierStringKey)(qualifier)) ?? host.qualifierDisplay.get(qualifier) ?? qualifier;
+  return (0, import_model2.formatSpeakerLabel)(lookup(import_model2.SPEAKER_PATTERN_KEY) ?? host.speakerPattern, name, shown);
+}
 function gameDataField(gameData) {
   return gameData && Object.keys(gameData).length ? { gameData } : {};
 }
@@ -2132,6 +2186,7 @@ function savedPrompt(p) {
   if (p.direction !== void 0) out.direction = p.direction;
   if (p.qualifier !== void 0) out.qualifier = p.qualifier;
   if (p.qualifierName !== void 0) out.qualifierName = p.qualifierName;
+  if (p.speakerLabel !== void 0) out.speakerLabel = p.speakerLabel;
   if (typeof p.padAfter === "number") out.padAfter = p.padAfter;
   return out;
 }