@patterkit/model 0.1.2 → 0.2.0

package/dist/index.cjs

@@ -26,6 +26,8 @@ __export(index_exports, {
   DEFAULT_RECORDING_STATUSES: () => DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES: () => DEFAULT_WRITING_STATUSES,
   PROJECT_LOCALE_SCENE: () => PROJECT_LOCALE_SCENE,
+  RERECORD_STATUS: () => RERECORD_STATUS,
+  RERECORD_STATUS_DECL: () => RERECORD_STATUS_DECL,
   castStringKey: () => castStringKey,
   deriveRecordingFolders: () => deriveRecordingFolders,
   effectiveGameId: () => effectiveGameId,
@@ -81,6 +83,8 @@ var DEFAULT_RECORDING_STATUSES = [
   { name: "final", colour: 9 }
   // purple
 ];
+var RERECORD_STATUS = "rerecord";
+var RERECORD_STATUS_DECL = { name: RERECORD_STATUS, colour: 1 };
 function deriveRecordingFolders(audioRoot, statuses) {
   const root = audioRoot?.trim();
   return statuses.map((s, i) => {
@@ -110,6 +114,8 @@ var DEFAULT_CAPTION_CHARACTER = "SFX";
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES,
   PROJECT_LOCALE_SCENE,
+  RERECORD_STATUS,
+  RERECORD_STATUS_DECL,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,

package/dist/index.d.cts

@@ -293,11 +293,18 @@ interface CoverageDriver {
     /** The pool the harness picks from (uniform). Empty = the driver is inert. */
     values: ScalarValue[];
 }
+/** A character's grammatical gender, for localisation. Translators need it to inflect the speaker's own
+ *  lines in gendered languages (adjectives, participles, pronouns), which the source text alone often
+ *  cannot tell them. Absent means "not specified". Authoring-only: it never reaches the runtime bundle,
+ *  but it IS carried into the localisation handoff formats as translator context (spec §14). */
+type GrammaticalGender = "male" | "female" | "neuter";
 interface CastMember {
     /** Canonical speaker name (matched by a beat's `character`); language-neutral key. */
     name: string;
     /** Localised player-facing name - a localisation id (project-level strings). */
     displayName?: string;
+    /** Grammatical gender for translators (see `GrammaticalGender`); absent = not specified. */
+    gender?: GrammaticalGender;
     /** Free-text production notes about the character (casting, voice, intent) - authoring only. */
     notes?: string;
     /** The voice actor cast for this character, if known - surfaced in the VO script export (spec §16).
@@ -305,6 +312,12 @@ interface CastMember {
     actor?: string;
     gameData?: GameData;
 }
+/** 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
+ *  fields across explicitly (an allow-list), which is what actually keeps a new authoring field out of
+ *  the bundle; this type states the resulting contract for anyone reading a bundle. */
+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";
@@ -357,6 +370,13 @@ interface RecordingStatusDecl {
 /** The default recording-status ladder (used when a project declares none). The FIRST rung is the
  *  level-0 / absence status: a beat with no recorded status counts as `missing`. */
 declare const DEFAULT_RECORDING_STATUSES: RecordingStatusDecl[];
+/** The reserved recording status a line takes when it is flagged **needs re-record** (#227): a recorded
+ *  take exists but is unusable (bad quality, wrong take), so it must be redone. It is NOT a ladder rung -
+ *  it is a regression flag that MASKS the derived / manual rung for the recording script, the production
+ *  report, and status browse, so a line "recorded" on disk still shows up as work to do. Reserved so it
+ *  can't collide with an author-declared rung; carries its own alert colour. */
+declare const RERECORD_STATUS = "rerecord";
+declare const RERECORD_STATUS_DECL: RecordingStatusDecl;
 /** One recording rung mapped to the folder its audio files live in (Audio Folders mode). */
 interface RecordingFolder {
     name: string;
@@ -663,6 +683,14 @@ interface AuthoringFile {
      * it as a separate "cut: N" figure so a removal is visible, not vanished.
      */
     cut?: Record<string, boolean>;
+    /**
+     * **Needs re-record** (#227): dialogue-line ids whose recorded take is unusable and must be redone
+     * (bad quality, wrong take, misread). Orthogonal to the recording ladder - a flagged line keeps its
+     * audio on disk, but its recording status is MASKED to the reserved `rerecord` status for the recording
+     * script / report / status browse (see `RERECORD_STATUS`), so a "recorded" line still reads as work.
+     * Authoring-only; never compiled into a bundle.
+     */
+    rerecord?: Record<string, boolean>;
 }
 /** A compiled expression envelope: canonical source + pre-derived tagged-tuple AST. */
 interface Expression {
@@ -748,7 +776,8 @@ interface Bundle {
         default: string;
         included: string[];
     };
-    cast?: CastMember[];
+    /** Player-facing cast only: the compiler strips notes / actor / gender (see `BundleCastMember`). */
+    cast?: BundleCastMember[];
     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. */
@@ -790,4 +819,4 @@ declare const DEFAULT_CAPTION_DELIMITERS: CaptionDelimiters;
  *  captions are off). Applies even to a project that pins no `closedCaptions`. */
 declare const DEFAULT_CAPTION_CHARACTER = "SFX";
 
-export { type AuthoringFile, type Beat, type Block, type Bundle, 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 EstimatingConfig, type Expression, type FlowFile, type FlowNode, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type Group, 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, type RecordingFolder, type RecordingStatusDecl, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SequenceOptions, type Snippet, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };
+export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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 EstimatingConfig, type Expression, type FlowFile, type FlowNode, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, 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, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SequenceOptions, type Snippet, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };

package/dist/index.d.ts

@@ -293,11 +293,18 @@ interface CoverageDriver {
     /** The pool the harness picks from (uniform). Empty = the driver is inert. */
     values: ScalarValue[];
 }
+/** A character's grammatical gender, for localisation. Translators need it to inflect the speaker's own
+ *  lines in gendered languages (adjectives, participles, pronouns), which the source text alone often
+ *  cannot tell them. Absent means "not specified". Authoring-only: it never reaches the runtime bundle,
+ *  but it IS carried into the localisation handoff formats as translator context (spec §14). */
+type GrammaticalGender = "male" | "female" | "neuter";
 interface CastMember {
     /** Canonical speaker name (matched by a beat's `character`); language-neutral key. */
     name: string;
     /** Localised player-facing name - a localisation id (project-level strings). */
     displayName?: string;
+    /** Grammatical gender for translators (see `GrammaticalGender`); absent = not specified. */
+    gender?: GrammaticalGender;
     /** Free-text production notes about the character (casting, voice, intent) - authoring only. */
     notes?: string;
     /** The voice actor cast for this character, if known - surfaced in the VO script export (spec §16).
@@ -305,6 +312,12 @@ interface CastMember {
     actor?: string;
     gameData?: GameData;
 }
+/** 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
+ *  fields across explicitly (an allow-list), which is what actually keeps a new authoring field out of
+ *  the bundle; this type states the resulting contract for anyone reading a bundle. */
+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";
@@ -357,6 +370,13 @@ interface RecordingStatusDecl {
 /** The default recording-status ladder (used when a project declares none). The FIRST rung is the
  *  level-0 / absence status: a beat with no recorded status counts as `missing`. */
 declare const DEFAULT_RECORDING_STATUSES: RecordingStatusDecl[];
+/** The reserved recording status a line takes when it is flagged **needs re-record** (#227): a recorded
+ *  take exists but is unusable (bad quality, wrong take), so it must be redone. It is NOT a ladder rung -
+ *  it is a regression flag that MASKS the derived / manual rung for the recording script, the production
+ *  report, and status browse, so a line "recorded" on disk still shows up as work to do. Reserved so it
+ *  can't collide with an author-declared rung; carries its own alert colour. */
+declare const RERECORD_STATUS = "rerecord";
+declare const RERECORD_STATUS_DECL: RecordingStatusDecl;
 /** One recording rung mapped to the folder its audio files live in (Audio Folders mode). */
 interface RecordingFolder {
     name: string;
@@ -663,6 +683,14 @@ interface AuthoringFile {
      * it as a separate "cut: N" figure so a removal is visible, not vanished.
      */
     cut?: Record<string, boolean>;
+    /**
+     * **Needs re-record** (#227): dialogue-line ids whose recorded take is unusable and must be redone
+     * (bad quality, wrong take, misread). Orthogonal to the recording ladder - a flagged line keeps its
+     * audio on disk, but its recording status is MASKED to the reserved `rerecord` status for the recording
+     * script / report / status browse (see `RERECORD_STATUS`), so a "recorded" line still reads as work.
+     * Authoring-only; never compiled into a bundle.
+     */
+    rerecord?: Record<string, boolean>;
 }
 /** A compiled expression envelope: canonical source + pre-derived tagged-tuple AST. */
 interface Expression {
@@ -748,7 +776,8 @@ interface Bundle {
         default: string;
         included: string[];
     };
-    cast?: CastMember[];
+    /** Player-facing cast only: the compiler strips notes / actor / gender (see `BundleCastMember`). */
+    cast?: BundleCastMember[];
     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. */
@@ -790,4 +819,4 @@ declare const DEFAULT_CAPTION_DELIMITERS: CaptionDelimiters;
  *  captions are off). Applies even to a project that pins no `closedCaptions`. */
 declare const DEFAULT_CAPTION_CHARACTER = "SFX";
 
-export { type AuthoringFile, type Beat, type Block, type Bundle, 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 EstimatingConfig, type Expression, type FlowFile, type FlowNode, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type Group, 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, type RecordingFolder, type RecordingStatusDecl, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SequenceOptions, type Snippet, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };
+export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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 EstimatingConfig, type Expression, type FlowFile, type FlowNode, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, 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, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SequenceOptions, type Snippet, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };

package/dist/index.js

@@ -45,6 +45,8 @@ var DEFAULT_RECORDING_STATUSES = [
   { name: "final", colour: 9 }
   // purple
 ];
+var RERECORD_STATUS = "rerecord";
+var RERECORD_STATUS_DECL = { name: RERECORD_STATUS, colour: 1 };
 function deriveRecordingFolders(audioRoot, statuses) {
   const root = audioRoot?.trim();
   return statuses.map((s, i) => {
@@ -73,6 +75,8 @@ export {
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES,
   PROJECT_LOCALE_SCENE,
+  RERECORD_STATUS,
+  RERECORD_STATUS_DECL,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,

package/package.json

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