@patterkit/model 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -116,7 +116,7 @@ function castStringKey(name) {
 var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
 var SAVE_SCHEMA = "patter/save@0";
-var SAVE_VERSION = 2;
+var SAVE_VERSION = 3;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   COMMON_GENDERS,

package/dist/index.d.cts

@@ -554,6 +554,12 @@ interface ProjectFile {
      *  resolver is bound, and coverage drives their values. Omitted = no host scopes (`@world.x` is then a
      *  compile error). See design/scope-registry.md §6. */
     scopeRegistry?: HostScopeRegistry;
+    /** Where the game's shared scopes folder is, relative to this project file's folder
+     *  (`"../../shared/game-scopes"`), for a folder the walk-up would not find. Omitted = walk up from the
+     *  project to the first `game-scopes/`, stopping at the version-control root; none found = the project
+     *  works alone. A path that doesn't exist is a project error. See the Patter site's World properties
+     *  page and patterkit/design/shared-scopes.md. Editor and compiler only; never reaches the bundle. */
+    gameScopes?: string;
     /** Coverage input drivers (#159): values to feed host scopes (`@world`) during a coverage run so
      *  externally-gated branches get exercised. Authoring-only (never reaches the runtime bundle). */
     coverageDrivers?: CoverageDriver[];
@@ -809,6 +815,10 @@ interface Bundle {
     /** 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. */
     scopeRegistry?: HostScopeRegistry;
+    /** Other engines' game-wide scopes the content names (`story`), sorted: the family's shared vocabulary,
+     *  opaque to the compiler and never self-backed. The engine reports when the game has not registered
+     *  one. Absent when none. */
+    externalScopes?: string[];
     gameDataFields?: GameDataFields;
     scenes: Record<string, CompiledScene>;
     /** locale -> (beatId -> text). In "embedded" localisation this carries every included locale; in "ids"
@@ -847,13 +857,13 @@ 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 = 2;
+declare const SAVE_VERSION = 3;
 /** The tagged envelope a host stores: `serializeState` writes it, `deserializeState` refuses anything else. */
 interface SaveEnvelope {
     schema: typeof SAVE_SCHEMA;
     save: SaveGame;
 }
-/** A property-state snapshot: owned scope -> property name -> value (`{ patter: { gold: 7 } }`). */
+/** A registry's values: registry key -> property name -> value (`{ patter: { gold: 7 } }`). */
 type EngineSave = Record<string, Record<string, ScalarValue>>;
 /** Serialised `sequence` selector visit state for one group (spec §4 / §7). Every key is OPTIONAL and
  *  present only once the selector has used it: `seq` after the first sequential pick, `bag` once a
@@ -911,31 +921,46 @@ interface FlowCursor {
     /** This flow's (non-shared) selector cursors, keyed by group id. */
     selectors: Record<string, SelectorSnapshot>;
 }
-/** The serialised cursor + scopes + PRNG of a single flow. */
+/** The serialised cursor + PRNG + visits of a single flow. Its properties are the registry's. */
 interface FlowSnapshot {
-    /** This flow's owned-scope values = the NOT-shared `@patter` globals, under token "patter". */
-    scopes: EngineSave;
-    /** Per-scene NOT-shared `@scene` bags (scene id -> name -> value); persist across re-entries (spec §7). */
-    sceneBags: Record<string, Record<string, ScalarValue>>;
     /** This flow's built-in PRNG position (mulberry32 state, uint32; older saves may carry it signed). */
     rngState: number;
     /** This flow's per-node entry counts (node id -> times entered by this flow). */
     visits: Record<string, number>;
     cursor: FlowCursor;
 }
-/** A full resumable save-game: shared `@patter` state + every live flow. */
+/** A full resumable save-game (version 3): everything that is not a property, plus the registry's
+ *  values when the engine made its own registry. */
 interface SaveGame {
-    version: number;
-    /** Shared `@patter` globals (owned scope "patter"). */
-    shared: EngineSave;
+    version: 3;
+    /** 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;
     /** World-wide per-node entry counts (node id -> times entered by any flow). */
     sharedVisits: Record<string, number>;
     /** Shared selector cursors (node id -> snapshot) for `shared` memoried selectors. */
     sharedSelectors: Record<string, SelectorSnapshot>;
-    /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value) - the shared scene props. */
-    stageBags: Record<string, Record<string, ScalarValue>>;
     /** Each live flow's snapshot, keyed by flow id. */
     flows: Record<string, FlowSnapshot>;
 }
+/** A version 2 flow snapshot, which carried the flow's property values itself. Still read. */
+interface FlowSnapshotV2 extends FlowSnapshot {
+    /** 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 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>;
+}
 
-export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, type SaveEnvelope, type SaveGame, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type StackFrame, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };
+export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, 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 StackFrame, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };

package/dist/index.d.ts

@@ -554,6 +554,12 @@ interface ProjectFile {
      *  resolver is bound, and coverage drives their values. Omitted = no host scopes (`@world.x` is then a
      *  compile error). See design/scope-registry.md §6. */
     scopeRegistry?: HostScopeRegistry;
+    /** Where the game's shared scopes folder is, relative to this project file's folder
+     *  (`"../../shared/game-scopes"`), for a folder the walk-up would not find. Omitted = walk up from the
+     *  project to the first `game-scopes/`, stopping at the version-control root; none found = the project
+     *  works alone. A path that doesn't exist is a project error. See the Patter site's World properties
+     *  page and patterkit/design/shared-scopes.md. Editor and compiler only; never reaches the bundle. */
+    gameScopes?: string;
     /** Coverage input drivers (#159): values to feed host scopes (`@world`) during a coverage run so
      *  externally-gated branches get exercised. Authoring-only (never reaches the runtime bundle). */
     coverageDrivers?: CoverageDriver[];
@@ -809,6 +815,10 @@ interface Bundle {
     /** 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. */
     scopeRegistry?: HostScopeRegistry;
+    /** Other engines' game-wide scopes the content names (`story`), sorted: the family's shared vocabulary,
+     *  opaque to the compiler and never self-backed. The engine reports when the game has not registered
+     *  one. Absent when none. */
+    externalScopes?: string[];
     gameDataFields?: GameDataFields;
     scenes: Record<string, CompiledScene>;
     /** locale -> (beatId -> text). In "embedded" localisation this carries every included locale; in "ids"
@@ -847,13 +857,13 @@ 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 = 2;
+declare const SAVE_VERSION = 3;
 /** The tagged envelope a host stores: `serializeState` writes it, `deserializeState` refuses anything else. */
 interface SaveEnvelope {
     schema: typeof SAVE_SCHEMA;
     save: SaveGame;
 }
-/** A property-state snapshot: owned scope -> property name -> value (`{ patter: { gold: 7 } }`). */
+/** A registry's values: registry key -> property name -> value (`{ patter: { gold: 7 } }`). */
 type EngineSave = Record<string, Record<string, ScalarValue>>;
 /** Serialised `sequence` selector visit state for one group (spec §4 / §7). Every key is OPTIONAL and
  *  present only once the selector has used it: `seq` after the first sequential pick, `bag` once a
@@ -911,31 +921,46 @@ interface FlowCursor {
     /** This flow's (non-shared) selector cursors, keyed by group id. */
     selectors: Record<string, SelectorSnapshot>;
 }
-/** The serialised cursor + scopes + PRNG of a single flow. */
+/** The serialised cursor + PRNG + visits of a single flow. Its properties are the registry's. */
 interface FlowSnapshot {
-    /** This flow's owned-scope values = the NOT-shared `@patter` globals, under token "patter". */
-    scopes: EngineSave;
-    /** Per-scene NOT-shared `@scene` bags (scene id -> name -> value); persist across re-entries (spec §7). */
-    sceneBags: Record<string, Record<string, ScalarValue>>;
     /** This flow's built-in PRNG position (mulberry32 state, uint32; older saves may carry it signed). */
     rngState: number;
     /** This flow's per-node entry counts (node id -> times entered by this flow). */
     visits: Record<string, number>;
     cursor: FlowCursor;
 }
-/** A full resumable save-game: shared `@patter` state + every live flow. */
+/** A full resumable save-game (version 3): everything that is not a property, plus the registry's
+ *  values when the engine made its own registry. */
 interface SaveGame {
-    version: number;
-    /** Shared `@patter` globals (owned scope "patter"). */
-    shared: EngineSave;
+    version: 3;
+    /** 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;
     /** World-wide per-node entry counts (node id -> times entered by any flow). */
     sharedVisits: Record<string, number>;
     /** Shared selector cursors (node id -> snapshot) for `shared` memoried selectors. */
     sharedSelectors: Record<string, SelectorSnapshot>;
-    /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value) - the shared scene props. */
-    stageBags: Record<string, Record<string, ScalarValue>>;
     /** Each live flow's snapshot, keyed by flow id. */
     flows: Record<string, FlowSnapshot>;
 }
+/** A version 2 flow snapshot, which carried the flow's property values itself. Still read. */
+interface FlowSnapshotV2 extends FlowSnapshot {
+    /** 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 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>;
+}
 
-export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, type SaveEnvelope, type SaveGame, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type StackFrame, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };
+export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, 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 StackFrame, type Suggestion, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };

package/dist/index.js

@@ -76,7 +76,7 @@ function castStringKey(name) {
 var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
 var SAVE_SCHEMA = "patter/save@0";
-var SAVE_VERSION = 2;
+var SAVE_VERSION = 3;
 export {
   COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER,

package/package.json

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