@patterkit/runtime 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -33,6 +33,31 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-10-10
+
+### Added
+
+- **Line padding**: the writer's pause after a line, in seconds. A `line` or `text` step carries `padAfter`,
+  resolved from the beat's own value, else the nearest `padAfterDefault` above it (its snippet, each group
+  around it, innermost first, its block, its scene), else the project's, else the built-in 0.6. Negative is a
+  cut-in, the next line (or game event) starting that long before this one ends; it is clamped to zero only on
+  a snippet's last line or text beat, where nothing certain follows. A choice option's `prompt` carries its
+  `padAfter` too, resolved through its option and never clamped, for a game that voices the prompts itself.
+  The outline and beat sequence carry `padAfter` and, when the beat sets its own, `ownPadAfter`.
+  `DEFAULT_PAD_AFTER` (0.6) is exported. What to do with it is the game's: the docs give the timing
+  rules a writer expects.
+
+## [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/README.md

@@ -44,6 +44,13 @@ for (;;) {
 }
 ```
 
+A `line` step carries `id`, `text`, `character`, `characterName`, `direction`, and, when the line has a
+speaker qualifier, `qualifier` (its `gameId`, `os`) and `qualifierName` (its shown name, `O.S.`). Line and
+text steps both carry `padAfter`, the writer's pause after the beat in seconds, already resolved; a negative
+one means the next line cuts in. Line, text, and game event steps can carry `gameData` and `tags`. The
+[step shapes](https://patterkit.dev/play/engine/#step-shapes) give the full list and the timing rules a game
+should follow.
+
 `new Engine(bundle, options)` takes `{ rng?, seed?, locale?, hostScopes?, registry?, replayPromptOnChoose?, closedCaptions? }`:
 - `hostScopes` binds the scopes your game owns, by token, each `{ get(name), set?(name, value) }`: for World
   Properties, `hostScopes: { world: { get, set } }`. Leave `world` unbound and the runtime self-backs `@world`
@@ -60,8 +67,8 @@ state, visit counts, and PRNG are untouched - so a game's "language" setting can
 rebuilding the engine or losing the player's place.
 
 The above is the **Embedded** build (strings ship inside the `.patterc`). An **IDs-only** build ships no
-strings: `step.text` is the beat **ID** and `step.characterName` is omitted - your game localises the IDs in
-its own system, then applies `{@ref}` replacement with **`flow.interpolate(yourString)`**. See the
+strings: `step.text` is the beat **ID**, and `step.characterName` and `step.qualifierName` are omitted, so
+your game localises the IDs in its own system, then applies `{@ref}` replacement with **`flow.interpolate(yourString)`**. See the
 [Localisation guide](https://patterkit.dev/play/localisation/) for both modes across all four runtimes.
 
 ## Drop-in (`<script>`)

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Checkpoint: () => Checkpoint,
+  DEFAULT_PAD_AFTER: () => import_model5.DEFAULT_PAD_AFTER,
   Engine: () => Engine,
   Flow: () => Flow,
   buildTagIndex: () => buildTagIndex,
@@ -37,7 +38,7 @@ var import_expr_specificity = require("@wildwinter/expr-specificity");
 var import_scoperegistry = require("@wildwinter/scoperegistry");
 var import_scoperegistry2 = require("@wildwinter/scoperegistry");
 var import_dialect = require("@patterkit/dialect");
-var import_model = require("@patterkit/model");
+var import_model2 = require("@patterkit/model");
 
 // src/tags.ts
 function dedupe(tags) {
@@ -73,8 +74,47 @@ function buildTagIndex(bundle) {
   return index;
 }
 
+// src/pads.ts
+var import_model = require("@patterkit/model");
+var spoken = (b) => b.kind === "line" || b.kind === "text";
+var num = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+function buildPadIndex(bundle) {
+  const index = /* @__PURE__ */ new Map();
+  const set = (beat, inherited, clamp) => {
+    const own = beat.kind === "gameEvent" ? void 0 : num(beat.padAfter);
+    let resolved = own ?? inherited;
+    if (clamp && resolved < 0) resolved = 0;
+    index.set(beat.id, own !== void 0 ? { own, resolved } : { resolved });
+  };
+  const visit = (node, inherited) => {
+    const def = num(node.padAfterDefault) ?? inherited;
+    if (node.type === "group") {
+      if (node.prompt) set(node.prompt, def, false);
+      for (const child of node.children) visit(child, def);
+      return;
+    }
+    const beats = node.beats ?? [];
+    let last = -1;
+    beats.forEach((b, i) => {
+      if (spoken(b)) last = i;
+    });
+    beats.forEach((b, i) => {
+      if (spoken(b)) set(b, def, i === last);
+    });
+  };
+  const projectDefault = num(bundle.padAfterDefault) ?? import_model.DEFAULT_PAD_AFTER;
+  for (const scene of Object.values(bundle.scenes)) {
+    const sceneDefault = num(scene.padAfterDefault) ?? projectDefault;
+    for (const block of scene.blocks) {
+      const blockDefault = num(block.padAfterDefault) ?? sceneDefault;
+      for (const child of block.children) visit(child, blockDefault);
+    }
+  }
+  return index;
+}
+
 // src/engine.ts
-var import_model2 = require("@patterkit/model");
+var import_model3 = require("@patterkit/model");
 var astCache = /* @__PURE__ */ new WeakMap();
 var tagIndexCache = /* @__PURE__ */ new WeakMap();
 function tagIndexFor(bundle) {
@@ -85,6 +125,15 @@ function tagIndexFor(bundle) {
   }
   return index;
 }
+var padIndexCache = /* @__PURE__ */ new WeakMap();
+function padIndexFor(bundle) {
+  let index = padIndexCache.get(bundle);
+  if (!index) {
+    index = buildPadIndex(bundle);
+    padIndexCache.set(bundle, index);
+  }
+  return index;
+}
 function tagsOf(host, id) {
   return host.tagIndex.get(id)?.slice();
 }
@@ -150,18 +199,20 @@ 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();
     const blockById = /* @__PURE__ */ new Map();
     for (const [sceneId, scene] of Object.entries(bundle.scenes)) {
-      this.sceneGameIdToId.set((0, import_model.effectiveGameId)(scene), sceneId);
+      this.sceneGameIdToId.set((0, import_model2.effectiveGameId)(scene), sceneId);
       const blockAddrs = /* @__PURE__ */ new Map();
       for (const block of scene.blocks) {
         blockIndex.set(block.id, { sceneId });
         blockById.set(block.id, block);
-        blockAddrs.set((0, import_model.effectiveGameId)(block), block.id);
-        (0, import_model.walkNodes)(block.children, (n) => nodeIndex.set(n.id, n));
+        blockAddrs.set((0, import_model2.effectiveGameId)(block), block.id);
+        (0, import_model2.walkNodes)(block.children, (n) => nodeIndex.set(n.id, n));
       }
       this.blockGameIdToId.set(sceneId, blockAddrs);
     }
@@ -210,6 +261,7 @@ var Engine = class _Engine {
       strings,
       defaultStrings,
       castDisplay,
+      qualifierDisplay,
       nodeIndex,
       blockIndex,
       blockById,
@@ -217,6 +269,7 @@ var Engine = class _Engine {
       blockGameIdToId: this.blockGameIdToId,
       // same instances the engine resolves with
       tagIndex: tagIndexFor(bundle),
+      padIndex: padIndexFor(bundle),
       registry,
       ownsRegistry,
       patterBag,
@@ -236,9 +289,9 @@ var Engine = class _Engine {
       replayPromptOnChoose: options.replayPromptOnChoose ?? false,
       captionsOn: options.closedCaptions ?? true,
       // captions shown by default (full text)
-      captionOpen: (bundle.closedCaptions ?? import_model.DEFAULT_CAPTION_DELIMITERS).open,
-      captionClose: (bundle.closedCaptions ?? import_model.DEFAULT_CAPTION_DELIMITERS).close,
-      captionCharacter: bundle.closedCaptions?.character || import_model.DEFAULT_CAPTION_CHARACTER,
+      captionOpen: (bundle.closedCaptions ?? import_model2.DEFAULT_CAPTION_DELIMITERS).open,
+      captionClose: (bundle.closedCaptions ?? import_model2.DEFAULT_CAPTION_DELIMITERS).close,
+      captionCharacter: bundle.closedCaptions?.character || import_model2.DEFAULT_CAPTION_CHARACTER,
       // absent/empty -> SFX
       refSplitCache: /* @__PURE__ */ new Map(),
       refSplitRevision: registry.revision
@@ -463,11 +516,11 @@ var Engine = class _Engine {
    *  The inverse of the resolve helpers - for a host that wants to display / log the address. */
   sceneAddress(sceneId) {
     const scene = this.host.bundle.scenes[sceneId];
-    return scene ? (0, import_model.effectiveGameId)(scene) : void 0;
+    return scene ? (0, import_model2.effectiveGameId)(scene) : void 0;
   }
   blockAddress(blockId) {
     const block = this.host.blockById.get(blockId);
-    return block ? (0, import_model.effectiveGameId)(block) : void 0;
+    return block ? (0, import_model2.effectiveGameId)(block) : void 0;
   }
   /**
    * Author tags (#215) accumulated for a beat by id: its own tags unioned with every ancestor's
@@ -550,13 +603,13 @@ var Engine = class _Engine {
   getOutline() {
     return Object.values(this.host.bundle.scenes).map((scene) => ({
       id: scene.id,
-      ...(0, import_model.effectiveGameId)(scene) ? { gameId: (0, import_model.effectiveGameId)(scene) } : {},
+      ...(0, import_model2.effectiveGameId)(scene) ? { gameId: (0, import_model2.effectiveGameId)(scene) } : {},
       name: scene.name,
       ...gameDataField(scene.gameData),
       ...this.tagsField(scene.id),
       blocks: scene.blocks.map((block) => ({
         id: block.id,
-        ...(0, import_model.effectiveGameId)(block) ? { gameId: (0, import_model.effectiveGameId)(block) } : {},
+        ...(0, import_model2.effectiveGameId)(block) ? { gameId: (0, import_model2.effectiveGameId)(block) } : {},
         name: block.name,
         ...gameDataField(block.gameData),
         ...this.tagsField(block.id),
@@ -573,7 +626,7 @@ var Engine = class _Engine {
     const out = [];
     for (const scene of Object.values(this.host.bundle.scenes)) {
       for (const block of scene.blocks) {
-        (0, import_model.walkNodes)(block.children, (n) => {
+        (0, import_model2.walkNodes)(block.children, (n) => {
           if (n.type !== "snippet") return;
           for (const beat of n.beats ?? []) {
             out.push({ sceneId: scene.id, blockId: block.id, snippetId: n.id, beat: this.beatInfo(beat) });
@@ -610,12 +663,20 @@ var Engine = class _Engine {
     if (beat.kind === "line") {
       if (beat.character !== void 0) {
         info.character = beat.character;
-        const name = this.host.defaultStrings[(0, import_model.castStringKey)(beat.character)] ?? this.host.castDisplay.get(beat.character);
+        const name = this.host.defaultStrings[(0, import_model2.castStringKey)(beat.character)] ?? this.host.castDisplay.get(beat.character);
         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_model2.qualifierStringKey)(beat.qualifier)] ?? this.host.qualifierDisplay.get(beat.qualifier);
+        if (name !== void 0) info.qualifierName = name;
+      }
     }
     if (beat.kind === "line" || beat.kind === "text") {
+      const pad = this.host.padIndex.get(beat.id);
+      info.padAfter = pad?.resolved ?? import_model2.DEFAULT_PAD_AFTER;
+      if (pad?.own !== void 0) info.ownPadAfter = pad.own;
       const source = this.host.defaultStrings[beat.id];
       if (source !== void 0) info.text = source;
     }
@@ -841,7 +902,7 @@ var Engine = class _Engine {
     const flows = {};
     for (const [id, flow] of this.flowsById) flows[id] = flow.snapshot();
     return {
-      version: import_model2.SAVE_VERSION,
+      version: import_model3.SAVE_VERSION,
       ...this.host.ownsRegistry ? { registry: this.host.registry.save() } : {},
       sharedVisits: Object.fromEntries(this.host.sharedVisits),
       sharedSelectors: serialiseSelectors(this.host.sharedSelectors),
@@ -858,7 +919,7 @@ var Engine = class _Engine {
   loadGame(save) {
     this.refuseInCheckpoint("loadGame");
     const version = save.version;
-    if (version !== 2 && version !== import_model2.SAVE_VERSION) throw new Error(`unsupported save version: ${String(version)}`);
+    if (version !== 2 && version !== import_model3.SAVE_VERSION) throw new Error(`unsupported save version: ${String(version)}`);
     const flows = save.flows;
     if (typeof flows !== "object" || flows === null || Array.isArray(flows)) throw new Error("malformed save: no flows");
     this.assertExternalScopes();
@@ -1409,7 +1470,8 @@ var Flow = class {
         const node = this.host.nodeIndex.get(o.id);
         if (!node) continue;
         byId.set(o.id, node);
-        options.push({ ...o });
+        const { prompt: saved, ...rest } = o;
+        options.push({ ...rest, ...saved ? { prompt: { ...saved, padAfter: saved.padAfter ?? this.promptPadOf(node) } } : {} });
       }
       if (options.length > 0) this.pendingChoice = { groupId: c.pendingChoice.groupId, options, byId };
     }
@@ -1418,7 +1480,7 @@ 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 } } : {} };
+      if (beat) this.pendingPrompt = { beat, ...c.pendingPrompt ? { shown: { ...c.pendingPrompt, padAfter: c.pendingPrompt.padAfter ?? this.padOf(beat.id) } } : {} };
       else this.pendingPromptOwnerId = null;
     }
   }
@@ -1788,7 +1850,7 @@ var Flow = class {
       case "gameEvent":
         return { type: "gameEvent", id: beat.id, gameData: beat.gameData, ...withTags };
       case "text":
-        return { type: "text", id: beat.id, text: this.interpolate(this.resolveString(beat.id)), gameData: beat.gameData, ...withTags };
+        return { type: "text", id: beat.id, text: this.interpolate(this.resolveString(beat.id)), padAfter: this.padOf(beat.id), gameData: beat.gameData, ...withTags };
       case "line": {
         const raw = this.resolveString(beat.id);
         const off = !this.host.captionsOn;
@@ -1802,6 +1864,10 @@ 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),
+          padAfter: this.padOf(beat.id),
+          // a silent line still fires, so it still carries its pause
           gameData: beat.gameData,
           ...withTags
         };
@@ -1840,7 +1906,17 @@ 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 };
+    const padAfter = this.padOf(beat.id);
+    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),
+      padAfter
+    } : { kind: "text", text, padAfter };
   }
   /** An option's AUTHORED prompt beat: an Option group's own `prompt`. The only prompt a replay speaks. */
   authoredPromptOf(node) {
@@ -1851,7 +1927,7 @@ var Flow = class {
   promptResult(beat, shown) {
     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 };
+    if (shown.kind === "text") return { type: "text", id: beat.id, text: shown.text, padAfter: this.padOf(beat.id), gameData: beat.gameData, ...withTags };
     return {
       type: "line",
       id: beat.id,
@@ -1859,6 +1935,9 @@ var Flow = class {
       character: shown.character,
       characterName: shown.characterName,
       direction: shown.direction,
+      qualifier: shown.qualifier,
+      qualifierName: shown.qualifierName,
+      padAfter: this.padOf(beat.id),
       gameData: beat.gameData,
       ...withTags
     };
@@ -1872,7 +1951,7 @@ var Flow = class {
   /** The first snippet with a line/text beat within a child list, depth-first in authored order. */
   firstTextSnippetIn(children) {
     let found;
-    (0, import_model.walkNodes)(children, (n) => {
+    (0, import_model2.walkNodes)(children, (n) => {
       if (!found && n.type === "snippet" && (n.beats ?? []).some((b) => b.kind === "line" || b.kind === "text")) {
         found = n;
       }
@@ -1892,9 +1971,29 @@ var Flow = class {
   resolveCharacterName(character) {
     if (character === void 0) return void 0;
     if (this.host.emitIds) return void 0;
-    const key = (0, import_model.castStringKey)(character);
+    const key = (0, import_model2.castStringKey)(character);
     return this.host.strings[key] ?? this.host.defaultStrings[key] ?? this.host.castDisplay.get(character);
   }
+  /** The resolved pause of the beat an option shows as its prompt (its authored prompt, else its first content
+   *  line), for a saved option that predates prompts carrying one. */
+  promptPadOf(node) {
+    const beat = this.promptBeatOf(node);
+    return beat ? this.padOf(beat.id) : import_model2.DEFAULT_PAD_AFTER;
+  }
+  /** A line or text beat's resolved pause (line padding): its own `padAfter`, else the nearest default above
+   *  it, else the project's, else the built-in one; clamped to zero on a snippet's last line. */
+  padOf(beatId) {
+    return this.host.padIndex.get(beatId)?.resolved ?? import_model2.DEFAULT_PAD_AFTER;
+  }
+  /** 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_model2.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);
@@ -1975,7 +2074,7 @@ var Flow = class {
   }
 };
 function collectCast(nodes, out) {
-  (0, import_model.walkNodes)(nodes, (n) => {
+  (0, import_model2.walkNodes)(nodes, (n) => {
     if (n.type === "group") {
       if (n.prompt?.kind === "line" && n.prompt.character) out.add(n.prompt.character);
       return;
@@ -1991,6 +2090,9 @@ 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;
+  if (typeof p.padAfter === "number") out.padAfter = p.padAfter;
   return out;
 }
 function serialiseSelectors(map) {
@@ -2081,8 +2183,11 @@ function truthy(v) {
   return v.length > 0;
 }
 
+// src/index.ts
+var import_model5 = require("@patterkit/model");
+
 // src/describe.ts
-var import_model3 = require("@patterkit/model");
+var import_model4 = require("@patterkit/model");
 var isShared = (d, scopeDefault) => d.shared ?? scopeDefault;
 function summariseProperty(d, scopeDefault) {
   return {
@@ -2135,11 +2240,11 @@ function describeBundle(bundle) {
   const sceneProps = [];
   for (const scene of Object.values(bundle.scenes)) {
     counts.scenes++;
-    const gameId = (0, import_model3.effectiveGameId)(scene);
+    const gameId = (0, import_model4.effectiveGameId)(scene);
     addresses.push({
       gameId,
       name: scene.name,
-      blocks: scene.blocks.map((b) => ({ gameId: (0, import_model3.effectiveGameId)(b), name: b.name }))
+      blocks: scene.blocks.map((b) => ({ gameId: (0, import_model4.effectiveGameId)(b), name: b.name }))
     });
     for (const block of scene.blocks) countBlock(block, counts);
     if (scene.sceneProps?.length) {
@@ -2204,6 +2309,7 @@ function effectiveGameData(fields, node) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Checkpoint,
+  DEFAULT_PAD_AFTER,
   Engine,
   Flow,
   buildTagIndex,