@patterkit/model 0.18.0 → 0.19.0

package/dist/index.cjs

@@ -64,6 +64,8 @@ __export(index_exports, {
   projectQualifiers: () => projectQualifiers,
   propertyNameify: () => import_expr.propertyNameify,
   qualifierStringKey: () => qualifierStringKey,
+  resolveSceneRef: () => resolveSceneRef,
+  sceneAddressIndex: () => sceneAddressIndex,
   speakerLabelKey: () => speakerLabelKey,
   textIsAction: () => textIsAction,
   usedQualifiers: () => usedQualifiers,
@@ -96,6 +98,14 @@ function effectiveGameId(entity) {
   const g = entity.gameId?.trim();
   return g ? g : gameIdify(entity.name);
 }
+function sceneAddressIndex(scenes) {
+  const byAddress = /* @__PURE__ */ new Map();
+  for (const [id, scene] of Object.entries(scenes)) byAddress.set(effectiveGameId(scene), id);
+  return byAddress;
+}
+function resolveSceneRef(scenes, ref, byAddress) {
+  return (byAddress ?? sceneAddressIndex(scenes)).get(ref) ?? (Object.hasOwn(scenes, ref) ? ref : void 0);
+}
 var COMMON_GENDERS = ["male", "female", "neuter"];
 var DEFAULT_QUALIFIERS = [
   { gameId: "vo", name: "V.O.", description: "Voice-over: the character isn't in the scene (a thought, narration, a voice in the ear)." },
@@ -288,6 +298,8 @@ var UNRESOLVED_KEY = "unresolved";
   projectQualifiers,
   propertyNameify,
   qualifierStringKey,
+  resolveSceneRef,
+  sceneAddressIndex,
   speakerLabelKey,
   textIsAction,
   usedQualifiers,

package/dist/index.d.cts

@@ -257,6 +257,25 @@ declare function effectiveGameId(entity: {
     gameId?: string;
     name: string;
 }): string;
+/** A bundle's scenes by their address (effective gameId), for `resolveSceneRef` to look up in. */
+declare function sceneAddressIndex(scenes: Readonly<Record<string, {
+    gameId?: string;
+    name: string;
+}>>): Map<string, string>;
+/**
+ * THE rule for resolving a scene reference to its internal id: its address (the effective gameId, the
+ * host-facing name, spec §6) first, then its internal id. Undefined when neither names a scene.
+ *
+ * One rule for the runtime's openFlow, goto and every engine lookup, and for every tool that has to land
+ * where the game will (the Storylet Engine's Board and pairing check, Patterpad's Show Card). Each used to
+ * keep a copy, and the copies tried the internal id first, so where one scene's id was another's gameId
+ * they picked a different scene from the one the game opened (family parity item 1). Pass `byAddress`
+ * (from `sceneAddressIndex`) to look up many references in one bundle without rebuilding it.
+ */
+declare function resolveSceneRef(scenes: Readonly<Record<string, {
+    gameId?: string;
+    name: string;
+}>>, ref: string, byAddress?: ReadonlyMap<string, string>): string | undefined;
 type PropertyType = "boolean" | "number" | "string" | "flags" | "enum" | "quality";
 interface PropertyDecl {
     name: string;
@@ -1383,4 +1402,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, 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 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 };

package/dist/index.d.ts

@@ -257,6 +257,25 @@ declare function effectiveGameId(entity: {
     gameId?: string;
     name: string;
 }): string;
+/** A bundle's scenes by their address (effective gameId), for `resolveSceneRef` to look up in. */
+declare function sceneAddressIndex(scenes: Readonly<Record<string, {
+    gameId?: string;
+    name: string;
+}>>): Map<string, string>;
+/**
+ * THE rule for resolving a scene reference to its internal id: its address (the effective gameId, the
+ * host-facing name, spec §6) first, then its internal id. Undefined when neither names a scene.
+ *
+ * One rule for the runtime's openFlow, goto and every engine lookup, and for every tool that has to land
+ * where the game will (the Storylet Engine's Board and pairing check, Patterpad's Show Card). Each used to
+ * keep a copy, and the copies tried the internal id first, so where one scene's id was another's gameId
+ * they picked a different scene from the one the game opened (family parity item 1). Pass `byAddress`
+ * (from `sceneAddressIndex`) to look up many references in one bundle without rebuilding it.
+ */
+declare function resolveSceneRef(scenes: Readonly<Record<string, {
+    gameId?: string;
+    name: string;
+}>>, ref: string, byAddress?: ReadonlyMap<string, string>): string | undefined;
 type PropertyType = "boolean" | "number" | "string" | "flags" | "enum" | "quality";
 interface PropertyDecl {
     name: string;
@@ -1383,4 +1402,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, 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 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 };

package/dist/index.js

@@ -29,6 +29,14 @@ function effectiveGameId(entity) {
   const g = entity.gameId?.trim();
   return g ? g : gameIdify(entity.name);
 }
+function sceneAddressIndex(scenes) {
+  const byAddress = /* @__PURE__ */ new Map();
+  for (const [id, scene] of Object.entries(scenes)) byAddress.set(effectiveGameId(scene), id);
+  return byAddress;
+}
+function resolveSceneRef(scenes, ref, byAddress) {
+  return (byAddress ?? sceneAddressIndex(scenes)).get(ref) ?? (Object.hasOwn(scenes, ref) ? ref : void 0);
+}
 var COMMON_GENDERS = ["male", "female", "neuter"];
 var DEFAULT_QUALIFIERS = [
   { gameId: "vo", name: "V.O.", description: "Voice-over: the character isn't in the scene (a thought, narration, a voice in the ear)." },
@@ -220,6 +228,8 @@ export {
   projectQualifiers,
   propertyNameify,
   qualifierStringKey,
+  resolveSceneRef,
+  sceneAddressIndex,
   speakerLabelKey,
   textIsAction,
   usedQualifiers,

package/package.json

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