@patterkit/runtime 0.4.5 → 0.5.0

package/CHANGELOG.md

@@ -25,6 +25,18 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-21
+
+### Added
+
+- **Cast lists you can query at runtime.** Three static reads answer "who is in this?": the cast the
+  project declares, the speakers of a scene, and the speakers of one block. Scene and block refs take
+  an internal id or a gameId address. The result is the character token a line beat carries, deduped
+  and ordered by first appearance, and it is derived from the AUTHORED structure, so a speaker behind a
+  condition, inside a group, or voicing a choice prompt is included: it answers who *can* speak, not
+  who a given playthrough heard. Held across all four runtimes by the conformance corpus.
+  `engine.getCast()`, `engine.castForScene(sceneRef)`, `engine.castForBlock(sceneRef, blockRef)`.
+
 ## [0.4.5] - 2026-08-20
 
 ### Changed

package/dist/index.cjs

@@ -360,6 +360,42 @@ var Engine = class _Engine {
     const id = this.resolveBlockRef(sceneId, blockRef);
     return (id != null ? this.host.tagIndex.get(id) : void 0) ?? [];
   }
+  /**
+   * Every cast member the PROJECT declares, in authored order - the same list `describeBundle` counts.
+   * A superset of any scene's cast: the validator holds a beat's `character` to a declared member, so
+   * {@link castForScene} and {@link castForBlock} only ever return names that appear here.
+   */
+  getCast() {
+    const names = [];
+    for (const c of this.host.bundle.cast ?? []) if (c?.name) names.push(c.name);
+    return names;
+  }
+  /**
+   * A scene's cast: the `character` token of every speaker with a line anywhere in it, deduped, in
+   * first-appearance order. Static, like {@link getOutline}: it walks the authored structure, so a
+   * speaker behind a condition, inside any group, or voicing a choice prompt counts - this is who CAN
+   * speak in the scene, not who a given playthrough heard. Empty for an unknown ref, or a scene with no
+   * dialogue. Tokens, not display names: resolve those through the delivered step (`characterName`),
+   * which is what follows `setLocale`.
+   */
+  castForScene(sceneRef) {
+    const id = this.resolveSceneRef(sceneRef);
+    const scene = id != null ? this.host.bundle.scenes[id] : void 0;
+    if (!scene) return [];
+    const out = /* @__PURE__ */ new Set();
+    for (const block of scene.blocks) collectCast(block.children, out);
+    return [...out];
+  }
+  /** One block's cast, by scene + block ref (id or gameId). {@link castForScene} scoped to a block. */
+  castForBlock(sceneRef, blockRef) {
+    const sceneId = this.resolveSceneRef(sceneRef);
+    const id = this.resolveBlockRef(sceneId, blockRef);
+    const block = id != null ? this.host.blockById.get(id) : void 0;
+    if (!block) return [];
+    const out = /* @__PURE__ */ new Set();
+    collectCast(block.children, out);
+    return [...out];
+  }
   /**
    * The authored structure as a nested tree: scenes -> blocks -> children (groups + snippets, groups
    * preserved) -> a snippet's beats. Static (no flow / play state); per-beat data is read at the source
@@ -1353,6 +1389,15 @@ var Flow = class {
     }
   }
 };
+function collectCast(nodes, out) {
+  (0, import_model.walkNodes)(nodes, (n) => {
+    if (n.type === "group") {
+      if (n.prompt?.kind === "line" && n.prompt.character) out.add(n.prompt.character);
+      return;
+    }
+    for (const beat of n.beats ?? []) if (beat.kind === "line" && beat.character) out.add(beat.character);
+  });
+}
 function serialiseSelectors(map) {
   const out = {};
   for (const [id, st] of map) {