@patterkit/model 0.22.0 → 0.23.0

package/dist/index.cjs

@@ -70,6 +70,8 @@ __export(index_exports, {
   qualifierStringKey: () => qualifierStringKey,
   resolveSceneRef: () => resolveSceneRef,
   sceneAddressIndex: () => sceneAddressIndex,
+  sceneFolderLayout: () => sceneFolderLayout,
+  sceneFolderPath: () => sceneFolderPath,
   speakerLabelKey: () => speakerLabelKey,
   textIsAction: () => textIsAction,
   usedQualifiers: () => usedQualifiers,
@@ -225,6 +227,60 @@ var DEFAULT_DOCUMENTATION_CLASSES = [
   { name: "editor", deliver: ["editor"] }
   // the editable script handed to an outside editor
 ];
+function sceneFolderLayout(project, sceneIds) {
+  const folders = project.sceneFolders ?? [];
+  const known = new Set(folders.map((f) => f.id));
+  const folderParent = /* @__PURE__ */ new Map();
+  for (const f of folders) folderParent.set(f.id, f.parent !== void 0 && known.has(f.parent) && f.parent !== f.id ? f.parent : void 0);
+  for (const f of folders) {
+    let at = folderParent.get(f.id);
+    for (let steps = 0; at !== void 0 && steps <= folders.length; steps++) {
+      if (at === f.id) {
+        folderParent.set(f.id, void 0);
+        break;
+      }
+      at = folderParent.get(at);
+    }
+  }
+  const sceneFolder = /* @__PURE__ */ new Map();
+  for (const id of sceneIds) {
+    const f = project.sceneFolder?.[id];
+    sceneFolder.set(id, f !== void 0 && known.has(f) ? f : void 0);
+  }
+  const rank = new Map((project.sceneOrder ?? []).map((id, i) => [id, i]));
+  const children = /* @__PURE__ */ new Map();
+  const add = (parent, kind, id, tie) => {
+    const list = children.get(parent) ?? [];
+    list.push({ kind, id, tie });
+    children.set(parent, list);
+  };
+  sceneIds.forEach((id, i) => add(sceneFolder.get(id), "scene", id, i));
+  folders.forEach((f, i) => add(folderParent.get(f.id), "folder", f.id, sceneIds.length + i));
+  const rows = [];
+  const out = [];
+  const walk = (parent, depth) => {
+    const list = (children.get(parent) ?? []).slice().sort((a, b) => {
+      const ra = rank.get(a.id), rb = rank.get(b.id);
+      if (ra !== void 0 && rb !== void 0) return ra - rb;
+      if (ra !== void 0) return -1;
+      if (rb !== void 0) return 1;
+      return a.tie - b.tie;
+    });
+    for (const c of list) {
+      rows.push({ kind: c.kind, id: c.id, depth, ...parent !== void 0 ? { folder: parent } : {} });
+      if (c.kind === "scene") out.push(c.id);
+      else walk(c.id, depth + 1);
+    }
+  };
+  walk(void 0, 0);
+  return { rows, sceneIds: out, folderParent, sceneFolder };
+}
+function sceneFolderPath(project, layout, sceneId) {
+  const names = new Map((project.sceneFolders ?? []).map((f) => [f.id, f.name]));
+  const parts = [];
+  for (let at = layout.sceneFolder.get(sceneId), n = 0; at !== void 0 && n <= names.size; at = layout.folderParent.get(at), n++) parts.unshift(names.get(at) ?? "");
+  return parts.join(" / ");
+}
 var PROJECT_LOCALE_SCENE = "@project";
 function castStringKey(name) {
   return `cast:${name}`;
@@ -311,6 +367,8 @@ var UNRESOLVED_KEY = "unresolved";
   qualifierStringKey,
   resolveSceneRef,
   sceneAddressIndex,
+  sceneFolderLayout,
+  sceneFolderPath,
   speakerLabelKey,
   textIsAction,
   usedQualifiers,

package/dist/index.d.cts

@@ -599,6 +599,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 +656,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. */
@@ -1235,6 +1281,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 +1460,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_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 SceneFolder, type SceneFolderLayout, type SceneNavRow, 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, sceneFolderLayout, sceneFolderPath, speakerLabelKey, textIsAction, usedQualifiers, usedSpeakerPairs, walkNodes };

package/dist/index.d.ts

@@ -599,6 +599,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 +656,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. */
@@ -1235,6 +1281,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 +1460,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_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 SceneFolder, type SceneFolderLayout, type SceneNavRow, 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, sceneFolderLayout, sceneFolderPath, speakerLabelKey, textIsAction, usedQualifiers, usedSpeakerPairs, walkNodes };

package/dist/index.js

@@ -152,6 +152,60 @@ var DEFAULT_DOCUMENTATION_CLASSES = [
   { name: "editor", deliver: ["editor"] }
   // the editable script handed to an outside editor
 ];
+function sceneFolderLayout(project, sceneIds) {
+  const folders = project.sceneFolders ?? [];
+  const known = new Set(folders.map((f) => f.id));
+  const folderParent = /* @__PURE__ */ new Map();
+  for (const f of folders) folderParent.set(f.id, f.parent !== void 0 && known.has(f.parent) && f.parent !== f.id ? f.parent : void 0);
+  for (const f of folders) {
+    let at = folderParent.get(f.id);
+    for (let steps = 0; at !== void 0 && steps <= folders.length; steps++) {
+      if (at === f.id) {
+        folderParent.set(f.id, void 0);
+        break;
+      }
+      at = folderParent.get(at);
+    }
+  }
+  const sceneFolder = /* @__PURE__ */ new Map();
+  for (const id of sceneIds) {
+    const f = project.sceneFolder?.[id];
+    sceneFolder.set(id, f !== void 0 && known.has(f) ? f : void 0);
+  }
+  const rank = new Map((project.sceneOrder ?? []).map((id, i) => [id, i]));
+  const children = /* @__PURE__ */ new Map();
+  const add = (parent, kind, id, tie) => {
+    const list = children.get(parent) ?? [];
+    list.push({ kind, id, tie });
+    children.set(parent, list);
+  };
+  sceneIds.forEach((id, i) => add(sceneFolder.get(id), "scene", id, i));
+  folders.forEach((f, i) => add(folderParent.get(f.id), "folder", f.id, sceneIds.length + i));
+  const rows = [];
+  const out = [];
+  const walk = (parent, depth) => {
+    const list = (children.get(parent) ?? []).slice().sort((a, b) => {
+      const ra = rank.get(a.id), rb = rank.get(b.id);
+      if (ra !== void 0 && rb !== void 0) return ra - rb;
+      if (ra !== void 0) return -1;
+      if (rb !== void 0) return 1;
+      return a.tie - b.tie;
+    });
+    for (const c of list) {
+      rows.push({ kind: c.kind, id: c.id, depth, ...parent !== void 0 ? { folder: parent } : {} });
+      if (c.kind === "scene") out.push(c.id);
+      else walk(c.id, depth + 1);
+    }
+  };
+  walk(void 0, 0);
+  return { rows, sceneIds: out, folderParent, sceneFolder };
+}
+function sceneFolderPath(project, layout, sceneId) {
+  const names = new Map((project.sceneFolders ?? []).map((f) => [f.id, f.name]));
+  const parts = [];
+  for (let at = layout.sceneFolder.get(sceneId), n = 0; at !== void 0 && n <= names.size; at = layout.folderParent.get(at), n++) parts.unshift(names.get(at) ?? "");
+  return parts.join(" / ");
+}
 var PROJECT_LOCALE_SCENE = "@project";
 function castStringKey(name) {
   return `cast:${name}`;
@@ -237,6 +291,8 @@ export {
   qualifierStringKey,
   resolveSceneRef,
   sceneAddressIndex,
+  sceneFolderLayout,
+  sceneFolderPath,
   speakerLabelKey,
   textIsAction,
   usedQualifiers,

package/package.json

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