@patterkit/model 0.22.0 → 0.24.0

package/dist/index.d.cts

@@ -2,6 +2,33 @@ import { AstNode } from '@wildwinter/expr';
 export { RESERVED_PROPERTY_NAMES, isCaseOnlyPropertyName, isValidPropertyName, propertyNameify } from '@wildwinter/expr';
 export { gameIdify, isValidGameId } from '@wildwinter/toolkit';
 
+/** What a speech unit is: a syllable (the mouth opens), a beat with the mouth shut (っ), or a pause. */
+type SpeechUnitKind = "syllable" | "closed" | "pause";
+/** One unit of a line as it would be spoken. `start` and `end` are code-point offsets into the text, end exclusive. */
+interface SpeechUnit {
+    kind: SpeechUnitKind;
+    weight: number;
+    start: number;
+    end: number;
+}
+/** A digit's weight: most read as one or two syllables. */
+declare const SPEECH_DIGIT_WEIGHT = 1.5;
+/** A Han character's weight in Japanese text. */
+declare const SPEECH_KANJI_WEIGHT = 2;
+/** A short pause's weight (`,` `;` `、`), and a long one's (`.` `?` `。`). */
+declare const SPEECH_PAUSE_SHORT_WEIGHT = 1;
+declare const SPEECH_PAUSE_LONG_WEIGHT = 2;
+/**
+ * A line broken into the units it would be spoken in: its syllables, its beats with the mouth shut, and its pauses,
+ * in order, each with a weight. `locale` is the language the line is spoken in (the project's main language, not the
+ * one being shown); it decides English's and French's silent e, and Japanese kanji, which also apply when the line
+ * has any kana in it.
+ */
+declare function speechUnits(text: string, locale?: string): SpeechUnit[];
+/** How many syllables a line would be spoken in: its syllables' and shut beats' weights, pauses aside. `locale` is
+ *  the language it's spoken in, as for `speechUnits`. */
+declare function countSyllables(text: string, locale?: string): number;
+
 type ScalarValue = boolean | number | string | string[];
 /** Developer-defined host metadata (spec §17). Opaque to Patter. */
 type GameData = Record<string, unknown>;
@@ -431,17 +458,22 @@ 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;
+/** How many syllables a second a line with no recording is timed at, unless the project sets its own
+ *  (`estimateSyllablesPerSecond`), and the range validation keeps a project's within. */
+declare const DEFAULT_ESTIMATE_SYLLABLES_PER_SECOND = 4;
+declare const ESTIMATE_SYLLABLES_PER_SECOND_MIN = 2;
+declare const ESTIMATE_SYLLABLES_PER_SECOND_MAX = 10;
 /** 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;
+/** How long a line with no recording lasts, in seconds: the total weight of its speech units (its syllables and its
+ *  pauses, `speechUnits`) at `syllablesPerSecond` (default 4, the project's `estimateSyllablesPerSecond` when it
+ *  sets one), clamped to 1.5 to 18 seconds. `text` and `locale` are the line as it's spoken, in the project's main
+ *  language (a line result's `spokenText` and `spokenLocale`), never a translation being shown. 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. A rate that isn't a
+ *  positive number is the default. A line with a recording lasts as long as the recording, whatever this says. */
+declare function estimateLineDuration(text: string, locale?: string, syllablesPerSecond?: number): number;
 /** A qualifier as it reaches a compiled bundle: its `gameId` and authored name (the unlocalised fallback). */
 interface BundleQualifier {
     gameId: string;
@@ -599,6 +631,43 @@ interface EstimatingConfig {
         lines: number;
     }[];
 }
+/** A folder in the scene list (ProjectFile.sceneFolders): organisational only, it carries no meaning. */
+interface SceneFolder {
+    id: string;
+    name: string;
+    /** The folder it sits in; omitted = the top level. A parent that doesn't exist, or a loop of parents
+     *  (only a bad merge makes one), reads as the top level. */
+    parent?: string;
+}
+/** One row of the scene list as laid out by `sceneFolderLayout`, top to bottom with every folder open. */
+interface SceneNavRow {
+    kind: "folder" | "scene";
+    id: string;
+    /** 0 = the top level. */
+    depth: number;
+    /** The folder this row sits in, if any. */
+    folder?: string;
+}
+interface SceneFolderLayout {
+    /** Every folder and scene, depth first, in authored order. */
+    rows: SceneNavRow[];
+    /** The scene ids in that order: what the nav, the exports, and the bundle list scenes by. */
+    sceneIds: string[];
+    /** Each folder's effective parent (undefined = top level), after the forgiving rules. */
+    folderParent: Map<string, string | undefined>;
+    /** Each scene's effective folder (undefined = top level). */
+    sceneFolder: Map<string, string | undefined>;
+}
+/**
+ * Lay out the scene list: folders and scenes, nested and ordered. Forgiving, as `sceneOrder` always was:
+ * a scene filed in a missing folder, or a folder with a missing parent, sits at the top level; a loop of
+ * parents is broken at the first folder of it in `sceneFolders`; ids in `sceneOrder` that are neither
+ * are ignored. In each level the rows `sceneOrder` lists come first, in its order, then unlisted scenes in
+ * the order given, then unlisted folders in `sceneFolders` order.
+ */
+declare function sceneFolderLayout(project: Pick<ProjectFile, "sceneOrder" | "sceneFolders" | "sceneFolder">, sceneIds: readonly string[]): SceneFolderLayout;
+/** A scene's folder path for display ("Act 1 / The docks"), or "" at the top level. */
+declare function sceneFolderPath(project: Pick<ProjectFile, "sceneFolders">, layout: Pick<SceneFolderLayout, "folderParent" | "sceneFolder">, sceneId: string): string;
 interface ProjectFile {
     schema: string;
     root?: boolean;
@@ -619,8 +688,17 @@ interface ProjectFile {
     };
     /** The authored scene order (scene ids) for navigation. Scenes not listed follow in file order;
      *  listed ids that no longer exist are ignored. Omitted = plain file order. Presentation only:
-     *  it never affects play, which always starts from `start` / an explicit address. */
+     *  it never affects play, which always starts from `start` / an explicit address.
+     *  Holds scene folder ids too (`sceneFolders`): folders and scenes mix in one order, and Patterpad keeps
+     *  the list equal to the scene list as shown, read top to bottom with every folder open. */
     sceneOrder?: string[];
+    /** Folders for organising the scene list (design/proposals/scene-folders.md). Navigation only, like
+     *  `sceneOrder`: no file moves, nothing reaches the bundle. The list's own order means nothing; where a
+     *  folder is shown comes from `sceneOrder`. Omitted = no folders. */
+    sceneFolders?: SceneFolder[];
+    /** Scene id -> the id of the folder it's filed in. A scene not listed sits at the top level; an entry
+     *  naming a folder that doesn't exist is ignored. A map, so two people filing different scenes merge. */
+    sceneFolder?: Record<string, string>;
     /** Version-control system (spec §12); omitted = unset / none. */
     vcs?: VcsKind;
     /** Project-wide VO mode (spec §16) - one boolean, no per-scene override. */
@@ -704,6 +782,10 @@ interface ProjectFile {
     /** 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;
+    /** How many syllables a second a line with no recording is timed at (`estimateLineDuration`), from 2 to 10.
+     *  Only estimates use it: a line with a recording lasts as long as the recording. Absent =
+     *  `DEFAULT_ESTIMATE_SYLLABLES_PER_SECOND`. */
+    estimateSyllablesPerSecond?: number;
     /** Localise text lines in dialogue scenes (design/proposals/action-text.md). Off (absent) by default: a
      *  dialogue scene's text beats (`isDialogueScene`) are then ACTION, left out of the loc files and the
      *  written word counts, and compiled with `action: true`. On: they're localised and shown as a text
@@ -1120,6 +1202,9 @@ interface Bundle {
     speakerPattern?: string;
     /** The project's own `padAfterDefault`, when it sets one; absent = `DEFAULT_PAD_AFTER`. */
     padAfterDefault?: number;
+    /** The project's own `estimateSyllablesPerSecond`, when it sets one; absent =
+     *  `DEFAULT_ESTIMATE_SYLLABLES_PER_SECOND`. */
+    estimateSyllablesPerSecond?: 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. */
@@ -1235,6 +1320,8 @@ interface SavedChoice {
 /** The flow's execution position: where it is, and what it is waiting on. */
 interface FlowCursor {
     flowEnded: boolean;
+    /** The choice group whose running dry ended the flow (its `end` step's reason "ran-dry"). Present only then. */
+    ranDry?: string;
     currentSceneId: string | null;
     /** The continuation stack (call frames + the active block run), root first. */
     stack: StackFrame[];
@@ -1412,4 +1499,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 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 };
+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_ESTIMATE_SYLLABLES_PER_SECOND, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_SPEAKER_PATTERN, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, ESTIMATE_SYLLABLES_PER_SECOND_MAX, ESTIMATE_SYLLABLES_PER_SECOND_MIN, 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_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, SPEECH_DIGIT_WEIGHT, SPEECH_KANJI_WEIGHT, SPEECH_PAUSE_LONG_WEIGHT, SPEECH_PAUSE_SHORT_WEIGHT, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV3, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type SceneFolder, type SceneFolderLayout, type SceneNavRow, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type SpeechUnit, type SpeechUnitKind, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, UNRESOLVED_KEY, type VcsKind, type WritingStatusDecl, castStringKey, countSyllables, deriveRecordingFolders, effectiveGameId, estimateLineDuration, formatSpeakerLabel, isContentlessBeat, isDialogueScene, projectLayout, projectQualifiers, qualifierStringKey, resolveSceneRef, sceneAddressIndex, sceneFolderLayout, sceneFolderPath, speakerLabelKey, speechUnits, textIsAction, usedQualifiers, usedSpeakerPairs, walkNodes };

package/dist/index.d.ts

@@ -2,6 +2,33 @@ import { AstNode } from '@wildwinter/expr';
 export { RESERVED_PROPERTY_NAMES, isCaseOnlyPropertyName, isValidPropertyName, propertyNameify } from '@wildwinter/expr';
 export { gameIdify, isValidGameId } from '@wildwinter/toolkit';
 
+/** What a speech unit is: a syllable (the mouth opens), a beat with the mouth shut (っ), or a pause. */
+type SpeechUnitKind = "syllable" | "closed" | "pause";
+/** One unit of a line as it would be spoken. `start` and `end` are code-point offsets into the text, end exclusive. */
+interface SpeechUnit {
+    kind: SpeechUnitKind;
+    weight: number;
+    start: number;
+    end: number;
+}
+/** A digit's weight: most read as one or two syllables. */
+declare const SPEECH_DIGIT_WEIGHT = 1.5;
+/** A Han character's weight in Japanese text. */
+declare const SPEECH_KANJI_WEIGHT = 2;
+/** A short pause's weight (`,` `;` `、`), and a long one's (`.` `?` `。`). */
+declare const SPEECH_PAUSE_SHORT_WEIGHT = 1;
+declare const SPEECH_PAUSE_LONG_WEIGHT = 2;
+/**
+ * A line broken into the units it would be spoken in: its syllables, its beats with the mouth shut, and its pauses,
+ * in order, each with a weight. `locale` is the language the line is spoken in (the project's main language, not the
+ * one being shown); it decides English's and French's silent e, and Japanese kanji, which also apply when the line
+ * has any kana in it.
+ */
+declare function speechUnits(text: string, locale?: string): SpeechUnit[];
+/** How many syllables a line would be spoken in: its syllables' and shut beats' weights, pauses aside. `locale` is
+ *  the language it's spoken in, as for `speechUnits`. */
+declare function countSyllables(text: string, locale?: string): number;
+
 type ScalarValue = boolean | number | string | string[];
 /** Developer-defined host metadata (spec §17). Opaque to Patter. */
 type GameData = Record<string, unknown>;
@@ -431,17 +458,22 @@ 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;
+/** How many syllables a second a line with no recording is timed at, unless the project sets its own
+ *  (`estimateSyllablesPerSecond`), and the range validation keeps a project's within. */
+declare const DEFAULT_ESTIMATE_SYLLABLES_PER_SECOND = 4;
+declare const ESTIMATE_SYLLABLES_PER_SECOND_MIN = 2;
+declare const ESTIMATE_SYLLABLES_PER_SECOND_MAX = 10;
 /** 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;
+/** How long a line with no recording lasts, in seconds: the total weight of its speech units (its syllables and its
+ *  pauses, `speechUnits`) at `syllablesPerSecond` (default 4, the project's `estimateSyllablesPerSecond` when it
+ *  sets one), clamped to 1.5 to 18 seconds. `text` and `locale` are the line as it's spoken, in the project's main
+ *  language (a line result's `spokenText` and `spokenLocale`), never a translation being shown. 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. A rate that isn't a
+ *  positive number is the default. A line with a recording lasts as long as the recording, whatever this says. */
+declare function estimateLineDuration(text: string, locale?: string, syllablesPerSecond?: number): number;
 /** A qualifier as it reaches a compiled bundle: its `gameId` and authored name (the unlocalised fallback). */
 interface BundleQualifier {
     gameId: string;
@@ -599,6 +631,43 @@ interface EstimatingConfig {
         lines: number;
     }[];
 }
+/** A folder in the scene list (ProjectFile.sceneFolders): organisational only, it carries no meaning. */
+interface SceneFolder {
+    id: string;
+    name: string;
+    /** The folder it sits in; omitted = the top level. A parent that doesn't exist, or a loop of parents
+     *  (only a bad merge makes one), reads as the top level. */
+    parent?: string;
+}
+/** One row of the scene list as laid out by `sceneFolderLayout`, top to bottom with every folder open. */
+interface SceneNavRow {
+    kind: "folder" | "scene";
+    id: string;
+    /** 0 = the top level. */
+    depth: number;
+    /** The folder this row sits in, if any. */
+    folder?: string;
+}
+interface SceneFolderLayout {
+    /** Every folder and scene, depth first, in authored order. */
+    rows: SceneNavRow[];
+    /** The scene ids in that order: what the nav, the exports, and the bundle list scenes by. */
+    sceneIds: string[];
+    /** Each folder's effective parent (undefined = top level), after the forgiving rules. */
+    folderParent: Map<string, string | undefined>;
+    /** Each scene's effective folder (undefined = top level). */
+    sceneFolder: Map<string, string | undefined>;
+}
+/**
+ * Lay out the scene list: folders and scenes, nested and ordered. Forgiving, as `sceneOrder` always was:
+ * a scene filed in a missing folder, or a folder with a missing parent, sits at the top level; a loop of
+ * parents is broken at the first folder of it in `sceneFolders`; ids in `sceneOrder` that are neither
+ * are ignored. In each level the rows `sceneOrder` lists come first, in its order, then unlisted scenes in
+ * the order given, then unlisted folders in `sceneFolders` order.
+ */
+declare function sceneFolderLayout(project: Pick<ProjectFile, "sceneOrder" | "sceneFolders" | "sceneFolder">, sceneIds: readonly string[]): SceneFolderLayout;
+/** A scene's folder path for display ("Act 1 / The docks"), or "" at the top level. */
+declare function sceneFolderPath(project: Pick<ProjectFile, "sceneFolders">, layout: Pick<SceneFolderLayout, "folderParent" | "sceneFolder">, sceneId: string): string;
 interface ProjectFile {
     schema: string;
     root?: boolean;
@@ -619,8 +688,17 @@ interface ProjectFile {
     };
     /** The authored scene order (scene ids) for navigation. Scenes not listed follow in file order;
      *  listed ids that no longer exist are ignored. Omitted = plain file order. Presentation only:
-     *  it never affects play, which always starts from `start` / an explicit address. */
+     *  it never affects play, which always starts from `start` / an explicit address.
+     *  Holds scene folder ids too (`sceneFolders`): folders and scenes mix in one order, and Patterpad keeps
+     *  the list equal to the scene list as shown, read top to bottom with every folder open. */
     sceneOrder?: string[];
+    /** Folders for organising the scene list (design/proposals/scene-folders.md). Navigation only, like
+     *  `sceneOrder`: no file moves, nothing reaches the bundle. The list's own order means nothing; where a
+     *  folder is shown comes from `sceneOrder`. Omitted = no folders. */
+    sceneFolders?: SceneFolder[];
+    /** Scene id -> the id of the folder it's filed in. A scene not listed sits at the top level; an entry
+     *  naming a folder that doesn't exist is ignored. A map, so two people filing different scenes merge. */
+    sceneFolder?: Record<string, string>;
     /** Version-control system (spec §12); omitted = unset / none. */
     vcs?: VcsKind;
     /** Project-wide VO mode (spec §16) - one boolean, no per-scene override. */
@@ -704,6 +782,10 @@ interface ProjectFile {
     /** 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;
+    /** How many syllables a second a line with no recording is timed at (`estimateLineDuration`), from 2 to 10.
+     *  Only estimates use it: a line with a recording lasts as long as the recording. Absent =
+     *  `DEFAULT_ESTIMATE_SYLLABLES_PER_SECOND`. */
+    estimateSyllablesPerSecond?: number;
     /** Localise text lines in dialogue scenes (design/proposals/action-text.md). Off (absent) by default: a
      *  dialogue scene's text beats (`isDialogueScene`) are then ACTION, left out of the loc files and the
      *  written word counts, and compiled with `action: true`. On: they're localised and shown as a text
@@ -1120,6 +1202,9 @@ interface Bundle {
     speakerPattern?: string;
     /** The project's own `padAfterDefault`, when it sets one; absent = `DEFAULT_PAD_AFTER`. */
     padAfterDefault?: number;
+    /** The project's own `estimateSyllablesPerSecond`, when it sets one; absent =
+     *  `DEFAULT_ESTIMATE_SYLLABLES_PER_SECOND`. */
+    estimateSyllablesPerSecond?: 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. */
@@ -1235,6 +1320,8 @@ interface SavedChoice {
 /** The flow's execution position: where it is, and what it is waiting on. */
 interface FlowCursor {
     flowEnded: boolean;
+    /** The choice group whose running dry ended the flow (its `end` step's reason "ran-dry"). Present only then. */
+    ranDry?: string;
     currentSceneId: string | null;
     /** The continuation stack (call frames + the active block run), root first. */
     stack: StackFrame[];
@@ -1412,4 +1499,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 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 };
+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_ESTIMATE_SYLLABLES_PER_SECOND, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_SPEAKER_PATTERN, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, ESTIMATE_SYLLABLES_PER_SECOND_MAX, ESTIMATE_SYLLABLES_PER_SECOND_MIN, 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_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, SPEECH_DIGIT_WEIGHT, SPEECH_KANJI_WEIGHT, SPEECH_PAUSE_LONG_WEIGHT, SPEECH_PAUSE_SHORT_WEIGHT, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV3, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type SceneFolder, type SceneFolderLayout, type SceneNavRow, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type SpeechUnit, type SpeechUnitKind, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, UNRESOLVED_KEY, type VcsKind, type WritingStatusDecl, castStringKey, countSyllables, deriveRecordingFolders, effectiveGameId, estimateLineDuration, formatSpeakerLabel, isContentlessBeat, isDialogueScene, projectLayout, projectQualifiers, qualifierStringKey, resolveSceneRef, sceneAddressIndex, sceneFolderLayout, sceneFolderPath, speakerLabelKey, speechUnits, textIsAction, usedQualifiers, usedSpeakerPairs, walkNodes };