@patterkit/runtime 0.25.0 → 0.26.0

package/CHANGELOG.md

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

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();
 }
@@ -1386,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 ?? [];