@patterkit/runtime 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -33,6 +33,17 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-10-10
+
+### Added
+
+- **Speaker qualifiers**: a line can say how it is delivered, a screenplay's `TAM (O.S.)`, without becoming a
+  second character. A `line` step, and a line-kind choice prompt, carries `qualifier`, the qualifier's `gameId`
+  (`vo`, `os`, `radio`, or the project's own), and `qualifierName`, its shown name, resolved as `characterName`
+  is: the active locale's `qualifier:<gameId>` string, then the default locale's, then the authored name.
+  `qualifierName` is absent in an IDs-only build, and both are dropped on a line silenced by closed captions.
+  Saves and the outline and beat sequence carry them too. What a qualifier means is the game's to decide.
+
 ## [0.21.0] - 2026-10-07
 
 ### Changed

package/dist/index.cjs

@@ -150,6 +150,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();
@@ -210,6 +212,7 @@ var Engine = class _Engine {
       strings,
       defaultStrings,
       castDisplay,
+      qualifierDisplay,
       nodeIndex,
       blockIndex,
       blockById,
@@ -614,6 +617,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[(0, import_model.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];
@@ -1802,6 +1810,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
         };
@@ -1840,7 +1850,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) {
@@ -1859,6 +1877,8 @@ var Flow = class {
       character: shown.character,
       characterName: shown.characterName,
       direction: shown.direction,
+      qualifier: shown.qualifier,
+      qualifierName: shown.qualifierName,
       gameData: beat.gameData,
       ...withTags
     };
@@ -1895,6 +1915,15 @@ var Flow = class {
     const key = (0, import_model.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 = (0, import_model.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);
@@ -1991,6 +2020,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) {