@patterkit/model 0.10.0 → 0.12.0

package/dist/index.cjs

@@ -26,10 +26,14 @@ __export(index_exports, {
   DEFAULT_CAPTION_DELIMITERS: () => DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES: () => DEFAULT_DOCUMENTATION_CLASSES,
   DEFAULT_LAYOUT: () => DEFAULT_LAYOUT,
+  DEFAULT_PAD_AFTER: () => DEFAULT_PAD_AFTER,
+  DEFAULT_QUALIFIERS: () => DEFAULT_QUALIFIERS,
   DEFAULT_RECORDING_STATUSES: () => DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES: () => DEFAULT_WRITING_STATUSES,
   FLOW_SCHEMA: () => FLOW_SCHEMA,
   HANDOFF_SCHEMA: () => HANDOFF_SCHEMA,
+  PAD_AFTER_MAX: () => PAD_AFTER_MAX,
+  PAD_AFTER_MIN: () => PAD_AFTER_MIN,
   PROJECT_LOCALE_SCENE: () => PROJECT_LOCALE_SCENE,
   PROJECT_SCHEMA: () => PROJECT_SCHEMA,
   RERECORD_STATUS: () => RERECORD_STATUS,
@@ -47,7 +51,10 @@ __export(index_exports, {
   isValidGameId: () => isValidGameId,
   isValidPropertyName: () => import_expr.isValidPropertyName,
   projectLayout: () => projectLayout,
+  projectQualifiers: () => projectQualifiers,
   propertyNameify: () => import_expr.propertyNameify,
+  qualifierStringKey: () => qualifierStringKey,
+  usedQualifiers: () => usedQualifiers,
   walkNodes: () => walkNodes
 });
 module.exports = __toCommonJS(index_exports);
@@ -77,6 +84,32 @@ function effectiveGameId(entity) {
   return g ? g : gameIdify(entity.name);
 }
 var COMMON_GENDERS = ["male", "female", "neuter"];
+var DEFAULT_QUALIFIERS = [
+  { gameId: "vo", name: "V.O.", description: "Voice-over: the character isn't in the scene (a thought, narration, a voice in the ear)." },
+  { gameId: "os", name: "O.S.", description: "Off-screen: the character is there, but not seen (the next room, behind a door)." },
+  { gameId: "radio", name: "RADIO", description: "Heard through a radio, a phone, or a loudspeaker." }
+];
+function projectQualifiers(project) {
+  return project.qualifiers ?? DEFAULT_QUALIFIERS;
+}
+function usedQualifiers(project, scenes) {
+  const used = /* @__PURE__ */ new Set();
+  for (const scene of scenes) {
+    for (const block of scene.blocks) {
+      walkNodes(block.children, (node) => {
+        if (node.type === "group") {
+          if (node.prompt?.kind === "line" && node.prompt.qualifier) used.add(node.prompt.qualifier);
+          return;
+        }
+        for (const beat of node.beats ?? []) if (beat.kind === "line" && beat.qualifier) used.add(beat.qualifier);
+      });
+    }
+  }
+  return projectQualifiers(project).filter((q) => used.has(q.gameId));
+}
+var DEFAULT_PAD_AFTER = 0.6;
+var PAD_AFTER_MIN = -10;
+var PAD_AFTER_MAX = 60;
 var DEFAULT_WRITING_STATUSES = [
   { name: "stub", colour: 0 },
   // red
@@ -122,6 +155,9 @@ var PROJECT_LOCALE_SCENE = "@project";
 function castStringKey(name) {
   return `cast:${name}`;
 }
+function qualifierStringKey(gameId) {
+  return `qualifier:${gameId}`;
+}
 var HANDOFF_SCHEMA = "patter/handoff@0";
 var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
@@ -143,10 +179,14 @@ var AUTHORING_SCHEMA = "patter/authoring@0";
   DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES,
   DEFAULT_LAYOUT,
+  DEFAULT_PAD_AFTER,
+  DEFAULT_QUALIFIERS,
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES,
   FLOW_SCHEMA,
   HANDOFF_SCHEMA,
+  PAD_AFTER_MAX,
+  PAD_AFTER_MIN,
   PROJECT_LOCALE_SCENE,
   PROJECT_SCHEMA,
   RERECORD_STATUS,
@@ -164,6 +204,9 @@ var AUTHORING_SCHEMA = "patter/authoring@0";
   isValidGameId,
   isValidPropertyName,
   projectLayout,
+  projectQualifiers,
   propertyNameify,
+  qualifierStringKey,
+  usedQualifiers,
   walkNodes
 });

package/dist/index.d.cts

@@ -23,6 +23,15 @@ interface LineBeat {
     character?: string;
     /** Performance direction, language-neutral (never localised). */
     direction?: string;
+    /** Speaker qualifier: the `gameId` of one of the project's qualifiers (`vo`, `os`, `radio`), which says
+     *  how the line is delivered (`TAM (O.S.)`), not who says it. Absent = none. The speaker is still
+     *  `character` for every authoring and reporting purpose. See `SpeakerQualifier`. */
+    qualifier?: string;
+    /** The pause after this beat, before the next, in seconds (`padAfter`, design/proposals/line-padding.md):
+     *  positive waits, zero follows at once, negative starts the next line that long before this one ends (a
+     *  cut-in). Absent = the nearest `padAfterDefault` above it, else the project's, else `DEFAULT_PAD_AFTER`.
+     *  Never negative on a snippet's last line or text beat: the runtime clamps it to zero there. */
+    padAfter?: number;
     gameData?: GameData;
     /** Author-defined freeform tags (#215): a cross-cutting label layer that travels to the runtime.
      *  At runtime a beat's tags are the UNION of its own and every ancestor's (scene → block → group(s) →
@@ -38,6 +47,11 @@ interface LineBeat {
 interface TextBeat {
     id: string;
     kind: "text";
+    /** The pause after this beat, before the next, in seconds (`padAfter`, design/proposals/line-padding.md):
+     *  positive waits, zero follows at once, negative starts the next line that long before this one ends (a
+     *  cut-in). Absent = the nearest `padAfterDefault` above it, else the project's, else `DEFAULT_PAD_AFTER`.
+     *  Never negative on a snippet's last line or text beat: the runtime clamps it to zero there. */
+    padAfter?: number;
     gameData?: GameData;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
@@ -85,6 +99,9 @@ interface Snippet {
     beats?: Beat[];
     onEnter?: Effect[];
     onExit?: Effect[];
+    /** The default `padAfter` for the line and text beats inside it that set none (the nearest default wins:
+     *  snippet, then each group, innermost first, then block, then scene, then the project). */
+    padAfterDefault?: number;
     gameData?: GameData;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
@@ -119,6 +136,9 @@ interface Group {
     /** `sequence` config (order × exhaust, spec §4). */
     options?: SequenceOptions;
     children: Array<Group | Snippet>;
+    /** The default `padAfter` for the line and text beats inside it that set none (the nearest default wins:
+     *  snippet, then each group, innermost first, then block, then scene, then the project). */
+    padAfterDefault?: number;
     gameData?: GameData;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
@@ -149,6 +169,9 @@ interface Block {
      */
     gameId?: string;
     children: Array<Group | Snippet>;
+    /** The default `padAfter` for the line and text beats inside it that set none (the nearest default wins:
+     *  snippet, then each group, innermost first, then block, then scene, then the project). */
+    padAfterDefault?: number;
     gameData?: GameData;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
@@ -165,6 +188,9 @@ interface Scene {
     gameId?: string;
     /** Host metadata - e.g. `location` lives here, not as a core field. */
     gameData?: GameData;
+    /** The default `padAfter` for the line and text beats inside it that set none (the nearest default wins:
+     *  snippet, then each group, innermost first, then block, then scene, then the project). */
+    padAfterDefault?: number;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
     /** Entry behaviour / setup (spec §15). */
@@ -328,6 +354,35 @@ interface CastMember {
     actor?: string;
     gameData?: GameData;
 }
+/** A speaker qualifier (a screenplay's character extension): `V.O.`, `O.S.`, `RADIO`, or the project's own.
+ *  A line stores the `gameId`; the `name` is what the cue, Play, and the scripts show, and is localised as a
+ *  cast display name is (`qualifierStringKey`). */
+interface SpeakerQualifier {
+    /** What code switches on, and what a line stores. Unique in the project; hyphen-slug form (`gameIdify`). */
+    gameId: string;
+    /** What the script shows (`V.O.`). Free to change: lines hold the `gameId`. */
+    name: string;
+    /** What the qualifier means, for writers. Authoring only. */
+    description?: string;
+}
+/** The qualifiers a project starts with. Their `gameId`s are pinned (`gameIdify` would make `V.O.` into
+ *  `v-o`); a qualifier a writer adds takes its `gameId` from `gameIdify(name)`. */
+declare const DEFAULT_QUALIFIERS: SpeakerQualifier[];
+/** The project's qualifiers: its own list, else the defaults. */
+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[];
+/** 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;
+/** The range validation keeps a `padAfter` or `padAfterDefault` within, in seconds. */
+declare const PAD_AFTER_MIN = -10;
+declare const PAD_AFTER_MAX = 60;
+/** A qualifier as it reaches a compiled bundle: its `gameId` and authored name (the unlocalised fallback). */
+interface BundleQualifier {
+    gameId: string;
+    name: string;
+}
 /** The cast as it reaches a compiled bundle: the player-facing fields only. `notes`, `actor` and
  *  `gender` are authoring / production / translation context, and the compiler drops them, so a shipped
  *  game never carries a real person's name or a writer's private notes. The compiler copies the shipping
@@ -565,6 +620,12 @@ interface ProjectFile {
      *  externally-gated branches get exercised. Authoring-only (never reaches the runtime bundle). */
     coverageDrivers?: CoverageDriver[];
     cast?: CastMember[];
+    /** The speaker qualifiers a line can pick from, in display order; default `DEFAULT_QUALIFIERS`. An empty
+     *  list means the project uses none. */
+    qualifiers?: SpeakerQualifier[];
+    /** 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;
     gameDataFields?: GameDataFields;
     /** Ordered writing-status ladder (not-done -> done); default `DEFAULT_WRITING_STATUSES`. */
     writingStatuses?: WritingStatusDecl[];
@@ -605,12 +666,16 @@ interface LocaleFile {
     strings: Record<string, string>;
 }
 /** The `scene` marker for a project-level loc shard (`loc/<locale>/_project.patterloc`): strings that
- *  aren't tied to a scene beat - currently cast display names, later project title / UI strings. */
+ *  aren't tied to a scene beat - currently cast display names and speaker qualifier names, later project
+ *  title / UI strings. */
 declare const PROJECT_LOCALE_SCENE = "@project";
 /** The project-level loc-string key for a cast member's player-facing name, e.g. `cast:BARKEEP`.
  *  Namespaced so it can't collide with opaque beat ids. The default-locale value is seeded from the
  *  CastMember's `displayName`; the runtime resolves a character's shown name through this key. */
 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;
 /** Typed documentation annotation line (spec §18). */
 interface DocLine {
     /** The documentation CLASS (a `DocumentationClass.name`) - routes export
@@ -690,6 +755,10 @@ interface Suggestion {
     /** A proposed new direction (the parenthetical), and the direction when suggested ("" for none). */
     proposedDirection?: string;
     baselineDirection?: string;
+    /** A proposed new speaker qualifier (a `gameId` from the project's list, "" for none), and the qualifier
+     *  when suggested ("" for none). */
+    proposedQualifier?: string;
+    baselineQualifier?: string;
     /** A proposal to cut the beat (an editor emptied its line). Accept marks it cut. */
     proposedCut?: boolean;
     /** Where the suggestion came from, when it arrived in an editable-script handoff: the handoff and the
@@ -795,8 +864,13 @@ interface HandoffLine {
     /** The beat id (a line, a narration beat, or an option prompt). */
     id: string;
     kind: "line" | "narration" | "option";
-    /** The speaker and direction as sent (spoken lines only). */
+    /** The speaker, speaker qualifier (`gameId`), and direction as sent (spoken lines only). */
     character?: string;
+    qualifier?: string;
+    /** The qualifier's name as the cue printed it (`O.S.` in `TAM (O.S.)`), so a returned cue is read against
+     *  what the editor saw even after the name changes in settings. Absent in handoffs written before it was
+     *  recorded, which compare against the qualifier's current name. */
+    qualifierName?: string;
     direction?: string;
     /** The text as sent: the baseline for every comparison on reimport. */
     baseline: string;
@@ -841,6 +915,7 @@ interface CompiledSnippet {
     beats?: Beat[];
     onEnter?: CompiledEffect[];
     onExit?: CompiledEffect[];
+    padAfterDefault?: number;
     gameData?: GameData;
     tags?: string[];
     jump?: Jump;
@@ -860,6 +935,7 @@ interface CompiledGroup {
     shared?: boolean;
     options?: SequenceOptions;
     children: Array<CompiledGroup | CompiledSnippet>;
+    padAfterDefault?: number;
     gameData?: GameData;
     tags?: string[];
     /** Option-position fields (spec §5) - only when a direct child of a `choice`. */
@@ -877,6 +953,7 @@ interface CompiledBlock {
     /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
     gameId?: string;
     children: Array<CompiledGroup | CompiledSnippet>;
+    padAfterDefault?: number;
     gameData?: GameData;
     tags?: string[];
 }
@@ -886,6 +963,7 @@ interface CompiledScene {
     name: string;
     /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
     gameId?: string;
+    padAfterDefault?: number;
     gameData?: GameData;
     tags?: string[];
     onEntry?: CompiledEffect[];
@@ -910,6 +988,11 @@ interface Bundle {
     };
     /** Player-facing cast only: the compiler strips notes / actor / gender (see `BundleCastMember`). */
     cast?: BundleCastMember[];
+    /** 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 own `padAfterDefault`, when it sets one; absent = `DEFAULT_PAD_AFTER`. */
+    padAfterDefault?: number;
     properties?: PropertyDecl[];
     /** Host / world scope declarations, baked from the project so the runtime can self-back a declared
      *  scope (`@world`, ...) when no host resolver claims its token. Absent = no host scopes. */
@@ -991,6 +1074,10 @@ interface SavedChoicePrompt {
     character?: string;
     characterName?: string;
     direction?: string;
+    qualifier?: string;
+    qualifierName?: string;
+    /** The prompt's resolved pause (line padding). Absent in a save written before it existed. */
+    padAfter?: number;
 }
 /** One option of a pending choice, saved VERBATIM: re-deriving on load would re-evaluate conditions. */
 interface SavedChoiceOption {
@@ -1092,4 +1179,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, 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_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 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, 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 StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, projectLayout, 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_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 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 };

package/dist/index.d.ts

@@ -23,6 +23,15 @@ interface LineBeat {
     character?: string;
     /** Performance direction, language-neutral (never localised). */
     direction?: string;
+    /** Speaker qualifier: the `gameId` of one of the project's qualifiers (`vo`, `os`, `radio`), which says
+     *  how the line is delivered (`TAM (O.S.)`), not who says it. Absent = none. The speaker is still
+     *  `character` for every authoring and reporting purpose. See `SpeakerQualifier`. */
+    qualifier?: string;
+    /** The pause after this beat, before the next, in seconds (`padAfter`, design/proposals/line-padding.md):
+     *  positive waits, zero follows at once, negative starts the next line that long before this one ends (a
+     *  cut-in). Absent = the nearest `padAfterDefault` above it, else the project's, else `DEFAULT_PAD_AFTER`.
+     *  Never negative on a snippet's last line or text beat: the runtime clamps it to zero there. */
+    padAfter?: number;
     gameData?: GameData;
     /** Author-defined freeform tags (#215): a cross-cutting label layer that travels to the runtime.
      *  At runtime a beat's tags are the UNION of its own and every ancestor's (scene → block → group(s) →
@@ -38,6 +47,11 @@ interface LineBeat {
 interface TextBeat {
     id: string;
     kind: "text";
+    /** The pause after this beat, before the next, in seconds (`padAfter`, design/proposals/line-padding.md):
+     *  positive waits, zero follows at once, negative starts the next line that long before this one ends (a
+     *  cut-in). Absent = the nearest `padAfterDefault` above it, else the project's, else `DEFAULT_PAD_AFTER`.
+     *  Never negative on a snippet's last line or text beat: the runtime clamps it to zero there. */
+    padAfter?: number;
     gameData?: GameData;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
@@ -85,6 +99,9 @@ interface Snippet {
     beats?: Beat[];
     onEnter?: Effect[];
     onExit?: Effect[];
+    /** The default `padAfter` for the line and text beats inside it that set none (the nearest default wins:
+     *  snippet, then each group, innermost first, then block, then scene, then the project). */
+    padAfterDefault?: number;
     gameData?: GameData;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
@@ -119,6 +136,9 @@ interface Group {
     /** `sequence` config (order × exhaust, spec §4). */
     options?: SequenceOptions;
     children: Array<Group | Snippet>;
+    /** The default `padAfter` for the line and text beats inside it that set none (the nearest default wins:
+     *  snippet, then each group, innermost first, then block, then scene, then the project). */
+    padAfterDefault?: number;
     gameData?: GameData;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
@@ -149,6 +169,9 @@ interface Block {
      */
     gameId?: string;
     children: Array<Group | Snippet>;
+    /** The default `padAfter` for the line and text beats inside it that set none (the nearest default wins:
+     *  snippet, then each group, innermost first, then block, then scene, then the project). */
+    padAfterDefault?: number;
     gameData?: GameData;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
@@ -165,6 +188,9 @@ interface Scene {
     gameId?: string;
     /** Host metadata - e.g. `location` lives here, not as a core field. */
     gameData?: GameData;
+    /** The default `padAfter` for the line and text beats inside it that set none (the nearest default wins:
+     *  snippet, then each group, innermost first, then block, then scene, then the project). */
+    padAfterDefault?: number;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
     /** Entry behaviour / setup (spec §15). */
@@ -328,6 +354,35 @@ interface CastMember {
     actor?: string;
     gameData?: GameData;
 }
+/** A speaker qualifier (a screenplay's character extension): `V.O.`, `O.S.`, `RADIO`, or the project's own.
+ *  A line stores the `gameId`; the `name` is what the cue, Play, and the scripts show, and is localised as a
+ *  cast display name is (`qualifierStringKey`). */
+interface SpeakerQualifier {
+    /** What code switches on, and what a line stores. Unique in the project; hyphen-slug form (`gameIdify`). */
+    gameId: string;
+    /** What the script shows (`V.O.`). Free to change: lines hold the `gameId`. */
+    name: string;
+    /** What the qualifier means, for writers. Authoring only. */
+    description?: string;
+}
+/** The qualifiers a project starts with. Their `gameId`s are pinned (`gameIdify` would make `V.O.` into
+ *  `v-o`); a qualifier a writer adds takes its `gameId` from `gameIdify(name)`. */
+declare const DEFAULT_QUALIFIERS: SpeakerQualifier[];
+/** The project's qualifiers: its own list, else the defaults. */
+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[];
+/** 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;
+/** The range validation keeps a `padAfter` or `padAfterDefault` within, in seconds. */
+declare const PAD_AFTER_MIN = -10;
+declare const PAD_AFTER_MAX = 60;
+/** A qualifier as it reaches a compiled bundle: its `gameId` and authored name (the unlocalised fallback). */
+interface BundleQualifier {
+    gameId: string;
+    name: string;
+}
 /** The cast as it reaches a compiled bundle: the player-facing fields only. `notes`, `actor` and
  *  `gender` are authoring / production / translation context, and the compiler drops them, so a shipped
  *  game never carries a real person's name or a writer's private notes. The compiler copies the shipping
@@ -565,6 +620,12 @@ interface ProjectFile {
      *  externally-gated branches get exercised. Authoring-only (never reaches the runtime bundle). */
     coverageDrivers?: CoverageDriver[];
     cast?: CastMember[];
+    /** The speaker qualifiers a line can pick from, in display order; default `DEFAULT_QUALIFIERS`. An empty
+     *  list means the project uses none. */
+    qualifiers?: SpeakerQualifier[];
+    /** 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;
     gameDataFields?: GameDataFields;
     /** Ordered writing-status ladder (not-done -> done); default `DEFAULT_WRITING_STATUSES`. */
     writingStatuses?: WritingStatusDecl[];
@@ -605,12 +666,16 @@ interface LocaleFile {
     strings: Record<string, string>;
 }
 /** The `scene` marker for a project-level loc shard (`loc/<locale>/_project.patterloc`): strings that
- *  aren't tied to a scene beat - currently cast display names, later project title / UI strings. */
+ *  aren't tied to a scene beat - currently cast display names and speaker qualifier names, later project
+ *  title / UI strings. */
 declare const PROJECT_LOCALE_SCENE = "@project";
 /** The project-level loc-string key for a cast member's player-facing name, e.g. `cast:BARKEEP`.
  *  Namespaced so it can't collide with opaque beat ids. The default-locale value is seeded from the
  *  CastMember's `displayName`; the runtime resolves a character's shown name through this key. */
 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;
 /** Typed documentation annotation line (spec §18). */
 interface DocLine {
     /** The documentation CLASS (a `DocumentationClass.name`) - routes export
@@ -690,6 +755,10 @@ interface Suggestion {
     /** A proposed new direction (the parenthetical), and the direction when suggested ("" for none). */
     proposedDirection?: string;
     baselineDirection?: string;
+    /** A proposed new speaker qualifier (a `gameId` from the project's list, "" for none), and the qualifier
+     *  when suggested ("" for none). */
+    proposedQualifier?: string;
+    baselineQualifier?: string;
     /** A proposal to cut the beat (an editor emptied its line). Accept marks it cut. */
     proposedCut?: boolean;
     /** Where the suggestion came from, when it arrived in an editable-script handoff: the handoff and the
@@ -795,8 +864,13 @@ interface HandoffLine {
     /** The beat id (a line, a narration beat, or an option prompt). */
     id: string;
     kind: "line" | "narration" | "option";
-    /** The speaker and direction as sent (spoken lines only). */
+    /** The speaker, speaker qualifier (`gameId`), and direction as sent (spoken lines only). */
     character?: string;
+    qualifier?: string;
+    /** The qualifier's name as the cue printed it (`O.S.` in `TAM (O.S.)`), so a returned cue is read against
+     *  what the editor saw even after the name changes in settings. Absent in handoffs written before it was
+     *  recorded, which compare against the qualifier's current name. */
+    qualifierName?: string;
     direction?: string;
     /** The text as sent: the baseline for every comparison on reimport. */
     baseline: string;
@@ -841,6 +915,7 @@ interface CompiledSnippet {
     beats?: Beat[];
     onEnter?: CompiledEffect[];
     onExit?: CompiledEffect[];
+    padAfterDefault?: number;
     gameData?: GameData;
     tags?: string[];
     jump?: Jump;
@@ -860,6 +935,7 @@ interface CompiledGroup {
     shared?: boolean;
     options?: SequenceOptions;
     children: Array<CompiledGroup | CompiledSnippet>;
+    padAfterDefault?: number;
     gameData?: GameData;
     tags?: string[];
     /** Option-position fields (spec §5) - only when a direct child of a `choice`. */
@@ -877,6 +953,7 @@ interface CompiledBlock {
     /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
     gameId?: string;
     children: Array<CompiledGroup | CompiledSnippet>;
+    padAfterDefault?: number;
     gameData?: GameData;
     tags?: string[];
 }
@@ -886,6 +963,7 @@ interface CompiledScene {
     name: string;
     /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
     gameId?: string;
+    padAfterDefault?: number;
     gameData?: GameData;
     tags?: string[];
     onEntry?: CompiledEffect[];
@@ -910,6 +988,11 @@ interface Bundle {
     };
     /** Player-facing cast only: the compiler strips notes / actor / gender (see `BundleCastMember`). */
     cast?: BundleCastMember[];
+    /** 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 own `padAfterDefault`, when it sets one; absent = `DEFAULT_PAD_AFTER`. */
+    padAfterDefault?: number;
     properties?: PropertyDecl[];
     /** Host / world scope declarations, baked from the project so the runtime can self-back a declared
      *  scope (`@world`, ...) when no host resolver claims its token. Absent = no host scopes. */
@@ -991,6 +1074,10 @@ interface SavedChoicePrompt {
     character?: string;
     characterName?: string;
     direction?: string;
+    qualifier?: string;
+    qualifierName?: string;
+    /** The prompt's resolved pause (line padding). Absent in a save written before it existed. */
+    padAfter?: number;
 }
 /** One option of a pending choice, saved VERBATIM: re-deriving on load would re-evaluate conditions. */
 interface SavedChoiceOption {
@@ -1092,4 +1179,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, 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_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 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, 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 StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, projectLayout, 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_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 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 };

package/dist/index.js

@@ -30,6 +30,32 @@ function effectiveGameId(entity) {
   return g ? g : gameIdify(entity.name);
 }
 var COMMON_GENDERS = ["male", "female", "neuter"];
+var DEFAULT_QUALIFIERS = [
+  { gameId: "vo", name: "V.O.", description: "Voice-over: the character isn't in the scene (a thought, narration, a voice in the ear)." },
+  { gameId: "os", name: "O.S.", description: "Off-screen: the character is there, but not seen (the next room, behind a door)." },
+  { gameId: "radio", name: "RADIO", description: "Heard through a radio, a phone, or a loudspeaker." }
+];
+function projectQualifiers(project) {
+  return project.qualifiers ?? DEFAULT_QUALIFIERS;
+}
+function usedQualifiers(project, scenes) {
+  const used = /* @__PURE__ */ new Set();
+  for (const scene of scenes) {
+    for (const block of scene.blocks) {
+      walkNodes(block.children, (node) => {
+        if (node.type === "group") {
+          if (node.prompt?.kind === "line" && node.prompt.qualifier) used.add(node.prompt.qualifier);
+          return;
+        }
+        for (const beat of node.beats ?? []) if (beat.kind === "line" && beat.qualifier) used.add(beat.qualifier);
+      });
+    }
+  }
+  return projectQualifiers(project).filter((q) => used.has(q.gameId));
+}
+var DEFAULT_PAD_AFTER = 0.6;
+var PAD_AFTER_MIN = -10;
+var PAD_AFTER_MAX = 60;
 var DEFAULT_WRITING_STATUSES = [
   { name: "stub", colour: 0 },
   // red
@@ -75,6 +101,9 @@ var PROJECT_LOCALE_SCENE = "@project";
 function castStringKey(name) {
   return `cast:${name}`;
 }
+function qualifierStringKey(gameId) {
+  return `qualifier:${gameId}`;
+}
 var HANDOFF_SCHEMA = "patter/handoff@0";
 var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
@@ -95,10 +124,14 @@ export {
   DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES,
   DEFAULT_LAYOUT,
+  DEFAULT_PAD_AFTER,
+  DEFAULT_QUALIFIERS,
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES,
   FLOW_SCHEMA,
   HANDOFF_SCHEMA,
+  PAD_AFTER_MAX,
+  PAD_AFTER_MIN,
   PROJECT_LOCALE_SCENE,
   PROJECT_SCHEMA,
   RERECORD_STATUS,
@@ -116,6 +149,9 @@ export {
   isValidGameId,
   isValidPropertyName,
   projectLayout,
+  projectQualifiers,
   propertyNameify,
+  qualifierStringKey,
+  usedQualifiers,
   walkNodes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/model",
-  "version": "0.10.0",
+  "version": "0.12.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",