@patterkit/model 0.20.0 → 0.22.0

package/dist/index.cjs

@@ -36,6 +36,9 @@ __export(index_exports, {
   EXTENSION_SHARD: () => EXTENSION_SHARD,
   FLOW_SCHEMA: () => FLOW_SCHEMA,
   HANDOFF_SCHEMA: () => HANDOFF_SCHEMA,
+  LINE_CHARS_PER_SECOND: () => LINE_CHARS_PER_SECOND,
+  LINE_DURATION_MAX: () => LINE_DURATION_MAX,
+  LINE_DURATION_MIN: () => LINE_DURATION_MIN,
   MANIFEST_EXTENSION: () => MANIFEST_EXTENSION,
   PAD_AFTER_MAX: () => PAD_AFTER_MAX,
   PAD_AFTER_MIN: () => PAD_AFTER_MIN,
@@ -53,12 +56,13 @@ __export(index_exports, {
   castStringKey: () => castStringKey,
   deriveRecordingFolders: () => deriveRecordingFolders,
   effectiveGameId: () => effectiveGameId,
+  estimateLineDuration: () => estimateLineDuration,
   formatSpeakerLabel: () => formatSpeakerLabel,
-  gameIdify: () => gameIdify,
+  gameIdify: () => import_toolkit.gameIdify,
   isCaseOnlyPropertyName: () => import_expr.isCaseOnlyPropertyName,
   isContentlessBeat: () => isContentlessBeat,
   isDialogueScene: () => isDialogueScene,
-  isValidGameId: () => isValidGameId,
+  isValidGameId: () => import_toolkit.isValidGameId,
   isValidPropertyName: () => import_expr.isValidPropertyName,
   projectLayout: () => projectLayout,
   projectQualifiers: () => projectQualifiers,
@@ -73,6 +77,7 @@ __export(index_exports, {
   walkNodes: () => walkNodes
 });
 module.exports = __toCommonJS(index_exports);
+var import_toolkit = require("@wildwinter/toolkit");
 var import_expr = require("@wildwinter/expr");
 function walkNodes(nodes, visit) {
   for (const node of nodes) {
@@ -88,15 +93,9 @@ function isContentlessBeat(beat, hasText) {
   if (beat.tags && beat.tags.length > 0) return false;
   return beat.kind === "text" || !beat.character && !beat.direction;
 }
-function gameIdify(text) {
-  return text.toLowerCase().replace(/['’]/g, "").replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
-}
-function isValidGameId(gameId) {
-  return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(gameId);
-}
 function effectiveGameId(entity) {
   const g = entity.gameId?.trim();
-  return g ? g : gameIdify(entity.name);
+  return g ? g : (0, import_toolkit.gameIdify)(entity.name);
 }
 function sceneAddressIndex(scenes) {
   const byAddress = /* @__PURE__ */ new Map();
@@ -177,6 +176,14 @@ function textIsAction(project, scene) {
 var DEFAULT_PAD_AFTER = 0.6;
 var PAD_AFTER_MIN = -10;
 var PAD_AFTER_MAX = 60;
+var LINE_CHARS_PER_SECOND = 14;
+var LINE_DURATION_MIN = 1.5;
+var LINE_DURATION_MAX = 18;
+function estimateLineDuration(text, _locale) {
+  let count = 0;
+  for (const ch of text ?? "") if (ch !== "\xAD") count++;
+  return Math.min(Math.max(count / LINE_CHARS_PER_SECOND, LINE_DURATION_MIN), LINE_DURATION_MAX);
+}
 var DEFAULT_WRITING_STATUSES = [
   { name: "stub", colour: 0 },
   // red
@@ -205,7 +212,7 @@ function deriveRecordingFolders(audioRoot, statuses) {
   const root = audioRoot?.trim();
   return statuses.map((s, i) => {
     if (i === 0 || !root) return { name: s.name };
-    return { name: s.name, folder: `${root}/${gameIdify(s.name)}` };
+    return { name: s.name, folder: `${root}/${(0, import_toolkit.gameIdify)(s.name)}` };
   });
 }
 var DEFAULT_DOCUMENTATION_CLASSES = [
@@ -237,7 +244,7 @@ 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 SAVE_VERSION = 4;
 var DEFAULT_LAYOUT = { flow: "scenes/", strings: "loc/", authoring: "authoring/", extensions: "extensions/" };
 function projectLayout(project) {
   return { ...DEFAULT_LAYOUT, ...project.layout };
@@ -270,6 +277,9 @@ var UNRESOLVED_KEY = "unresolved";
   EXTENSION_SHARD,
   FLOW_SCHEMA,
   HANDOFF_SCHEMA,
+  LINE_CHARS_PER_SECOND,
+  LINE_DURATION_MAX,
+  LINE_DURATION_MIN,
   MANIFEST_EXTENSION,
   PAD_AFTER_MAX,
   PAD_AFTER_MIN,
@@ -287,6 +297,7 @@ var UNRESOLVED_KEY = "unresolved";
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
+  estimateLineDuration,
   formatSpeakerLabel,
   gameIdify,
   isCaseOnlyPropertyName,

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { AstNode } from '@wildwinter/expr';
 export { RESERVED_PROPERTY_NAMES, isCaseOnlyPropertyName, isValidPropertyName, propertyNameify } from '@wildwinter/expr';
+export { gameIdify, isValidGameId } from '@wildwinter/toolkit';
 
 type ScalarValue = boolean | number | string | string[];
 /** Developer-defined host metadata (spec §17). Opaque to Patter. */
@@ -246,11 +247,6 @@ declare function walkNodes<N extends {
  * just `{ jump }` with zero beats - which is valid.
  */
 declare function isContentlessBeat(beat: Beat, hasText: boolean): boolean;
-/** Slugify a name into a hyphen-form game id: lowercase, drop apostrophes, runs of
- *  other punctuation -> a single hyphen, collapse repeats, no leading / trailing hyphen. */
-declare function gameIdify(text: string): string;
-/** A valid authored game id: lowercase alphanumerics + hyphens, no leading / trailing hyphen. */
-declare function isValidGameId(gameId: string): boolean;
 
 /** The effective address: the explicit `gameId` if pinned, else derived from `name`. */
 declare function effectiveGameId(entity: {
@@ -392,6 +388,11 @@ interface CastMember {
      *  (`{ 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>;
+    /** The character's colour in the editors (their cue, the play window, the readable script): a slot of the
+     *  family's curated palette, 0 to 11. Absent, the colour comes from a hash of the name, so a cast needs no
+     *  setup; renaming a character stamps the old name's slot here, so they keep their colour. Authoring only
+     *  (not shipped in the runtime bundle). */
+    colour?: number;
     gameData?: GameData;
 }
 /** A speaker qualifier (a screenplay's character extension): `V.O.`, `O.S.`, `RADIO`, or the project's own.
@@ -430,17 +431,28 @@ 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;
+/** The reading rate a line with no recording is timed by, in characters a second (`estimateLineDuration`). */
+declare const LINE_CHARS_PER_SECOND = 14;
+/** The shortest and longest a line with no recording lasts, in seconds (`estimateLineDuration`). */
+declare const LINE_DURATION_MIN = 1.5;
+declare const LINE_DURATION_MAX = 18;
+/** How long a line with no recording lasts, in seconds: its characters at 14 a second, clamped to 1.5 to 18
+ *  seconds. A character is a Unicode code point (one outside the Basic Multilingual Plane counts once), and soft
+ *  hyphens (U+00AD) aren't counted. This is the one rule every Patter tool and runtime times a line by: Patterpad's
+ *  Play window, the playable HTML page, and the Unity, Unreal, and Godot runtimes, which the conformance corpus
+ *  holds to the same numbers. `locale` is reserved for per-language reading rates and is unused for now. */
+declare function estimateLineDuration(text: string, _locale?: string): number;
 /** 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
+/** The cast as it reaches a compiled bundle: the player-facing fields only. `notes`, `actor`,
+ *  `gender` and `colour` 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">;
+type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender" | "colour">;
 /** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
  *  Beat kinds map straight through: dialogue = `line`, text = `text`, game event = `gameEvent`.
  *  `option` is a choice's option: a group that is a direct child of a `choice` group, whose gameData the
@@ -1091,6 +1103,13 @@ interface Bundle {
         default: string;
         included: string[];
     };
+    /** Where a flow opened without a scene starts: the project's authored start (scene id, and block id when
+     *  it names one). Absent when the project sets none, or names one that has gone: every runtime then starts
+     *  at the first scene. */
+    start?: {
+        scene: string;
+        block?: string;
+    };
     /** 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
@@ -1154,7 +1173,7 @@ declare const DEFAULT_CAPTION_DELIMITERS: CaptionDelimiters;
 declare const DEFAULT_CAPTION_CHARACTER = "SFX";
 declare const SAVE_SCHEMA = "patter/save@0";
 /** The `save.version` inside the envelope. Bumped only when a reader would MISREAD an older save. */
-declare const SAVE_VERSION = 3;
+declare const SAVE_VERSION = 4;
 /** The tagged envelope a host stores: `serializeState` writes it, `deserializeState` refuses anything else. */
 interface SaveEnvelope {
     schema: typeof SAVE_SCHEMA;
@@ -1181,8 +1200,11 @@ interface StackFrame {
      *  restore against an EDITED bundle re-finds the position by id. Absent when the frame sat at its
      *  container's end (no next child), or in an older save. */
     nextId?: string;
+    /** SNAPSHOT-ONLY: on a frame whose container is an option of a choice, that choice group's id, so a load
+     *  whose option has gone offers the choice again. Absent on every other frame, and in a version 3 save. */
+    choiceId?: string;
 }
-/** The prompt of a saved choice option: the choice text as a structured line/text beat. */
+/** A prompt as the choice showed it: a replayed prompt still to be spoken (`FlowCursor.pendingPrompt`). */
 interface SavedChoicePrompt {
     kind: "line" | "text";
     text: string;
@@ -1196,10 +1218,12 @@ interface SavedChoicePrompt {
     /** 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. */
+/** One option of a pending choice: which option, and whether it could be taken, saved VERBATIM, since
+ *  re-deriving on load would re-evaluate conditions. Its prompt is not saved: it is built again in the
+ *  language in use each time the choice is delivered. (A version 3 save's option also has a `prompt`,
+ *  which a load discards.) */
 interface SavedChoiceOption {
     id: string;
-    prompt?: SavedChoicePrompt;
     eligible: boolean;
     gameData?: GameData;
 }
@@ -1215,17 +1239,21 @@ interface FlowCursor {
     /** The continuation stack (call frames + the active block run), root first. */
     stack: StackFrame[];
     activeSnippetId: string | null;
-    beatIndex: number;
+    /** The id of the next beat the active snippet delivers, so a load against an edited bundle finds its
+     *  place by id. Absent when no snippet is active or the active one has delivered every beat. */
+    beatId?: string;
+    /** Version 3 only, read and never written: the index of the next beat in the active snippet. */
+    beatIndex?: number;
     /** Present (non-null) iff the flow is stopped at a choice. */
     pendingChoice: SavedChoice | null;
     /** The chosen option owning a prompt still to be replayed (a save taken between choose + advance).
      *  Optional / null in older saves -> no pending prompt. */
     pendingPromptOwnerId?: string | null;
-    /** The prompt still to be replayed, exactly as the choice SHOWED it (text and speaker fields, the same
-     *  shape as a saved option's `prompt`), so the replay after a load says what the player saw. Written only
-     *  alongside a `pendingPromptOwnerId` (the choose -> advance window, with `replayPromptOnChoose`), and
-     *  absent otherwise. A save without it (written before Patterplay 0.18.0) resolves the owner's prompt beat
-     *  when it is delivered, as before. */
+    /** The prompt still to be replayed, exactly as the choice SHOWED it (text and speaker fields), so the
+     *  replay after a load says what the player saw, in the language they saw it in: the one prompt a save
+     *  keeps as text. Written only alongside a `pendingPromptOwnerId` (the choose -> advance window, with
+     *  `replayPromptOnChoose`), and absent otherwise. A save without it (written before Patterplay 0.18.0)
+     *  resolves the owner's prompt beat when it is delivered, as before. */
     pendingPrompt?: SavedChoicePrompt;
     /** This flow's (non-shared) selector cursors, keyed by group id. */
     selectors: Record<string, SelectorSnapshot>;
@@ -1238,10 +1266,10 @@ interface FlowSnapshot {
     visits: Record<string, number>;
     cursor: FlowCursor;
 }
-/** A full resumable save-game (version 3): everything that is not a property, plus the registry's
+/** A full resumable save-game (version 4): everything that is not a property, plus the registry's
  *  values when the engine made its own registry. */
 interface SaveGame {
-    version: 3;
+    version: typeof SAVE_VERSION;
     /** The engine's own registry's values, keyed by registry key: present only when the engine made the
      *  registry itself (a standalone game). A game that passed a registry saves it once, beside this. */
     registry?: EngineSave;
@@ -1252,17 +1280,18 @@ interface SaveGame {
     /** Each live flow's snapshot, keyed by flow id. */
     flows: Record<string, FlowSnapshot>;
 }
-/** One flow's own property values, without its id: the sections a version 2 save carried per flow, and a
- *  `FlowState` carries now. */
+/** A version 3 save, still read: the same shape apart from the cursor (`beatIndex` for `beatId`, no
+ *  `choiceId` on its frames) and a pending choice's options (each with its prompt text, discarded). */
+interface SaveGameV3 extends Omit<SaveGame, "version"> {
+    version: 3;
+}
+/** One flow's own property values, without its id: what a `FlowState` carries beside its snapshot. */
 interface FlowValues {
     /** The NOT-shared `@patter` globals, under token "patter". */
     scopes: EngineSave;
     /** Per-scene NOT-shared `@scene` bags (scene id -> name -> value). */
     sceneBags: Record<string, Record<string, ScalarValue>>;
 }
-/** A version 2 flow snapshot, which carried the flow's property values itself. Still read. */
-interface FlowSnapshotV2 extends FlowSnapshot, FlowValues {
-}
 /**
  * One flow taken out of an engine (`engine.captureFlow`) to be put back later (`engine.restoreFlow`), under the
  * same id or another: its snapshot as a save writes it, and its own property values without its id. Plain data
@@ -1270,19 +1299,8 @@ interface FlowSnapshotV2 extends FlowSnapshot, FlowValues {
  * visit counts, shared selectors) is never in it, so restoring one rewinds nothing else.
  */
 interface FlowState extends FlowSnapshot, FlowValues {
-    version: typeof SAVE_VERSION;
-}
-/** A version 2 save, from before the registry held the properties. Every runtime still reads it: its
- *  property sections move into the registry (under the keys in the header above) as it loads. */
-interface SaveGameV2 {
-    version: 2;
-    /** Shared `@patter` globals (owned scope "patter"). */
-    shared: EngineSave;
-    sharedVisits: Record<string, number>;
-    sharedSelectors: Record<string, SelectorSnapshot>;
-    /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value). */
-    stageBags: Record<string, Record<string, ScalarValue>>;
-    flows: Record<string, FlowSnapshotV2>;
+    /** `SAVE_VERSION` when written; a version 3 state still restores. */
+    version: typeof SAVE_VERSION | 3;
 }
 /** Where a project keeps its shards unless its `layout` says otherwise, relative to the project root. */
 declare const DEFAULT_LAYOUT: {
@@ -1394,4 +1412,4 @@ interface ExtensionFieldDecl {
 /** A node's extension values in a bundle: extension id -> field -> value, raw. */
 type NodeExtensions = Record<string, Record<string, unknown>>;
 
-export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleExtension, 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, EXTENSIONS_DIR, EXTENSION_SCHEMA, EXTENSION_SHARD, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type ExtensionFieldDecl, type ExtensionShard, 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, MANIFEST_EXTENSION, type NodeExtensions, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_EXTENSION_STEM, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectExtension, type ProjectFile, type ProjectLayout, 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, UNRESOLVED_KEY, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, formatSpeakerLabel, gameIdify, isContentlessBeat, isDialogueScene, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, resolveSceneRef, sceneAddressIndex, speakerLabelKey, textIsAction, usedQualifiers, usedSpeakerPairs, walkNodes };
+export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleExtension, 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, EXTENSIONS_DIR, EXTENSION_SCHEMA, EXTENSION_SHARD, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type ExtensionFieldDecl, type ExtensionShard, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, 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, LINE_CHARS_PER_SECOND, LINE_DURATION_MAX, LINE_DURATION_MIN, type LineBeat, type LocaleFile, MANIFEST_EXTENSION, type NodeExtensions, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_EXTENSION_STEM, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectExtension, type ProjectFile, type ProjectLayout, 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 SaveGameV3, 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, UNRESOLVED_KEY, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, estimateLineDuration, formatSpeakerLabel, isContentlessBeat, isDialogueScene, projectLayout, projectQualifiers, qualifierStringKey, resolveSceneRef, sceneAddressIndex, speakerLabelKey, textIsAction, usedQualifiers, usedSpeakerPairs, walkNodes };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { AstNode } from '@wildwinter/expr';
 export { RESERVED_PROPERTY_NAMES, isCaseOnlyPropertyName, isValidPropertyName, propertyNameify } from '@wildwinter/expr';
+export { gameIdify, isValidGameId } from '@wildwinter/toolkit';
 
 type ScalarValue = boolean | number | string | string[];
 /** Developer-defined host metadata (spec §17). Opaque to Patter. */
@@ -246,11 +247,6 @@ declare function walkNodes<N extends {
  * just `{ jump }` with zero beats - which is valid.
  */
 declare function isContentlessBeat(beat: Beat, hasText: boolean): boolean;
-/** Slugify a name into a hyphen-form game id: lowercase, drop apostrophes, runs of
- *  other punctuation -> a single hyphen, collapse repeats, no leading / trailing hyphen. */
-declare function gameIdify(text: string): string;
-/** A valid authored game id: lowercase alphanumerics + hyphens, no leading / trailing hyphen. */
-declare function isValidGameId(gameId: string): boolean;
 
 /** The effective address: the explicit `gameId` if pinned, else derived from `name`. */
 declare function effectiveGameId(entity: {
@@ -392,6 +388,11 @@ interface CastMember {
      *  (`{ 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>;
+    /** The character's colour in the editors (their cue, the play window, the readable script): a slot of the
+     *  family's curated palette, 0 to 11. Absent, the colour comes from a hash of the name, so a cast needs no
+     *  setup; renaming a character stamps the old name's slot here, so they keep their colour. Authoring only
+     *  (not shipped in the runtime bundle). */
+    colour?: number;
     gameData?: GameData;
 }
 /** A speaker qualifier (a screenplay's character extension): `V.O.`, `O.S.`, `RADIO`, or the project's own.
@@ -430,17 +431,28 @@ 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;
+/** The reading rate a line with no recording is timed by, in characters a second (`estimateLineDuration`). */
+declare const LINE_CHARS_PER_SECOND = 14;
+/** The shortest and longest a line with no recording lasts, in seconds (`estimateLineDuration`). */
+declare const LINE_DURATION_MIN = 1.5;
+declare const LINE_DURATION_MAX = 18;
+/** How long a line with no recording lasts, in seconds: its characters at 14 a second, clamped to 1.5 to 18
+ *  seconds. A character is a Unicode code point (one outside the Basic Multilingual Plane counts once), and soft
+ *  hyphens (U+00AD) aren't counted. This is the one rule every Patter tool and runtime times a line by: Patterpad's
+ *  Play window, the playable HTML page, and the Unity, Unreal, and Godot runtimes, which the conformance corpus
+ *  holds to the same numbers. `locale` is reserved for per-language reading rates and is unused for now. */
+declare function estimateLineDuration(text: string, _locale?: string): number;
 /** 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
+/** The cast as it reaches a compiled bundle: the player-facing fields only. `notes`, `actor`,
+ *  `gender` and `colour` 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">;
+type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender" | "colour">;
 /** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
  *  Beat kinds map straight through: dialogue = `line`, text = `text`, game event = `gameEvent`.
  *  `option` is a choice's option: a group that is a direct child of a `choice` group, whose gameData the
@@ -1091,6 +1103,13 @@ interface Bundle {
         default: string;
         included: string[];
     };
+    /** Where a flow opened without a scene starts: the project's authored start (scene id, and block id when
+     *  it names one). Absent when the project sets none, or names one that has gone: every runtime then starts
+     *  at the first scene. */
+    start?: {
+        scene: string;
+        block?: string;
+    };
     /** 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
@@ -1154,7 +1173,7 @@ declare const DEFAULT_CAPTION_DELIMITERS: CaptionDelimiters;
 declare const DEFAULT_CAPTION_CHARACTER = "SFX";
 declare const SAVE_SCHEMA = "patter/save@0";
 /** The `save.version` inside the envelope. Bumped only when a reader would MISREAD an older save. */
-declare const SAVE_VERSION = 3;
+declare const SAVE_VERSION = 4;
 /** The tagged envelope a host stores: `serializeState` writes it, `deserializeState` refuses anything else. */
 interface SaveEnvelope {
     schema: typeof SAVE_SCHEMA;
@@ -1181,8 +1200,11 @@ interface StackFrame {
      *  restore against an EDITED bundle re-finds the position by id. Absent when the frame sat at its
      *  container's end (no next child), or in an older save. */
     nextId?: string;
+    /** SNAPSHOT-ONLY: on a frame whose container is an option of a choice, that choice group's id, so a load
+     *  whose option has gone offers the choice again. Absent on every other frame, and in a version 3 save. */
+    choiceId?: string;
 }
-/** The prompt of a saved choice option: the choice text as a structured line/text beat. */
+/** A prompt as the choice showed it: a replayed prompt still to be spoken (`FlowCursor.pendingPrompt`). */
 interface SavedChoicePrompt {
     kind: "line" | "text";
     text: string;
@@ -1196,10 +1218,12 @@ interface SavedChoicePrompt {
     /** 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. */
+/** One option of a pending choice: which option, and whether it could be taken, saved VERBATIM, since
+ *  re-deriving on load would re-evaluate conditions. Its prompt is not saved: it is built again in the
+ *  language in use each time the choice is delivered. (A version 3 save's option also has a `prompt`,
+ *  which a load discards.) */
 interface SavedChoiceOption {
     id: string;
-    prompt?: SavedChoicePrompt;
     eligible: boolean;
     gameData?: GameData;
 }
@@ -1215,17 +1239,21 @@ interface FlowCursor {
     /** The continuation stack (call frames + the active block run), root first. */
     stack: StackFrame[];
     activeSnippetId: string | null;
-    beatIndex: number;
+    /** The id of the next beat the active snippet delivers, so a load against an edited bundle finds its
+     *  place by id. Absent when no snippet is active or the active one has delivered every beat. */
+    beatId?: string;
+    /** Version 3 only, read and never written: the index of the next beat in the active snippet. */
+    beatIndex?: number;
     /** Present (non-null) iff the flow is stopped at a choice. */
     pendingChoice: SavedChoice | null;
     /** The chosen option owning a prompt still to be replayed (a save taken between choose + advance).
      *  Optional / null in older saves -> no pending prompt. */
     pendingPromptOwnerId?: string | null;
-    /** The prompt still to be replayed, exactly as the choice SHOWED it (text and speaker fields, the same
-     *  shape as a saved option's `prompt`), so the replay after a load says what the player saw. Written only
-     *  alongside a `pendingPromptOwnerId` (the choose -> advance window, with `replayPromptOnChoose`), and
-     *  absent otherwise. A save without it (written before Patterplay 0.18.0) resolves the owner's prompt beat
-     *  when it is delivered, as before. */
+    /** The prompt still to be replayed, exactly as the choice SHOWED it (text and speaker fields), so the
+     *  replay after a load says what the player saw, in the language they saw it in: the one prompt a save
+     *  keeps as text. Written only alongside a `pendingPromptOwnerId` (the choose -> advance window, with
+     *  `replayPromptOnChoose`), and absent otherwise. A save without it (written before Patterplay 0.18.0)
+     *  resolves the owner's prompt beat when it is delivered, as before. */
     pendingPrompt?: SavedChoicePrompt;
     /** This flow's (non-shared) selector cursors, keyed by group id. */
     selectors: Record<string, SelectorSnapshot>;
@@ -1238,10 +1266,10 @@ interface FlowSnapshot {
     visits: Record<string, number>;
     cursor: FlowCursor;
 }
-/** A full resumable save-game (version 3): everything that is not a property, plus the registry's
+/** A full resumable save-game (version 4): everything that is not a property, plus the registry's
  *  values when the engine made its own registry. */
 interface SaveGame {
-    version: 3;
+    version: typeof SAVE_VERSION;
     /** The engine's own registry's values, keyed by registry key: present only when the engine made the
      *  registry itself (a standalone game). A game that passed a registry saves it once, beside this. */
     registry?: EngineSave;
@@ -1252,17 +1280,18 @@ interface SaveGame {
     /** Each live flow's snapshot, keyed by flow id. */
     flows: Record<string, FlowSnapshot>;
 }
-/** One flow's own property values, without its id: the sections a version 2 save carried per flow, and a
- *  `FlowState` carries now. */
+/** A version 3 save, still read: the same shape apart from the cursor (`beatIndex` for `beatId`, no
+ *  `choiceId` on its frames) and a pending choice's options (each with its prompt text, discarded). */
+interface SaveGameV3 extends Omit<SaveGame, "version"> {
+    version: 3;
+}
+/** One flow's own property values, without its id: what a `FlowState` carries beside its snapshot. */
 interface FlowValues {
     /** The NOT-shared `@patter` globals, under token "patter". */
     scopes: EngineSave;
     /** Per-scene NOT-shared `@scene` bags (scene id -> name -> value). */
     sceneBags: Record<string, Record<string, ScalarValue>>;
 }
-/** A version 2 flow snapshot, which carried the flow's property values itself. Still read. */
-interface FlowSnapshotV2 extends FlowSnapshot, FlowValues {
-}
 /**
  * One flow taken out of an engine (`engine.captureFlow`) to be put back later (`engine.restoreFlow`), under the
  * same id or another: its snapshot as a save writes it, and its own property values without its id. Plain data
@@ -1270,19 +1299,8 @@ interface FlowSnapshotV2 extends FlowSnapshot, FlowValues {
  * visit counts, shared selectors) is never in it, so restoring one rewinds nothing else.
  */
 interface FlowState extends FlowSnapshot, FlowValues {
-    version: typeof SAVE_VERSION;
-}
-/** A version 2 save, from before the registry held the properties. Every runtime still reads it: its
- *  property sections move into the registry (under the keys in the header above) as it loads. */
-interface SaveGameV2 {
-    version: 2;
-    /** Shared `@patter` globals (owned scope "patter"). */
-    shared: EngineSave;
-    sharedVisits: Record<string, number>;
-    sharedSelectors: Record<string, SelectorSnapshot>;
-    /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value). */
-    stageBags: Record<string, Record<string, ScalarValue>>;
-    flows: Record<string, FlowSnapshotV2>;
+    /** `SAVE_VERSION` when written; a version 3 state still restores. */
+    version: typeof SAVE_VERSION | 3;
 }
 /** Where a project keeps its shards unless its `layout` says otherwise, relative to the project root. */
 declare const DEFAULT_LAYOUT: {
@@ -1394,4 +1412,4 @@ interface ExtensionFieldDecl {
 /** A node's extension values in a bundle: extension id -> field -> value, raw. */
 type NodeExtensions = Record<string, Record<string, unknown>>;
 
-export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleExtension, 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, EXTENSIONS_DIR, EXTENSION_SCHEMA, EXTENSION_SHARD, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type ExtensionFieldDecl, type ExtensionShard, 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, MANIFEST_EXTENSION, type NodeExtensions, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_EXTENSION_STEM, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectExtension, type ProjectFile, type ProjectLayout, 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, UNRESOLVED_KEY, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, formatSpeakerLabel, gameIdify, isContentlessBeat, isDialogueScene, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, resolveSceneRef, sceneAddressIndex, speakerLabelKey, textIsAction, usedQualifiers, usedSpeakerPairs, walkNodes };
+export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleExtension, 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, EXTENSIONS_DIR, EXTENSION_SCHEMA, EXTENSION_SHARD, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type ExtensionFieldDecl, type ExtensionShard, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, 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, LINE_CHARS_PER_SECOND, LINE_DURATION_MAX, LINE_DURATION_MIN, type LineBeat, type LocaleFile, MANIFEST_EXTENSION, type NodeExtensions, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_EXTENSION_STEM, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectExtension, type ProjectFile, type ProjectLayout, 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 SaveGameV3, 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, UNRESOLVED_KEY, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, estimateLineDuration, formatSpeakerLabel, isContentlessBeat, isDialogueScene, projectLayout, projectQualifiers, qualifierStringKey, resolveSceneRef, sceneAddressIndex, speakerLabelKey, textIsAction, usedQualifiers, usedSpeakerPairs, walkNodes };

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/index.ts
+import { gameIdify, isValidGameId } from "@wildwinter/toolkit";
 import {
   propertyNameify,
   isValidPropertyName,
@@ -19,12 +20,6 @@ function isContentlessBeat(beat, hasText) {
   if (beat.tags && beat.tags.length > 0) return false;
   return beat.kind === "text" || !beat.character && !beat.direction;
 }
-function gameIdify(text) {
-  return text.toLowerCase().replace(/['’]/g, "").replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
-}
-function isValidGameId(gameId) {
-  return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(gameId);
-}
 function effectiveGameId(entity) {
   const g = entity.gameId?.trim();
   return g ? g : gameIdify(entity.name);
@@ -108,6 +103,14 @@ function textIsAction(project, scene) {
 var DEFAULT_PAD_AFTER = 0.6;
 var PAD_AFTER_MIN = -10;
 var PAD_AFTER_MAX = 60;
+var LINE_CHARS_PER_SECOND = 14;
+var LINE_DURATION_MIN = 1.5;
+var LINE_DURATION_MAX = 18;
+function estimateLineDuration(text, _locale) {
+  let count = 0;
+  for (const ch of text ?? "") if (ch !== "\xAD") count++;
+  return Math.min(Math.max(count / LINE_CHARS_PER_SECOND, LINE_DURATION_MIN), LINE_DURATION_MAX);
+}
 var DEFAULT_WRITING_STATUSES = [
   { name: "stub", colour: 0 },
   // red
@@ -168,7 +171,7 @@ 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 SAVE_VERSION = 4;
 var DEFAULT_LAYOUT = { flow: "scenes/", strings: "loc/", authoring: "authoring/", extensions: "extensions/" };
 function projectLayout(project) {
   return { ...DEFAULT_LAYOUT, ...project.layout };
@@ -200,6 +203,9 @@ export {
   EXTENSION_SHARD,
   FLOW_SCHEMA,
   HANDOFF_SCHEMA,
+  LINE_CHARS_PER_SECOND,
+  LINE_DURATION_MAX,
+  LINE_DURATION_MIN,
   MANIFEST_EXTENSION,
   PAD_AFTER_MAX,
   PAD_AFTER_MIN,
@@ -217,6 +223,7 @@ export {
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
+  estimateLineDuration,
   formatSpeakerLabel,
   gameIdify,
   isCaseOnlyPropertyName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/model",
-  "version": "0.20.0",
+  "version": "0.22.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,7 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean"
   },
   "dependencies": {
-    "@wildwinter/expr": "^0.6.0"
+    "@wildwinter/expr": "^0.6.0",
+    "@wildwinter/toolkit": "^0.4.0"
   }
 }