@patterkit/runtime 0.23.0 → 0.25.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { ScalarValue } from '@wildwinter/expr';
 import { ScopeRegistry, PropertyBag, ScopeDeclaration, LogMount, ScopeResolver, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
-import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, SaveGameV2, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
-export { Bundle, DEFAULT_PAD_AFTER, EngineSave, FlowCursor, FlowSnapshot, SaveEnvelope, SaveGame, SavedChoice, SavedChoiceOption, SavedChoicePrompt, SelectorSnapshot, StackFrame } from '@patterkit/model';
+import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, FlowState, EngineSave, SaveGame, SaveGameV2, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
+export { Bundle, DEFAULT_PAD_AFTER, EngineSave, FlowCursor, FlowSnapshot, FlowState, FlowValues, SaveEnvelope, SaveGame, SavedChoice, SavedChoiceOption, SavedChoicePrompt, SelectorSnapshot, StackFrame } from '@patterkit/model';
 
 /** A beat's own `padAfter` (when it sets one) and its resolved one (always). */
 interface BeatPad {
@@ -22,6 +22,7 @@ type StepResult = {
     direction?: string;
     qualifier?: string;
     qualifierName?: string;
+    speakerLabel?: string;
     padAfter: number;
     gameData?: GameData;
     tags?: string[];
@@ -58,6 +59,8 @@ interface BeatInfo {
     qualifier?: string;
     /** The qualifier's shown name (source locale), e.g. `V.O.`. */
     qualifierName?: string;
+    /** The speaker's label (source locale): `You (V.O.)`, a pair's own label, or with no qualifier the name. */
+    speakerLabel?: string;
     /** The pause after this beat, in seconds, resolved from its own value and the defaults above it (line and
      *  text only; see line padding). What a delivered step carries. */
     padAfter?: number;
@@ -133,6 +136,8 @@ interface ChoicePrompt {
     /** The speaker qualifier's `gameId` (`vo`), and its resolved shown name (locale-aware). */
     qualifier?: string;
     qualifierName?: string;
+    /** The name to show for the speaker (locale-aware): see {@link speakerLabelOf}. */
+    speakerLabel?: string;
     /** The prompt's resolved pause, in seconds: when it is spoken (by `replayPromptOnChoose`, or by a game that
      *  voices it), the wait before the reply, negative to cut in on the question (line padding). */
     padAfter: number;
@@ -379,6 +384,11 @@ interface FlowHost {
     castDisplay: Map<string, string>;
     /** Speaker qualifier gameId -> authored name (the unlocalised fallback when no loc string exists). */
     qualifierDisplay: Map<string, string>;
+    /** `<name>\0<gameId>` -> a character's own label with that qualifier, for the overridden pairs only (the
+     *  unlocalised fallback). A pair not here follows the pattern, whatever a loc file holds for it. */
+    speakerLabels: Map<string, string>;
+    /** The project's speaker pattern (the unlocalised fallback for the `speaker:pattern` string). */
+    speakerPattern: string;
     nodeIndex: Map<string, SelectableNode>;
     blockIndex: Map<string, {
         sceneId: string;
@@ -686,6 +696,20 @@ declare class Engine {
     /** Let go of what a closed checkpoint recorded, so a handle the game keeps holds nothing. */
     private static forget;
     private refuseInCheckpoint;
+    /**
+     * Take flow `id` out of the engine as plain data, to be put back later with {@link restoreFlow}: its snapshot as
+     * `saveGame` writes it, and its own property values without its id (so it can come back under another). Shared
+     * state is never in it. Doesn't close the flow; close it with {@link closeFlow} AFTER capturing, since closing
+     * drops its values. Only reads, so it is allowed while a checkpoint is open.
+     */
+    captureFlow(id: string): FlowState;
+    /**
+     * Open flow `id` from a {@link captureFlow} state, the per-flow half of `loadGame`: its values go into the
+     * registry as a load's do, and the flow is restored as a load restores each flow. `id` needn't be the id it was
+     * captured from. Against an edited bundle it re-finds its place by id, as a load does. Refused if a flow of
+     * that id is open, or while a checkpoint is.
+     */
+    restoreFlow(id: string, state: FlowState): Flow;
     /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
      *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
     closeFlow(id: string): void;

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { ScalarValue } from '@wildwinter/expr';
 import { ScopeRegistry, PropertyBag, ScopeDeclaration, LogMount, ScopeResolver, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
-import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, SaveGameV2, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
-export { Bundle, DEFAULT_PAD_AFTER, EngineSave, FlowCursor, FlowSnapshot, SaveEnvelope, SaveGame, SavedChoice, SavedChoiceOption, SavedChoicePrompt, SelectorSnapshot, StackFrame } from '@patterkit/model';
+import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, FlowState, EngineSave, SaveGame, SaveGameV2, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
+export { Bundle, DEFAULT_PAD_AFTER, EngineSave, FlowCursor, FlowSnapshot, FlowState, FlowValues, SaveEnvelope, SaveGame, SavedChoice, SavedChoiceOption, SavedChoicePrompt, SelectorSnapshot, StackFrame } from '@patterkit/model';
 
 /** A beat's own `padAfter` (when it sets one) and its resolved one (always). */
 interface BeatPad {
@@ -22,6 +22,7 @@ type StepResult = {
     direction?: string;
     qualifier?: string;
     qualifierName?: string;
+    speakerLabel?: string;
     padAfter: number;
     gameData?: GameData;
     tags?: string[];
@@ -58,6 +59,8 @@ interface BeatInfo {
     qualifier?: string;
     /** The qualifier's shown name (source locale), e.g. `V.O.`. */
     qualifierName?: string;
+    /** The speaker's label (source locale): `You (V.O.)`, a pair's own label, or with no qualifier the name. */
+    speakerLabel?: string;
     /** The pause after this beat, in seconds, resolved from its own value and the defaults above it (line and
      *  text only; see line padding). What a delivered step carries. */
     padAfter?: number;
@@ -133,6 +136,8 @@ interface ChoicePrompt {
     /** The speaker qualifier's `gameId` (`vo`), and its resolved shown name (locale-aware). */
     qualifier?: string;
     qualifierName?: string;
+    /** The name to show for the speaker (locale-aware): see {@link speakerLabelOf}. */
+    speakerLabel?: string;
     /** The prompt's resolved pause, in seconds: when it is spoken (by `replayPromptOnChoose`, or by a game that
      *  voices it), the wait before the reply, negative to cut in on the question (line padding). */
     padAfter: number;
@@ -379,6 +384,11 @@ interface FlowHost {
     castDisplay: Map<string, string>;
     /** Speaker qualifier gameId -> authored name (the unlocalised fallback when no loc string exists). */
     qualifierDisplay: Map<string, string>;
+    /** `<name>\0<gameId>` -> a character's own label with that qualifier, for the overridden pairs only (the
+     *  unlocalised fallback). A pair not here follows the pattern, whatever a loc file holds for it. */
+    speakerLabels: Map<string, string>;
+    /** The project's speaker pattern (the unlocalised fallback for the `speaker:pattern` string). */
+    speakerPattern: string;
     nodeIndex: Map<string, SelectableNode>;
     blockIndex: Map<string, {
         sceneId: string;
@@ -686,6 +696,20 @@ declare class Engine {
     /** Let go of what a closed checkpoint recorded, so a handle the game keeps holds nothing. */
     private static forget;
     private refuseInCheckpoint;
+    /**
+     * Take flow `id` out of the engine as plain data, to be put back later with {@link restoreFlow}: its snapshot as
+     * `saveGame` writes it, and its own property values without its id (so it can come back under another). Shared
+     * state is never in it. Doesn't close the flow; close it with {@link closeFlow} AFTER capturing, since closing
+     * drops its values. Only reads, so it is allowed while a checkpoint is open.
+     */
+    captureFlow(id: string): FlowState;
+    /**
+     * Open flow `id` from a {@link captureFlow} state, the per-flow half of `loadGame`: its values go into the
+     * registry as a load's do, and the flow is restored as a load restores each flow. `id` needn't be the id it was
+     * captured from. Against an edited bundle it re-finds its place by id, as a load does. Refused if a flow of
+     * that id is open, or while a checkpoint is.
+     */
+    restoreFlow(id: string, state: FlowState): Flow;
     /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
      *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
     closeFlow(id: string): void;

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, qualifierStringKey, DEFAULT_PAD_AFTER as DEFAULT_PAD_AFTER2, DEFAULT_CAPTION_DELIMITERS, DEFAULT_CAPTION_CHARACTER } from "@patterkit/model";
+import { walkNodes, effectiveGameId, castStringKey, qualifierStringKey, speakerLabelKey, formatSpeakerLabel, SPEAKER_PATTERN_KEY, DEFAULT_SPEAKER_PATTERN, DEFAULT_PAD_AFTER as DEFAULT_PAD_AFTER2, DEFAULT_CAPTION_DELIMITERS, DEFAULT_CAPTION_CHARACTER } from "@patterkit/model";
 
 // src/tags.ts
 function dedupe(tags) {
@@ -105,6 +105,7 @@ function tagsOf(host, id) {
 }
 var OWNER = "Patter";
 var esc = (id) => id.replace(/%/g, "%25").replace(/\//g, "%2F");
+var unesc = (key) => key.replace(/%2F/g, "/").replace(/%25/g, "%");
 var OWNS_REGISTRY = /* @__PURE__ */ Symbol("ownsRegistry");
 var keys = {
   /** A scene's SHARED `@scene` props (one bag per scene, every flow's). */
@@ -167,6 +168,9 @@ var Engine = class _Engine {
     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);
+    const speakerLabels = /* @__PURE__ */ new Map();
+    for (const c of bundle.cast ?? []) for (const [q, label] of Object.entries(c.qualifierLabels ?? {})) if (typeof label === "string") speakerLabels.set(`${c.name}\0${q}`, label);
+    const speakerPattern = bundle.speakerPattern ?? DEFAULT_SPEAKER_PATTERN;
     this.defaultSeed = (options.seed ?? 2654435769) >>> 0;
     const nodeIndex = /* @__PURE__ */ new Map();
     const blockIndex = /* @__PURE__ */ new Map();
@@ -228,6 +232,8 @@ var Engine = class _Engine {
       defaultStrings,
       castDisplay,
       qualifierDisplay,
+      speakerLabels,
+      speakerPattern,
       nodeIndex,
       blockIndex,
       blockById,
@@ -638,6 +644,8 @@ var Engine = class _Engine {
         const name = this.host.defaultStrings[qualifierStringKey(beat.qualifier)] ?? this.host.qualifierDisplay.get(beat.qualifier);
         if (name !== void 0) info.qualifierName = name;
       }
+      const label = speakerLabelOf(this.host, beat.character, beat.qualifier, true);
+      if (label !== void 0) info.speakerLabel = label;
     }
     if (beat.kind === "line" || beat.kind === "text") {
       const pad = this.host.padIndex.get(beat.id);
@@ -733,6 +741,45 @@ var Engine = class _Engine {
   refuseInCheckpoint(what) {
     if (this.host.journal) throw new Error(`${what} can't be undone, so it isn't allowed while a checkpoint is open`);
   }
+  /**
+   * Take flow `id` out of the engine as plain data, to be put back later with {@link restoreFlow}: its snapshot as
+   * `saveGame` writes it, and its own property values without its id (so it can come back under another). Shared
+   * state is never in it. Doesn't close the flow; close it with {@link closeFlow} AFTER capturing, since closing
+   * drops its values. Only reads, so it is allowed while a checkpoint is open.
+   */
+  captureFlow(id) {
+    const flow = this.flowsById.get(id);
+    if (!flow) throw new Error(`no open flow '${id}' to capture`);
+    return { version: SAVE_VERSION, ...flow.snapshot(), ...flowValuesFrom(id, this.host.registry.save()) };
+  }
+  /**
+   * Open flow `id` from a {@link captureFlow} state, the per-flow half of `loadGame`: its values go into the
+   * registry as a load's do, and the flow is restored as a load restores each flow. `id` needn't be the id it was
+   * captured from. Against an edited bundle it re-finds its place by id, as a load does. Refused if a flow of
+   * that id is open, or while a checkpoint is.
+   */
+  restoreFlow(id, state) {
+    this.refuseInCheckpoint("restoreFlow");
+    const version = state.version;
+    if (version !== 2 && version !== SAVE_VERSION) throw new Error(`unsupported flow state version: ${String(version)}`);
+    const cursor = state.cursor;
+    if (typeof cursor !== "object" || cursor === null) throw new Error("malformed flow state: no cursor");
+    if (this.flowsById.has(id)) throw new Error(`a flow '${id}' is already open; close it before restoring another under that id`);
+    this.assertExternalScopes();
+    const parked = keys.flow(id);
+    this.host.registry.discardParked(parked);
+    this.host.registry.load(flowSections(id, state), { keepParked: true });
+    const flow = new Flow(id, this.host, this.defaultSeed);
+    try {
+      flow.restore(state);
+    } catch (e) {
+      flow.close();
+      this.host.registry.discardParked(parked);
+      throw e;
+    }
+    this.flowsById.set(id, flow);
+    return flow;
+  }
   /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
    *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
   closeFlow(id) {
@@ -1437,7 +1484,8 @@ var Flow = class {
         if (!node) continue;
         byId.set(o.id, node);
         const { prompt: saved, ...rest } = o;
-        options.push({ ...rest, ...saved ? { prompt: { ...saved, padAfter: saved.padAfter ?? this.promptPadOf(node) } } : {} });
+        const label = saved?.kind === "line" && saved.speakerLabel === void 0 ? speakerLabelOf(this.host, saved.character, saved.qualifier) : void 0;
+        options.push({ ...rest, ...saved ? { prompt: { ...saved, padAfter: saved.padAfter ?? this.promptPadOf(node), ...label !== void 0 ? { speakerLabel: label } : {} } } : {} });
       }
       if (options.length > 0) this.pendingChoice = { groupId: c.pendingChoice.groupId, options, byId };
     }
@@ -1446,7 +1494,9 @@ 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, padAfter: c.pendingPrompt.padAfter ?? this.padOf(beat.id) } } : {} };
+      const saved = c.pendingPrompt;
+      const label = saved?.kind === "line" && saved.speakerLabel === void 0 ? speakerLabelOf(this.host, saved.character, saved.qualifier) : void 0;
+      if (beat) this.pendingPrompt = { beat, ...saved ? { shown: { ...saved, padAfter: saved.padAfter ?? this.padOf(beat.id), ...label !== void 0 ? { speakerLabel: label } : {} } } : {} };
       else this.pendingPromptOwnerId = null;
     }
   }
@@ -1832,6 +1882,7 @@ var Flow = class {
           direction: silent ? void 0 : beat.direction,
           qualifier: silent ? void 0 : beat.qualifier,
           qualifierName: silent ? void 0 : this.resolveQualifierName(beat.qualifier),
+          speakerLabel: silent ? void 0 : speakerLabelOf(this.host, beat.character, beat.qualifier),
           padAfter: this.padOf(beat.id),
           // a silent line still fires, so it still carries its pause
           gameData: beat.gameData,
@@ -1881,6 +1932,7 @@ var Flow = class {
       direction: beat.direction,
       qualifier: beat.qualifier,
       qualifierName: this.resolveQualifierName(beat.qualifier),
+      speakerLabel: speakerLabelOf(this.host, beat.character, beat.qualifier),
       padAfter
     } : { kind: "text", text, padAfter };
   }
@@ -1903,6 +1955,7 @@ var Flow = class {
       direction: shown.direction,
       qualifier: shown.qualifier,
       qualifierName: shown.qualifierName,
+      speakerLabel: shown.speakerLabel,
       padAfter: this.padOf(beat.id),
       gameData: beat.gameData,
       ...withTags
@@ -2048,6 +2101,16 @@ function collectCast(nodes, out) {
     for (const beat of n.beats ?? []) if (beat.kind === "line" && beat.character) out.add(beat.character);
   });
 }
+function speakerLabelOf(host, character, qualifier, source = false) {
+  if (!character || host.emitIds) return void 0;
+  const lookup = (key) => (source ? void 0 : host.strings[key]) ?? host.defaultStrings[key];
+  const name = lookup(castStringKey(character)) ?? host.castDisplay.get(character) ?? character;
+  if (qualifier === void 0) return name;
+  const own = host.speakerLabels.get(`${character}\0${qualifier}`);
+  if (own !== void 0) return lookup(speakerLabelKey(character, qualifier)) ?? own;
+  const shown = lookup(qualifierStringKey(qualifier)) ?? host.qualifierDisplay.get(qualifier) ?? qualifier;
+  return formatSpeakerLabel(lookup(SPEAKER_PATTERN_KEY) ?? host.speakerPattern, name, shown);
+}
 function gameDataField(gameData) {
   return gameData && Object.keys(gameData).length ? { gameData } : {};
 }
@@ -2058,6 +2121,7 @@ function savedPrompt(p) {
   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 (p.speakerLabel !== void 0) out.speakerLabel = p.speakerLabel;
   if (typeof p.padAfter === "number") out.padAfter = p.padAfter;
   return out;
 }
@@ -2136,9 +2200,23 @@ function sectionsFromV2(save) {
   const out = {};
   if (save.shared?.patter) out["patter"] = save.shared.patter;
   for (const [s, v] of Object.entries(save.stageBags ?? {})) out[keys.stage(s)] = v;
-  for (const [id, f] of Object.entries(save.flows ?? {})) {
-    if (f.scopes?.patter) out[keys.flowGlobals(id)] = f.scopes.patter;
-    for (const [s, v] of Object.entries(f.sceneBags ?? {})) out[keys.flowScene(id, s)] = v;
+  for (const [id, f] of Object.entries(save.flows ?? {})) Object.assign(out, flowSections(id, f));
+  return out;
+}
+function flowSections(id, f) {
+  const out = {};
+  if (f.scopes?.patter) out[keys.flowGlobals(id)] = f.scopes.patter;
+  for (const [s, v] of Object.entries(f.sceneBags ?? {})) out[keys.flowScene(id, s)] = v;
+  return out;
+}
+function flowValuesFrom(id, saved) {
+  const out = { scopes: {}, sceneBags: {} };
+  const prefix = keys.flow(id);
+  for (const [key, values] of Object.entries(saved)) {
+    if (!key.startsWith(prefix)) continue;
+    const rest = key.slice(prefix.length);
+    if (rest === "patter") out.scopes.patter = values;
+    else if (rest.startsWith("scene/")) out.sceneBags[unesc(rest.slice("scene/".length))] = values;
   }
   return out;
 }