@patterkit/runtime 0.20.0 → 0.22.0

package/dist/index.d.cts

@@ -14,6 +14,8 @@ type StepResult = {
     character?: string;
     characterName?: string;
     direction?: string;
+    qualifier?: string;
+    qualifierName?: string;
     gameData?: GameData;
     tags?: string[];
 } | {
@@ -44,6 +46,10 @@ interface BeatInfo {
     characterName?: string;
     /** Performance direction (line only). */
     direction?: string;
+    /** Speaker qualifier `gameId` (line only), e.g. `vo`. */
+    qualifier?: string;
+    /** The qualifier's shown name (source locale), e.g. `V.O.`. */
+    qualifierName?: string;
     /** Source text, un-interpolated (line / text). Omitted for gameEvent and IDs-only bundles. */
     text?: string;
     /** Author gameData overrides on this beat (raw, as the step carries them). Omitted when empty. */
@@ -111,6 +117,9 @@ interface ChoicePrompt {
     /** The speaker's resolved player-facing name (locale-aware; absent when the character has none). */
     characterName?: string;
     direction?: string;
+    /** The speaker qualifier's `gameId` (`vo`), and its resolved shown name (locale-aware). */
+    qualifier?: string;
+    qualifierName?: string;
 }
 /** A single option of a pending `choice` group. */
 interface ChoiceOption {
@@ -352,6 +361,8 @@ interface FlowHost {
     defaultStrings: Record<string, string>;
     /** Cast canonical name -> authoring `displayName` (the unlocalised fallback when no loc string exists). */
     castDisplay: Map<string, string>;
+    /** Speaker qualifier gameId -> authored name (the unlocalised fallback when no loc string exists). */
+    qualifierDisplay: Map<string, string>;
     nodeIndex: Map<string, SelectableNode>;
     blockIndex: Map<string, {
         sceneId: string;
@@ -680,8 +691,6 @@ declare class Engine {
      *  across the family 2026-09-05, after a Storylets venue clock and this project's coverage driver
      *  were each refused the one property they existed to move.) */
     setProperty(ref: string, value: ScalarValue): void;
-    /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
-     *  value, declared default (for reset), and enum options. Mirrors the Unity / Godot ports. */
     /** The run's decisions, in order, each naming the flow it happened in. Empty unless the
      *  run was opened with `log: true`. A flow's own log stays flow-local; this is the only
      *  place a story spanning several flows reads as one sequence. */
@@ -696,6 +705,8 @@ declare class Engine {
     /** How many times each node has been entered across every flow, by node id: the shared count. With a
      *  flow's own {@link Flow.getVisitCounts}, every visit count the run keeps, read without a save. */
     getVisitCounts(): Record<string, number>;
+    /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
+     *  value, declared default (for reset), and enum options. Every runtime has the same call. */
     listProperties(): PropertyRow[];
     private splitShared;
     /** The shared `@patter` values alone, as `{ patter: {...} }`.
@@ -994,6 +1005,10 @@ declare class Flow {
      *  locale, else the authoring `displayName`. Undefined when the character has no display name at all
      *  (the host falls back to the `character` token itself). */
     private resolveCharacterName;
+    /** A speaker qualifier's shown name, resolved as a character's is: the `qualifier:<gameId>` string in the
+     *  active locale, else the default locale, else the authored name. Undefined in IDs-only mode (the game
+     *  maps the `qualifier` gameId itself). */
+    private resolveQualifierName;
     /** Split a ref into scope + name. Tokens: `@scene`, registered tokens, else `@patter` (incl. bare `@name`). */
     private splitRef;
     /** A fresh, unregistered bag for the NOT-shared `@patter` globals (the shared ones live on the host). */

package/dist/index.d.ts

@@ -14,6 +14,8 @@ type StepResult = {
     character?: string;
     characterName?: string;
     direction?: string;
+    qualifier?: string;
+    qualifierName?: string;
     gameData?: GameData;
     tags?: string[];
 } | {
@@ -44,6 +46,10 @@ interface BeatInfo {
     characterName?: string;
     /** Performance direction (line only). */
     direction?: string;
+    /** Speaker qualifier `gameId` (line only), e.g. `vo`. */
+    qualifier?: string;
+    /** The qualifier's shown name (source locale), e.g. `V.O.`. */
+    qualifierName?: string;
     /** Source text, un-interpolated (line / text). Omitted for gameEvent and IDs-only bundles. */
     text?: string;
     /** Author gameData overrides on this beat (raw, as the step carries them). Omitted when empty. */
@@ -111,6 +117,9 @@ interface ChoicePrompt {
     /** The speaker's resolved player-facing name (locale-aware; absent when the character has none). */
     characterName?: string;
     direction?: string;
+    /** The speaker qualifier's `gameId` (`vo`), and its resolved shown name (locale-aware). */
+    qualifier?: string;
+    qualifierName?: string;
 }
 /** A single option of a pending `choice` group. */
 interface ChoiceOption {
@@ -352,6 +361,8 @@ interface FlowHost {
     defaultStrings: Record<string, string>;
     /** Cast canonical name -> authoring `displayName` (the unlocalised fallback when no loc string exists). */
     castDisplay: Map<string, string>;
+    /** Speaker qualifier gameId -> authored name (the unlocalised fallback when no loc string exists). */
+    qualifierDisplay: Map<string, string>;
     nodeIndex: Map<string, SelectableNode>;
     blockIndex: Map<string, {
         sceneId: string;
@@ -680,8 +691,6 @@ declare class Engine {
      *  across the family 2026-09-05, after a Storylets venue clock and this project's coverage driver
      *  were each refused the one property they existed to move.) */
     setProperty(ref: string, value: ScalarValue): void;
-    /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
-     *  value, declared default (for reset), and enum options. Mirrors the Unity / Godot ports. */
     /** The run's decisions, in order, each naming the flow it happened in. Empty unless the
      *  run was opened with `log: true`. A flow's own log stays flow-local; this is the only
      *  place a story spanning several flows reads as one sequence. */
@@ -696,6 +705,8 @@ declare class Engine {
     /** How many times each node has been entered across every flow, by node id: the shared count. With a
      *  flow's own {@link Flow.getVisitCounts}, every visit count the run keeps, read without a save. */
     getVisitCounts(): Record<string, number>;
+    /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
+     *  value, declared default (for reset), and enum options. Every runtime has the same call. */
     listProperties(): PropertyRow[];
     private splitShared;
     /** The shared `@patter` values alone, as `{ patter: {...} }`.
@@ -994,6 +1005,10 @@ declare class Flow {
      *  locale, else the authoring `displayName`. Undefined when the character has no display name at all
      *  (the host falls back to the `character` token itself). */
     private resolveCharacterName;
+    /** A speaker qualifier's shown name, resolved as a character's is: the `qualifier:<gameId>` string in the
+     *  active locale, else the default locale, else the authored name. Undefined in IDs-only mode (the game
+     *  maps the `qualifier` gameId itself). */
+    private resolveQualifierName;
     /** Split a ref into scope + name. Tokens: `@scene`, registered tokens, else `@patter` (incl. bare `@name`). */
     private splitRef;
     /** A fresh, unregistered bag for the NOT-shared `@patter` globals (the shared ones live on the host). */

package/dist/index.js

@@ -4,7 +4,7 @@ import { matchedSpecificity as scoreSpecificity } from "@wildwinter/expr-specifi
 import { ScopeRegistry } from "@wildwinter/scoperegistry";
 import { defaultFor, PropertyBag } from "@wildwinter/scoperegistry";
 import { patterDialect, interpolate, splitRef, stripCaptions } from "@patterkit/dialect";
-import { walkNodes, effectiveGameId, castStringKey, DEFAULT_CAPTION_DELIMITERS, DEFAULT_CAPTION_CHARACTER } from "@patterkit/model";
+import { walkNodes, effectiveGameId, castStringKey, qualifierStringKey, DEFAULT_CAPTION_DELIMITERS, DEFAULT_CAPTION_CHARACTER } from "@patterkit/model";
 
 // src/tags.ts
 function dedupe(tags) {
@@ -43,6 +43,18 @@ function buildTagIndex(bundle) {
 // src/engine.ts
 import { SAVE_VERSION } from "@patterkit/model";
 var astCache = /* @__PURE__ */ new WeakMap();
+var tagIndexCache = /* @__PURE__ */ new WeakMap();
+function tagIndexFor(bundle) {
+  let index = tagIndexCache.get(bundle);
+  if (!index) {
+    index = buildTagIndex(bundle);
+    tagIndexCache.set(bundle, index);
+  }
+  return index;
+}
+function tagsOf(host, id) {
+  return host.tagIndex.get(id)?.slice();
+}
 var OWNER = "Patter";
 var esc = (id) => id.replace(/%/g, "%25").replace(/\//g, "%2F");
 var OWNS_REGISTRY = /* @__PURE__ */ Symbol("ownsRegistry");
@@ -105,6 +117,8 @@ var Engine = class _Engine {
     }
     const castDisplay = /* @__PURE__ */ new Map();
     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);
     this.defaultSeed = (options.seed ?? 2654435769) >>> 0;
     const nodeIndex = /* @__PURE__ */ new Map();
     const blockIndex = /* @__PURE__ */ new Map();
@@ -165,13 +179,14 @@ var Engine = class _Engine {
       strings,
       defaultStrings,
       castDisplay,
+      qualifierDisplay,
       nodeIndex,
       blockIndex,
       blockById,
       sceneGameIdToId: this.sceneGameIdToId,
       blockGameIdToId: this.blockGameIdToId,
       // same instances the engine resolves with
-      tagIndex: buildTagIndex(bundle),
+      tagIndex: tagIndexFor(bundle),
       registry,
       ownsRegistry,
       patterBag,
@@ -430,18 +445,18 @@ var Engine = class _Engine {
    * delivered step carries. Empty array for an unknown id or a beat with no tags anywhere up the chain.
    */
   tagsForBeat(beatId) {
-    return this.host.tagIndex.get(beatId) ?? [];
+    return tagsOf(this.host, beatId) ?? [];
   }
   /** A scene's own tags (by internal id or gameId address). Empty when none / unknown. */
   tagsForScene(sceneRef) {
     const id = this.resolveSceneRef(sceneRef);
-    return (id != null ? this.host.tagIndex.get(id) : void 0) ?? [];
+    return (id != null ? tagsOf(this.host, id) : void 0) ?? [];
   }
   /** A block's accumulated tags (scene + block), by scene + block ref (id or gameId). Empty when none / unknown. */
   tagsForBlock(sceneRef, blockRef) {
     const sceneId = this.resolveSceneRef(sceneRef);
     const id = this.resolveBlockRef(sceneId, blockRef);
-    return (id != null ? this.host.tagIndex.get(id) : void 0) ?? [];
+    return (id != null ? tagsOf(this.host, id) : void 0) ?? [];
   }
   /**
    * A scene's own author gameData (by internal id or gameId address): the RAW sparse overrides, exactly
@@ -560,7 +575,7 @@ var Engine = class _Engine {
   }
   /** One beat's static data (source locale), the same shape a delivered step carries. */
   beatInfo(beat) {
-    const tags = this.host.tagIndex.get(beat.id);
+    const tags = tagsOf(this.host, beat.id);
     const info = { id: beat.id, kind: beat.kind };
     if (beat.kind === "line") {
       if (beat.character !== void 0) {
@@ -569,6 +584,11 @@ var Engine = class _Engine {
         if (name !== void 0) info.characterName = name;
       }
       if (beat.direction !== void 0) info.direction = beat.direction;
+      if (beat.qualifier !== void 0) {
+        info.qualifier = beat.qualifier;
+        const name = this.host.defaultStrings[qualifierStringKey(beat.qualifier)] ?? this.host.qualifierDisplay.get(beat.qualifier);
+        if (name !== void 0) info.qualifierName = name;
+      }
     }
     if (beat.kind === "line" || beat.kind === "text") {
       const source = this.host.defaultStrings[beat.id];
@@ -580,7 +600,7 @@ var Engine = class _Engine {
   }
   /** A `{ tags }` fragment for an id, present only when the id has accumulated tags (keeps output tidy). */
   tagsField(id) {
-    const tags = this.host.tagIndex.get(id);
+    const tags = tagsOf(this.host, id);
     return tags && tags.length ? { tags } : {};
   }
   /** Retrieve an open flow by id (undefined if none / closed). */
@@ -717,8 +737,6 @@ var Engine = class _Engine {
     this.host.registry.set(scope, name, value, { host: true });
     if (this.host.journal && prev !== void 0) this.host.journal.undo.push(() => this.host.registry.set(scope, name, prev, { host: true }));
   }
-  /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
-   *  value, declared default (for reset), and enum options. Mirrors the Unity / Godot ports. */
   /** The run's decisions, in order, each naming the flow it happened in. Empty unless the
    *  run was opened with `log: true`. A flow's own log stays flow-local; this is the only
    *  place a story spanning several flows reads as one sequence. */
@@ -750,6 +768,8 @@ var Engine = class _Engine {
   getVisitCounts() {
     return Object.fromEntries(this.host.sharedVisits);
   }
+  /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
+   *  value, declared default (for reset), and enum options. Every runtime has the same call. */
   listProperties() {
     return this.host.patterSharedDecls.map((d) => ({
       name: d.name,
@@ -1737,7 +1757,7 @@ var Flow = class {
   };
   // -- Strings / beats ------------------------------------------------------
   beatResult(beat) {
-    const tags = this.host.tagIndex.get(beat.id);
+    const tags = tagsOf(this.host, beat.id);
     const withTags = tags && tags.length ? { tags } : {};
     switch (beat.kind) {
       case "gameEvent":
@@ -1757,6 +1777,8 @@ var Flow = class {
           character: silent ? void 0 : beat.character,
           characterName: silent ? void 0 : this.resolveCharacterName(beat.character),
           direction: silent ? void 0 : beat.direction,
+          qualifier: silent ? void 0 : beat.qualifier,
+          qualifierName: silent ? void 0 : this.resolveQualifierName(beat.qualifier),
           gameData: beat.gameData,
           ...withTags
         };
@@ -1795,7 +1817,15 @@ var Flow = class {
     const beat = this.promptBeatOf(node);
     if (!beat) return void 0;
     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 };
+    return beat.kind === "line" ? {
+      kind: "line",
+      text: this.captionLine(text),
+      character: beat.character,
+      characterName: this.resolveCharacterName(beat.character),
+      direction: beat.direction,
+      qualifier: beat.qualifier,
+      qualifierName: this.resolveQualifierName(beat.qualifier)
+    } : { kind: "text", text };
   }
   /** An option's AUTHORED prompt beat: an Option group's own `prompt`. The only prompt a replay speaks. */
   authoredPromptOf(node) {
@@ -1804,7 +1834,7 @@ var Flow = class {
   /** 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 tags = tagsOf(this.host, 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 {
@@ -1814,6 +1844,8 @@ var Flow = class {
       character: shown.character,
       characterName: shown.characterName,
       direction: shown.direction,
+      qualifier: shown.qualifier,
+      qualifierName: shown.qualifierName,
       gameData: beat.gameData,
       ...withTags
     };
@@ -1850,6 +1882,15 @@ var Flow = class {
     const key = castStringKey(character);
     return this.host.strings[key] ?? this.host.defaultStrings[key] ?? this.host.castDisplay.get(character);
   }
+  /** A speaker qualifier's shown name, resolved as a character's is: the `qualifier:<gameId>` string in the
+   *  active locale, else the default locale, else the authored name. Undefined in IDs-only mode (the game
+   *  maps the `qualifier` gameId itself). */
+  resolveQualifierName(qualifier) {
+    if (qualifier === void 0) return void 0;
+    if (this.host.emitIds) return void 0;
+    const key = qualifierStringKey(qualifier);
+    return this.host.strings[key] ?? this.host.defaultStrings[key] ?? this.host.qualifierDisplay.get(qualifier);
+  }
   /** Split a ref into scope + name. Tokens: `@scene`, registered tokens, else `@patter` (incl. bare `@name`). */
   splitRef(ref) {
     return splitHostRef(this.host, ref);
@@ -1946,6 +1987,8 @@ function savedPrompt(p) {
   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;
+  if (p.qualifier !== void 0) out.qualifier = p.qualifier;
+  if (p.qualifierName !== void 0) out.qualifierName = p.qualifierName;
   return out;
 }
 function serialiseSelectors(map) {