@patterkit/model 0.13.1 → 0.15.0

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   DEFAULT_PAD_AFTER: () => DEFAULT_PAD_AFTER,
   DEFAULT_QUALIFIERS: () => DEFAULT_QUALIFIERS,
   DEFAULT_RECORDING_STATUSES: () => DEFAULT_RECORDING_STATUSES,
+  DEFAULT_SPEAKER_PATTERN: () => DEFAULT_SPEAKER_PATTERN,
   DEFAULT_WRITING_STATUSES: () => DEFAULT_WRITING_STATUSES,
   FLOW_SCHEMA: () => FLOW_SCHEMA,
   HANDOFF_SCHEMA: () => HANDOFF_SCHEMA,
@@ -41,10 +42,12 @@ __export(index_exports, {
   RESERVED_PROPERTY_NAMES: () => import_expr.RESERVED_PROPERTY_NAMES,
   SAVE_SCHEMA: () => SAVE_SCHEMA,
   SAVE_VERSION: () => SAVE_VERSION,
+  SPEAKER_PATTERN_KEY: () => SPEAKER_PATTERN_KEY,
   STRINGS_SCHEMA: () => STRINGS_SCHEMA,
   castStringKey: () => castStringKey,
   deriveRecordingFolders: () => deriveRecordingFolders,
   effectiveGameId: () => effectiveGameId,
+  formatSpeakerLabel: () => formatSpeakerLabel,
   gameIdify: () => gameIdify,
   isCaseOnlyPropertyName: () => import_expr.isCaseOnlyPropertyName,
   isContentlessBeat: () => isContentlessBeat,
@@ -54,7 +57,9 @@ __export(index_exports, {
   projectQualifiers: () => projectQualifiers,
   propertyNameify: () => import_expr.propertyNameify,
   qualifierStringKey: () => qualifierStringKey,
+  speakerLabelKey: () => speakerLabelKey,
   usedQualifiers: () => usedQualifiers,
+  usedSpeakerPairs: () => usedSpeakerPairs,
   walkNodes: () => walkNodes
 });
 module.exports = __toCommonJS(index_exports);
@@ -107,6 +112,29 @@ function usedQualifiers(project, scenes) {
   }
   return projectQualifiers(project).filter((q) => used.has(q.gameId));
 }
+function usedSpeakerPairs(scenes) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const add = (beat) => {
+    if (!beat.character || !beat.qualifier) return;
+    const key = `${beat.character}\0${beat.qualifier}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ character: beat.character, qualifier: beat.qualifier });
+  };
+  for (const scene of scenes) {
+    for (const block of scene.blocks) {
+      walkNodes(block.children, (node) => {
+        if (node.type === "group") {
+          if (node.prompt?.kind === "line") add(node.prompt);
+          return;
+        }
+        for (const beat of node.beats ?? []) if (beat.kind === "line") add(beat);
+      });
+    }
+  }
+  return out;
+}
 var DEFAULT_PAD_AFTER = 0.6;
 var PAD_AFTER_MIN = -10;
 var PAD_AFTER_MAX = 60;
@@ -158,6 +186,14 @@ function castStringKey(name) {
 function qualifierStringKey(gameId) {
   return `qualifier:${gameId}`;
 }
+function speakerLabelKey(name, gameId) {
+  return `speaker:${name}:${gameId}`;
+}
+var SPEAKER_PATTERN_KEY = "speaker:pattern";
+var DEFAULT_SPEAKER_PATTERN = "{name} ({qualifier})";
+function formatSpeakerLabel(pattern, name, qualifier) {
+  return pattern.split("{name}").map((part) => part.split("{qualifier}").join(qualifier)).join(name);
+}
 var HANDOFF_SCHEMA = "patter/handoff@0";
 var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
@@ -182,6 +218,7 @@ var AUTHORING_SCHEMA = "patter/authoring@0";
   DEFAULT_PAD_AFTER,
   DEFAULT_QUALIFIERS,
   DEFAULT_RECORDING_STATUSES,
+  DEFAULT_SPEAKER_PATTERN,
   DEFAULT_WRITING_STATUSES,
   FLOW_SCHEMA,
   HANDOFF_SCHEMA,
@@ -194,10 +231,12 @@ var AUTHORING_SCHEMA = "patter/authoring@0";
   RESERVED_PROPERTY_NAMES,
   SAVE_SCHEMA,
   SAVE_VERSION,
+  SPEAKER_PATTERN_KEY,
   STRINGS_SCHEMA,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
+  formatSpeakerLabel,
   gameIdify,
   isCaseOnlyPropertyName,
   isContentlessBeat,
@@ -207,6 +246,8 @@ var AUTHORING_SCHEMA = "patter/authoring@0";
   projectQualifiers,
   propertyNameify,
   qualifierStringKey,
+  speakerLabelKey,
   usedQualifiers,
+  usedSpeakerPairs,
   walkNodes
 });

package/dist/index.d.cts

@@ -352,6 +352,10 @@ interface CastMember {
     /** The voice actor cast for this character, if known - surfaced in the VO script export (spec §16).
      *  Authoring-only (not shipped in the runtime bundle). */
     actor?: string;
+    /** This character's own label with a qualifier, by the qualifier's `gameId`, in the source language
+     *  (`{ vo: "Your thoughts" }`), where the project's speaker pattern shouldn't apply. Localised as the
+     *  `speaker:<name>:<gameId>` string (`speakerLabelKey`). Absent for every pair that follows the pattern. */
+    qualifierLabels?: Record<string, string>;
     gameData?: GameData;
 }
 /** A speaker qualifier (a screenplay's character extension): `V.O.`, `O.S.`, `RADIO`, or the project's own.
@@ -372,6 +376,12 @@ declare const DEFAULT_QUALIFIERS: SpeakerQualifier[];
 declare function projectQualifiers(project: Pick<ProjectFile, "qualifiers">): SpeakerQualifier[];
 /** The project's qualifiers that some line (or line prompt) in these scenes uses, in the project's order. */
 declare function usedQualifiers(project: Pick<ProjectFile, "qualifiers">, scenes: Scene[]): SpeakerQualifier[];
+/** Every character and qualifier pair the lines use (a line's speaker with its qualifier, option prompts
+ *  included), once each, in the order first met. A pair's label is shown only for these. */
+declare function usedSpeakerPairs(scenes: Scene[]): {
+    character: string;
+    qualifier: string;
+}[];
 /** The built-in `padAfter`, in seconds, for a project that sets no default of its own: the same on every runtime
  *  and in Patterpad's Play window (design/proposals/line-padding.md section 4). */
 declare const DEFAULT_PAD_AFTER = 0.6;
@@ -392,19 +402,27 @@ type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender">;
 /** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
  *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`. */
 type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent";
-/** The value type of a gameData field - the property-type vocabulary plus a multiline-text variant.
- *  Drives the inspector's editor widget (text / textarea / number / toggle / enum dropdown). */
-type GameDataFieldType = "text" | "multiline" | "number" | "boolean" | "enum";
+/** The value type of a gameData field: the family's one field-type list, shared with Storylets' card and
+ *  outcome fields (patterkit design/family-parity-2026-10.md item 9, patter-qualities.md section 1). Drives
+ *  the inspector's editor widget (text / textarea / number / toggle / enum dropdown / flags checklist /
+ *  quality ladder). A `quality` value is a stage of the field's own ladder (`stages`), compared by position by
+ *  a host, never by the engine. */
+type GameDataFieldType = "text" | "multiline" | "number" | "boolean" | "enum" | "flags" | "quality";
 /** One author-defined custom field on a node type (host-integration metadata, NOT expression state). */
 interface GameDataField {
     /** Field key - also the key a node stores its value under in `gameData` (values are name-keyed). */
     name: string;
     type: GameDataFieldType;
     /** The value used when a node sets nothing. Storage is SPARSE - nodes hold only their overrides, and
-     *  a reader falls back to this default (so changing it here propagates to every node that didn't set it). */
+     *  a reader falls back to this default (so changing it here propagates to every node that didn't set it).
+     *  Optional in source: left out, the type's default holds (by the kernel's `defaultFor`), and the compiler
+     *  writes it into the bundle, so a bundle's field always has one. An enum's may be `""`, none chosen. */
     default?: ScalarValue;
-    /** Allowed values when `type` is "enum". */
+    /** Allowed values when `type` is "enum", or the flags a "flags" value may hold. */
     values?: string[];
+    /** A "quality" field's ordered ladder, by the family's one rule (at least two stages, none empty, none
+     *  twice; `@wildwinter/expr`'s `qualityDeclarationProblems`). */
+    stages?: string[];
     /** Free-text description of what the field is for - shown as a rollover hint in the inspector. */
     purpose?: string;
 }
@@ -623,6 +641,9 @@ interface ProjectFile {
     /** The speaker qualifiers a line can pick from, in display order; default `DEFAULT_QUALIFIERS`. An empty
      *  list means the project uses none. */
     qualifiers?: SpeakerQualifier[];
+    /** How a character's label reads with a qualifier, in the source language: `{name}` and `{qualifier}` filled
+     *  in. Absent = `DEFAULT_SPEAKER_PATTERN`. Localised as the `speaker:pattern` string. */
+    speakerPattern?: string;
     /** The project's default `padAfter` for every line and text beat that sets none and has no default above it.
      *  Absent = `DEFAULT_PAD_AFTER`. */
     padAfterDefault?: number;
@@ -676,6 +697,19 @@ declare function castStringKey(name: string): string;
 /** The project-level loc-string key for a speaker qualifier's shown name, e.g. `qualifier:vo`. Resolved as a
  *  cast display name is: the active locale, then the default locale, then the authored `name`. */
 declare function qualifierStringKey(gameId: string): string;
+/** The project-level loc-string key for one character's own label with one qualifier, e.g. `speaker:PLAYER:vo`:
+ *  only for a pair someone has overridden (`CastMember.qualifierLabels`). Every other pair's label is built from
+ *  the speaker pattern. */
+declare function speakerLabelKey(name: string, gameId: string): string;
+/** The project-level loc-string key for the speaker pattern, the label a character shows with a qualifier. */
+declare const SPEAKER_PATTERN_KEY = "speaker:pattern";
+/** The speaker pattern a project starts with: `You (V.O.)`. `{name}` and `{qualifier}` are plain placeholders,
+ *  never run through line interpolation. */
+declare const DEFAULT_SPEAKER_PATTERN = "{name} ({qualifier})";
+/** A qualified speaker's label: the pattern with its placeholders filled. Each placeholder is replaced
+ *  wherever it appears; nothing else in the pattern is read. The one composition rule, on every runtime and
+ *  in Patterpad. */
+declare function formatSpeakerLabel(pattern: string, name: string, qualifier: string): string;
 /** Typed documentation annotation line (spec §18). */
 interface DocLine {
     /** The documentation CLASS (a `DocumentationClass.name`) - routes export
@@ -991,6 +1025,9 @@ interface Bundle {
     /** The speaker qualifiers the content uses, in the project's order. Absent when no line has one, so a
      *  bundle without qualifiers is exactly as before. */
     qualifiers?: BundleQualifier[];
+    /** The project's speaker pattern, the unlocalised fallback for a qualified speaker's label. Absent when the
+     *  project keeps `DEFAULT_SPEAKER_PATTERN` or uses no qualifiers. */
+    speakerPattern?: string;
     /** The project's own `padAfterDefault`, when it sets one; absent = `DEFAULT_PAD_AFTER`. */
     padAfterDefault?: number;
     properties?: PropertyDecl[];
@@ -1076,6 +1113,8 @@ interface SavedChoicePrompt {
     direction?: string;
     qualifier?: string;
     qualifierName?: string;
+    /** The speaker's label as the choice showed it. Absent in a save written before it existed. */
+    speakerLabel?: string;
     /** The prompt's resolved pause (line padding). Absent in a save written before it existed. */
     padAfter?: number;
 }
@@ -1192,4 +1231,4 @@ declare const PROJECT_SCHEMA = "patter/project@0";
 declare const STRINGS_SCHEMA = "patter/strings@0";
 declare const AUTHORING_SCHEMA = "patter/authoring@0";
 
-export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleQualifier, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type FlowState, type FlowValues, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, HANDOFF_SCHEMA, type HandoffFile, type HandoffImport, type HandoffLine, type HandoffRow, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV2, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, usedQualifiers, walkNodes };
+export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleQualifier, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_SPEAKER_PATTERN, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type FlowState, type FlowValues, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, HANDOFF_SCHEMA, type HandoffFile, type HandoffImport, type HandoffLine, type HandoffRow, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, SPEAKER_PATTERN_KEY, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV2, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, formatSpeakerLabel, gameIdify, isContentlessBeat, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, speakerLabelKey, usedQualifiers, usedSpeakerPairs, walkNodes };

package/dist/index.d.ts

@@ -352,6 +352,10 @@ interface CastMember {
     /** The voice actor cast for this character, if known - surfaced in the VO script export (spec §16).
      *  Authoring-only (not shipped in the runtime bundle). */
     actor?: string;
+    /** This character's own label with a qualifier, by the qualifier's `gameId`, in the source language
+     *  (`{ vo: "Your thoughts" }`), where the project's speaker pattern shouldn't apply. Localised as the
+     *  `speaker:<name>:<gameId>` string (`speakerLabelKey`). Absent for every pair that follows the pattern. */
+    qualifierLabels?: Record<string, string>;
     gameData?: GameData;
 }
 /** A speaker qualifier (a screenplay's character extension): `V.O.`, `O.S.`, `RADIO`, or the project's own.
@@ -372,6 +376,12 @@ declare const DEFAULT_QUALIFIERS: SpeakerQualifier[];
 declare function projectQualifiers(project: Pick<ProjectFile, "qualifiers">): SpeakerQualifier[];
 /** The project's qualifiers that some line (or line prompt) in these scenes uses, in the project's order. */
 declare function usedQualifiers(project: Pick<ProjectFile, "qualifiers">, scenes: Scene[]): SpeakerQualifier[];
+/** Every character and qualifier pair the lines use (a line's speaker with its qualifier, option prompts
+ *  included), once each, in the order first met. A pair's label is shown only for these. */
+declare function usedSpeakerPairs(scenes: Scene[]): {
+    character: string;
+    qualifier: string;
+}[];
 /** The built-in `padAfter`, in seconds, for a project that sets no default of its own: the same on every runtime
  *  and in Patterpad's Play window (design/proposals/line-padding.md section 4). */
 declare const DEFAULT_PAD_AFTER = 0.6;
@@ -392,19 +402,27 @@ type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender">;
 /** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
  *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`. */
 type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent";
-/** The value type of a gameData field - the property-type vocabulary plus a multiline-text variant.
- *  Drives the inspector's editor widget (text / textarea / number / toggle / enum dropdown). */
-type GameDataFieldType = "text" | "multiline" | "number" | "boolean" | "enum";
+/** The value type of a gameData field: the family's one field-type list, shared with Storylets' card and
+ *  outcome fields (patterkit design/family-parity-2026-10.md item 9, patter-qualities.md section 1). Drives
+ *  the inspector's editor widget (text / textarea / number / toggle / enum dropdown / flags checklist /
+ *  quality ladder). A `quality` value is a stage of the field's own ladder (`stages`), compared by position by
+ *  a host, never by the engine. */
+type GameDataFieldType = "text" | "multiline" | "number" | "boolean" | "enum" | "flags" | "quality";
 /** One author-defined custom field on a node type (host-integration metadata, NOT expression state). */
 interface GameDataField {
     /** Field key - also the key a node stores its value under in `gameData` (values are name-keyed). */
     name: string;
     type: GameDataFieldType;
     /** The value used when a node sets nothing. Storage is SPARSE - nodes hold only their overrides, and
-     *  a reader falls back to this default (so changing it here propagates to every node that didn't set it). */
+     *  a reader falls back to this default (so changing it here propagates to every node that didn't set it).
+     *  Optional in source: left out, the type's default holds (by the kernel's `defaultFor`), and the compiler
+     *  writes it into the bundle, so a bundle's field always has one. An enum's may be `""`, none chosen. */
     default?: ScalarValue;
-    /** Allowed values when `type` is "enum". */
+    /** Allowed values when `type` is "enum", or the flags a "flags" value may hold. */
     values?: string[];
+    /** A "quality" field's ordered ladder, by the family's one rule (at least two stages, none empty, none
+     *  twice; `@wildwinter/expr`'s `qualityDeclarationProblems`). */
+    stages?: string[];
     /** Free-text description of what the field is for - shown as a rollover hint in the inspector. */
     purpose?: string;
 }
@@ -623,6 +641,9 @@ interface ProjectFile {
     /** The speaker qualifiers a line can pick from, in display order; default `DEFAULT_QUALIFIERS`. An empty
      *  list means the project uses none. */
     qualifiers?: SpeakerQualifier[];
+    /** How a character's label reads with a qualifier, in the source language: `{name}` and `{qualifier}` filled
+     *  in. Absent = `DEFAULT_SPEAKER_PATTERN`. Localised as the `speaker:pattern` string. */
+    speakerPattern?: string;
     /** The project's default `padAfter` for every line and text beat that sets none and has no default above it.
      *  Absent = `DEFAULT_PAD_AFTER`. */
     padAfterDefault?: number;
@@ -676,6 +697,19 @@ declare function castStringKey(name: string): string;
 /** The project-level loc-string key for a speaker qualifier's shown name, e.g. `qualifier:vo`. Resolved as a
  *  cast display name is: the active locale, then the default locale, then the authored `name`. */
 declare function qualifierStringKey(gameId: string): string;
+/** The project-level loc-string key for one character's own label with one qualifier, e.g. `speaker:PLAYER:vo`:
+ *  only for a pair someone has overridden (`CastMember.qualifierLabels`). Every other pair's label is built from
+ *  the speaker pattern. */
+declare function speakerLabelKey(name: string, gameId: string): string;
+/** The project-level loc-string key for the speaker pattern, the label a character shows with a qualifier. */
+declare const SPEAKER_PATTERN_KEY = "speaker:pattern";
+/** The speaker pattern a project starts with: `You (V.O.)`. `{name}` and `{qualifier}` are plain placeholders,
+ *  never run through line interpolation. */
+declare const DEFAULT_SPEAKER_PATTERN = "{name} ({qualifier})";
+/** A qualified speaker's label: the pattern with its placeholders filled. Each placeholder is replaced
+ *  wherever it appears; nothing else in the pattern is read. The one composition rule, on every runtime and
+ *  in Patterpad. */
+declare function formatSpeakerLabel(pattern: string, name: string, qualifier: string): string;
 /** Typed documentation annotation line (spec §18). */
 interface DocLine {
     /** The documentation CLASS (a `DocumentationClass.name`) - routes export
@@ -991,6 +1025,9 @@ interface Bundle {
     /** The speaker qualifiers the content uses, in the project's order. Absent when no line has one, so a
      *  bundle without qualifiers is exactly as before. */
     qualifiers?: BundleQualifier[];
+    /** The project's speaker pattern, the unlocalised fallback for a qualified speaker's label. Absent when the
+     *  project keeps `DEFAULT_SPEAKER_PATTERN` or uses no qualifiers. */
+    speakerPattern?: string;
     /** The project's own `padAfterDefault`, when it sets one; absent = `DEFAULT_PAD_AFTER`. */
     padAfterDefault?: number;
     properties?: PropertyDecl[];
@@ -1076,6 +1113,8 @@ interface SavedChoicePrompt {
     direction?: string;
     qualifier?: string;
     qualifierName?: string;
+    /** The speaker's label as the choice showed it. Absent in a save written before it existed. */
+    speakerLabel?: string;
     /** The prompt's resolved pause (line padding). Absent in a save written before it existed. */
     padAfter?: number;
 }
@@ -1192,4 +1231,4 @@ declare const PROJECT_SCHEMA = "patter/project@0";
 declare const STRINGS_SCHEMA = "patter/strings@0";
 declare const AUTHORING_SCHEMA = "patter/authoring@0";
 
-export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleQualifier, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type FlowState, type FlowValues, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, HANDOFF_SCHEMA, type HandoffFile, type HandoffImport, type HandoffLine, type HandoffRow, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV2, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, usedQualifiers, walkNodes };
+export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleQualifier, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_SPEAKER_PATTERN, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type FlowState, type FlowValues, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, HANDOFF_SCHEMA, type HandoffFile, type HandoffImport, type HandoffLine, type HandoffRow, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, SPEAKER_PATTERN_KEY, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV2, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, formatSpeakerLabel, gameIdify, isContentlessBeat, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, speakerLabelKey, usedQualifiers, usedSpeakerPairs, walkNodes };

package/dist/index.js

@@ -53,6 +53,29 @@ function usedQualifiers(project, scenes) {
   }
   return projectQualifiers(project).filter((q) => used.has(q.gameId));
 }
+function usedSpeakerPairs(scenes) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const add = (beat) => {
+    if (!beat.character || !beat.qualifier) return;
+    const key = `${beat.character}\0${beat.qualifier}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ character: beat.character, qualifier: beat.qualifier });
+  };
+  for (const scene of scenes) {
+    for (const block of scene.blocks) {
+      walkNodes(block.children, (node) => {
+        if (node.type === "group") {
+          if (node.prompt?.kind === "line") add(node.prompt);
+          return;
+        }
+        for (const beat of node.beats ?? []) if (beat.kind === "line") add(beat);
+      });
+    }
+  }
+  return out;
+}
 var DEFAULT_PAD_AFTER = 0.6;
 var PAD_AFTER_MIN = -10;
 var PAD_AFTER_MAX = 60;
@@ -104,6 +127,14 @@ function castStringKey(name) {
 function qualifierStringKey(gameId) {
   return `qualifier:${gameId}`;
 }
+function speakerLabelKey(name, gameId) {
+  return `speaker:${name}:${gameId}`;
+}
+var SPEAKER_PATTERN_KEY = "speaker:pattern";
+var DEFAULT_SPEAKER_PATTERN = "{name} ({qualifier})";
+function formatSpeakerLabel(pattern, name, qualifier) {
+  return pattern.split("{name}").map((part) => part.split("{qualifier}").join(qualifier)).join(name);
+}
 var HANDOFF_SCHEMA = "patter/handoff@0";
 var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
@@ -127,6 +158,7 @@ export {
   DEFAULT_PAD_AFTER,
   DEFAULT_QUALIFIERS,
   DEFAULT_RECORDING_STATUSES,
+  DEFAULT_SPEAKER_PATTERN,
   DEFAULT_WRITING_STATUSES,
   FLOW_SCHEMA,
   HANDOFF_SCHEMA,
@@ -139,10 +171,12 @@ export {
   RESERVED_PROPERTY_NAMES,
   SAVE_SCHEMA,
   SAVE_VERSION,
+  SPEAKER_PATTERN_KEY,
   STRINGS_SCHEMA,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
+  formatSpeakerLabel,
   gameIdify,
   isCaseOnlyPropertyName,
   isContentlessBeat,
@@ -152,6 +186,8 @@ export {
   projectQualifiers,
   propertyNameify,
   qualifierStringKey,
+  speakerLabelKey,
   usedQualifiers,
+  usedSpeakerPairs,
   walkNodes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/model",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Patter data-model types: source (scene/block/group/snippet/beat/jump), project, locale, authoring. The shape source-of-truth.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,6 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean"
   },
   "dependencies": {
-    "@wildwinter/expr": "^0.5.0"
+    "@wildwinter/expr": "^0.6.0"
   }
 }