@patterkit/model 0.9.0 → 0.11.0

package/dist/index.cjs

@@ -20,19 +20,25 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AUTHORING_SCHEMA: () => AUTHORING_SCHEMA,
   COMMON_GENDERS: () => COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER: () => DEFAULT_CAPTION_CHARACTER,
   DEFAULT_CAPTION_DELIMITERS: () => DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES: () => DEFAULT_DOCUMENTATION_CLASSES,
+  DEFAULT_LAYOUT: () => DEFAULT_LAYOUT,
+  DEFAULT_QUALIFIERS: () => DEFAULT_QUALIFIERS,
   DEFAULT_RECORDING_STATUSES: () => DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES: () => DEFAULT_WRITING_STATUSES,
+  FLOW_SCHEMA: () => FLOW_SCHEMA,
   HANDOFF_SCHEMA: () => HANDOFF_SCHEMA,
   PROJECT_LOCALE_SCENE: () => PROJECT_LOCALE_SCENE,
+  PROJECT_SCHEMA: () => PROJECT_SCHEMA,
   RERECORD_STATUS: () => RERECORD_STATUS,
   RERECORD_STATUS_DECL: () => RERECORD_STATUS_DECL,
   RESERVED_PROPERTY_NAMES: () => import_expr.RESERVED_PROPERTY_NAMES,
   SAVE_SCHEMA: () => SAVE_SCHEMA,
   SAVE_VERSION: () => SAVE_VERSION,
+  STRINGS_SCHEMA: () => STRINGS_SCHEMA,
   castStringKey: () => castStringKey,
   deriveRecordingFolders: () => deriveRecordingFolders,
   effectiveGameId: () => effectiveGameId,
@@ -41,7 +47,11 @@ __export(index_exports, {
   isContentlessBeat: () => isContentlessBeat,
   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);
@@ -71,6 +81,29 @@ 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_WRITING_STATUSES = [
   { name: "stub", colour: 0 },
   // red
@@ -116,26 +149,43 @@ 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";
 var SAVE_SCHEMA = "patter/save@0";
 var SAVE_VERSION = 3;
+var DEFAULT_LAYOUT = { flow: "scenes/", strings: "loc/", authoring: "authoring/" };
+function projectLayout(project) {
+  return { ...DEFAULT_LAYOUT, ...project.layout };
+}
+var FLOW_SCHEMA = "patter/flow@0";
+var PROJECT_SCHEMA = "patter/project@0";
+var STRINGS_SCHEMA = "patter/strings@0";
+var AUTHORING_SCHEMA = "patter/authoring@0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AUTHORING_SCHEMA,
   COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER,
   DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES,
+  DEFAULT_LAYOUT,
+  DEFAULT_QUALIFIERS,
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES,
+  FLOW_SCHEMA,
   HANDOFF_SCHEMA,
   PROJECT_LOCALE_SCENE,
+  PROJECT_SCHEMA,
   RERECORD_STATUS,
   RERECORD_STATUS_DECL,
   RESERVED_PROPERTY_NAMES,
   SAVE_SCHEMA,
   SAVE_VERSION,
+  STRINGS_SCHEMA,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
@@ -144,6 +194,10 @@ var SAVE_VERSION = 3;
   isContentlessBeat,
   isValidGameId,
   isValidPropertyName,
+  projectLayout,
+  projectQualifiers,
   propertyNameify,
+  qualifierStringKey,
+  usedQualifiers,
   walkNodes
 });

package/dist/index.d.cts

@@ -23,6 +23,10 @@ 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;
     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) →
@@ -328,6 +332,29 @@ 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[];
+/** 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
@@ -533,7 +560,7 @@ interface ProjectFile {
         authoring?: string;
     };
     /** `bundle`: the compiled `.patterc` output path (relative to the project root,
-     *  or absolute); default `dist/<project-file-stem>.patterc` (spec §11).
+     *  or absolute); default `../patter-dist/<project-file-stem>.patterc`, beside the project (spec §11).
      *  `localisation`: how strings ship + are resolved (spec §11).
      *    - "embedded" (default): every locale's strings live INSIDE the `.patterc`; the runtime resolves
      *      them and can switch locale live (`setLocale`).
@@ -565,6 +592,9 @@ 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[];
     gameDataFields?: GameDataFields;
     /** Ordered writing-status ladder (not-done -> done); default `DEFAULT_WRITING_STATUSES`. */
     writingStatuses?: WritingStatusDecl[];
@@ -605,12 +635,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 +724,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 +833,9 @@ 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;
     direction?: string;
     /** The text as sent: the baseline for every comparison on reimport. */
     baseline: string;
@@ -910,6 +949,9 @@ 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[];
     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 +1033,8 @@ interface SavedChoicePrompt {
     character?: string;
     characterName?: string;
     direction?: string;
+    qualifier?: string;
+    qualifierName?: string;
 }
 /** One option of a pending choice, saved VERBATIM: re-deriving on load would re-evaluate conditions. */
 interface SavedChoiceOption {
@@ -1067,5 +1111,29 @@ interface SaveGameV2 {
     stageBags: Record<string, Record<string, ScalarValue>>;
     flows: Record<string, FlowSnapshotV2>;
 }
+/** Where a project keeps its shards unless its `layout` says otherwise, relative to the project root. */
+declare const DEFAULT_LAYOUT: {
+    readonly flow: "scenes/";
+    readonly strings: "loc/";
+    readonly authoring: "authoring/";
+};
+/** A project's layout with the defaults filled in: the one place they are written down (the loader,
+ *  validate, localisation, the scene scaffold, and Patterpad each had a copy). */
+declare function projectLayout(project: {
+    layout?: {
+        flow?: string;
+        strings?: string;
+        authoring?: string;
+    };
+}): {
+    flow: string;
+    strings: string;
+    authoring: string;
+};
+/** The source shards' schema tags (spec §10), written by every tool that makes one. */
+declare const FLOW_SCHEMA = "patter/flow@0";
+declare const PROJECT_SCHEMA = "patter/project@0";
+declare const STRINGS_SCHEMA = "patter/strings@0";
+declare const AUTHORING_SCHEMA = "patter/authoring@0";
 
-export { 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_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, 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, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, 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, 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_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, 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,10 @@ 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;
     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) →
@@ -328,6 +332,29 @@ 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[];
+/** 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
@@ -533,7 +560,7 @@ interface ProjectFile {
         authoring?: string;
     };
     /** `bundle`: the compiled `.patterc` output path (relative to the project root,
-     *  or absolute); default `dist/<project-file-stem>.patterc` (spec §11).
+     *  or absolute); default `../patter-dist/<project-file-stem>.patterc`, beside the project (spec §11).
      *  `localisation`: how strings ship + are resolved (spec §11).
      *    - "embedded" (default): every locale's strings live INSIDE the `.patterc`; the runtime resolves
      *      them and can switch locale live (`setLocale`).
@@ -565,6 +592,9 @@ 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[];
     gameDataFields?: GameDataFields;
     /** Ordered writing-status ladder (not-done -> done); default `DEFAULT_WRITING_STATUSES`. */
     writingStatuses?: WritingStatusDecl[];
@@ -605,12 +635,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 +724,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 +833,9 @@ 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;
     direction?: string;
     /** The text as sent: the baseline for every comparison on reimport. */
     baseline: string;
@@ -910,6 +949,9 @@ 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[];
     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 +1033,8 @@ interface SavedChoicePrompt {
     character?: string;
     characterName?: string;
     direction?: string;
+    qualifier?: string;
+    qualifierName?: string;
 }
 /** One option of a pending choice, saved VERBATIM: re-deriving on load would re-evaluate conditions. */
 interface SavedChoiceOption {
@@ -1067,5 +1111,29 @@ interface SaveGameV2 {
     stageBags: Record<string, Record<string, ScalarValue>>;
     flows: Record<string, FlowSnapshotV2>;
 }
+/** Where a project keeps its shards unless its `layout` says otherwise, relative to the project root. */
+declare const DEFAULT_LAYOUT: {
+    readonly flow: "scenes/";
+    readonly strings: "loc/";
+    readonly authoring: "authoring/";
+};
+/** A project's layout with the defaults filled in: the one place they are written down (the loader,
+ *  validate, localisation, the scene scaffold, and Patterpad each had a copy). */
+declare function projectLayout(project: {
+    layout?: {
+        flow?: string;
+        strings?: string;
+        authoring?: string;
+    };
+}): {
+    flow: string;
+    strings: string;
+    authoring: string;
+};
+/** The source shards' schema tags (spec §10), written by every tool that makes one. */
+declare const FLOW_SCHEMA = "patter/flow@0";
+declare const PROJECT_SCHEMA = "patter/project@0";
+declare const STRINGS_SCHEMA = "patter/strings@0";
+declare const AUTHORING_SCHEMA = "patter/authoring@0";
 
-export { 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_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, 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, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, 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, 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_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, 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,29 @@ 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_WRITING_STATUSES = [
   { name: "stub", colour: 0 },
   // red
@@ -75,25 +98,42 @@ 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";
 var SAVE_SCHEMA = "patter/save@0";
 var SAVE_VERSION = 3;
+var DEFAULT_LAYOUT = { flow: "scenes/", strings: "loc/", authoring: "authoring/" };
+function projectLayout(project) {
+  return { ...DEFAULT_LAYOUT, ...project.layout };
+}
+var FLOW_SCHEMA = "patter/flow@0";
+var PROJECT_SCHEMA = "patter/project@0";
+var STRINGS_SCHEMA = "patter/strings@0";
+var AUTHORING_SCHEMA = "patter/authoring@0";
 export {
+  AUTHORING_SCHEMA,
   COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER,
   DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES,
+  DEFAULT_LAYOUT,
+  DEFAULT_QUALIFIERS,
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES,
+  FLOW_SCHEMA,
   HANDOFF_SCHEMA,
   PROJECT_LOCALE_SCENE,
+  PROJECT_SCHEMA,
   RERECORD_STATUS,
   RERECORD_STATUS_DECL,
   RESERVED_PROPERTY_NAMES,
   SAVE_SCHEMA,
   SAVE_VERSION,
+  STRINGS_SCHEMA,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
@@ -102,6 +142,10 @@ export {
   isContentlessBeat,
   isValidGameId,
   isValidPropertyName,
+  projectLayout,
+  projectQualifiers,
   propertyNameify,
+  qualifierStringKey,
+  usedQualifiers,
   walkNodes
 };

package/package.json

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