@storylet-studio/model 0.4.1 → 0.6.0

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   RESERVED_PROPERTY_NAMES: () => import_expr.RESERVED_PROPERTY_NAMES,
   SAVEFILE_SCHEMA: () => SAVEFILE_SCHEMA,
   SAVE_SCHEMA: () => SAVE_SCHEMA,
+  SAVE_SCHEMA_V1: () => SAVE_SCHEMA_V1,
   SHARD_EXTENSIONS: () => SHARD_EXTENSIONS,
   SPATIAL: () => SPATIAL,
   TAGS_SCHEMA: () => TAGS_SCHEMA,
@@ -552,7 +553,8 @@ var parseHoleRef = (value) => {
 };
 var BUNDLE_SCHEMA = "storylets/bundle@0";
 var DEFAULT_PLAY_RUNG = "solo";
-var SAVE_SCHEMA = "storylets/save@1";
+var SAVE_SCHEMA = "storylets/save@2";
+var SAVE_SCHEMA_V1 = "storylets/save@1";
 var SAVEFILE_SCHEMA = "storylets/savefile@1";
 var PROJECT_FOLDER_EXTENSION = ".storylets";
 var BUNDLE_EXTENSION = ".storyletsc";
@@ -626,6 +628,7 @@ var FURNITURE_COLOURS = ["paper", "amber", "sage", "sky", "rose", "slate"];
   RESERVED_PROPERTY_NAMES,
   SAVEFILE_SCHEMA,
   SAVE_SCHEMA,
+  SAVE_SCHEMA_V1,
   SHARD_EXTENSIONS,
   SPATIAL,
   TAGS_SCHEMA,

package/dist/index.d.cts

@@ -976,8 +976,14 @@ interface Bundle {
     boxes: Box<Expression>[];
     /** Maps, when the project asked for them. Absent is the normal state. */
     maps?: BundleMap[];
+    /** Other engines' game-wide scopes the content names (`patter`), sorted: the
+     *  family's shared vocabulary, let through unchecked by the compiler. The
+     *  engine reports when the game has not registered one. Absent when none. */
+    externalScopes?: string[];
 }
-declare const SAVE_SCHEMA = "storylets/save@1";
+declare const SAVE_SCHEMA = "storylets/save@2";
+/** The version 1 envelope's schema tag, still read. */
+declare const SAVE_SCHEMA_V1 = "storylets/save@1";
 interface PlayRecord {
     /** Card and outcome by gameId (feeds the play-history functions). */
     card: string;
@@ -1002,10 +1008,13 @@ interface PropsPartition {
     /** Tag state, keyed by tag id. */
     value: Record<string, PropertyBag>;
 }
-/** One flow's snapshot inside the envelope (schema 4). */
+/** One flow's snapshot inside the envelope (schema 4), and the blob
+ *  `saveFlow` parks. */
 interface FlowSave {
-    /** The per-flow property partitions. */
-    props: PropsPartition;
+    /** The per-flow property partitions. Carried by `saveFlow`, which parks one
+     *  flow whole; absent from a version 2 envelope's flows, whose properties
+     *  are the registry's. Present in every flow of a version 1 envelope. */
+    props?: PropsPartition;
     /** Per-box turn counters, keyed by box id (schema 3.4) - per flow: there
      *  is deliberately no global turn. */
     turns: Record<string, number>;
@@ -1028,16 +1037,33 @@ interface FlowSave {
  *  (design/shared-scarcity.md). Claims are NOT here: they are derived from the
  *  live boards, and each flow's board rides its own blob. */
 interface SharedSave {
-    props: PropsPartition;
+    /** The shared property partitions: version 1 only. */
+    props?: PropsPartition;
     /** Card ids, sorted, so a save is byte-stable for a diff. */
     spent: string[];
 }
 interface SaveEnvelope {
     schema: typeof SAVE_SCHEMA;
     content: BundleContent;
+    /** 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 envelope. */
+    registry?: Record<string, PropertyBag>;
     shared: SharedSave;
     flows: Record<string, FlowSave>;
 }
+/** A version 1 envelope, from before the registry held the properties. Every
+ *  runtime still reads it: its partitions move into the registry as it loads. */
+interface SaveEnvelopeV1 {
+    schema: typeof SAVE_SCHEMA_V1;
+    content: BundleContent;
+    shared: SharedSave & {
+        props: PropsPartition;
+    };
+    flows: Record<string, FlowSave & {
+        props: PropsPartition;
+    }>;
+}
 /** One card that a restore refused to put back on the board.
  *
  *  `vanished` and `hand-vanished` are the edit's doing (the card, or the hand
@@ -1115,7 +1141,8 @@ interface LoadReport {
 declare const SAVEFILE_SCHEMA = "storylets/savefile@1";
 interface SaveFile {
     schema: typeof SAVEFILE_SCHEMA;
-    engine: SaveEnvelope;
+    /** The engine's envelope: version 2 when written today, version 1 still read. */
+    engine: SaveEnvelope | SaveEnvelopeV1;
     /** The host's @world values, saved and restored by the host. */
     world?: PropertyBag;
 }
@@ -1410,6 +1437,14 @@ interface ProjectShard {
          *  on state nothing writes) always warns, because that kills cards now. */
         warnUnreadWrites?: boolean;
     };
+    /**
+     * Where the game's shared scopes folder is, relative to the folder holding this file
+     * (`"../../shared/game-scopes"`). Authoring config, never compiled, and usually absent: the
+     * tools find a `game-scopes/` folder by walking up from the project on their own, stopping at
+     * the version-control root, so this is only for a folder that walk would not reach. A path
+     * that doesn't exist is a project error. (patterkit design/shared-scopes.md.)
+     */
+    gameScopes?: string;
     world: {
         properties: PropertyDecl[];
         registry?: unknown;
@@ -1508,4 +1543,4 @@ interface DeckShard {
     cards: Card<string>[];
 }
 
-export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, CONTRACTS_DIR, CONTRACT_SCHEMA, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type ContractProperty, type ContractShard, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, DEFAULT_PLAY_RUNG, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, type HoleRef, type HoleRefScope, type LoadEviction, type LoadProperty, type LoadReport, MAP_SCHEMA, type MapShard, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type PlayRung, type Polygon, type ProjectSettings, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ValueAddresses, type ViewPoint, type ViewShard, ambiguousValueAddressMessage, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, contractPropertyPath, contractPropertyType, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isHoleRef, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, parseHoleRef, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, turnSpan, unbindHand, valueAddresses, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };
+export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, CONTRACTS_DIR, CONTRACT_SCHEMA, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type ContractProperty, type ContractShard, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, DEFAULT_PLAY_RUNG, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, type HoleRef, type HoleRefScope, type LoadEviction, type LoadProperty, type LoadReport, MAP_SCHEMA, type MapShard, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type PlayRung, type Polygon, type ProjectSettings, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SAVE_SCHEMA_V1, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveEnvelopeV1, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ValueAddresses, type ViewPoint, type ViewShard, ambiguousValueAddressMessage, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, contractPropertyPath, contractPropertyType, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isHoleRef, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, parseHoleRef, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, turnSpan, unbindHand, valueAddresses, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };

package/dist/index.d.ts

@@ -976,8 +976,14 @@ interface Bundle {
     boxes: Box<Expression>[];
     /** Maps, when the project asked for them. Absent is the normal state. */
     maps?: BundleMap[];
+    /** Other engines' game-wide scopes the content names (`patter`), sorted: the
+     *  family's shared vocabulary, let through unchecked by the compiler. The
+     *  engine reports when the game has not registered one. Absent when none. */
+    externalScopes?: string[];
 }
-declare const SAVE_SCHEMA = "storylets/save@1";
+declare const SAVE_SCHEMA = "storylets/save@2";
+/** The version 1 envelope's schema tag, still read. */
+declare const SAVE_SCHEMA_V1 = "storylets/save@1";
 interface PlayRecord {
     /** Card and outcome by gameId (feeds the play-history functions). */
     card: string;
@@ -1002,10 +1008,13 @@ interface PropsPartition {
     /** Tag state, keyed by tag id. */
     value: Record<string, PropertyBag>;
 }
-/** One flow's snapshot inside the envelope (schema 4). */
+/** One flow's snapshot inside the envelope (schema 4), and the blob
+ *  `saveFlow` parks. */
 interface FlowSave {
-    /** The per-flow property partitions. */
-    props: PropsPartition;
+    /** The per-flow property partitions. Carried by `saveFlow`, which parks one
+     *  flow whole; absent from a version 2 envelope's flows, whose properties
+     *  are the registry's. Present in every flow of a version 1 envelope. */
+    props?: PropsPartition;
     /** Per-box turn counters, keyed by box id (schema 3.4) - per flow: there
      *  is deliberately no global turn. */
     turns: Record<string, number>;
@@ -1028,16 +1037,33 @@ interface FlowSave {
  *  (design/shared-scarcity.md). Claims are NOT here: they are derived from the
  *  live boards, and each flow's board rides its own blob. */
 interface SharedSave {
-    props: PropsPartition;
+    /** The shared property partitions: version 1 only. */
+    props?: PropsPartition;
     /** Card ids, sorted, so a save is byte-stable for a diff. */
     spent: string[];
 }
 interface SaveEnvelope {
     schema: typeof SAVE_SCHEMA;
     content: BundleContent;
+    /** 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 envelope. */
+    registry?: Record<string, PropertyBag>;
     shared: SharedSave;
     flows: Record<string, FlowSave>;
 }
+/** A version 1 envelope, from before the registry held the properties. Every
+ *  runtime still reads it: its partitions move into the registry as it loads. */
+interface SaveEnvelopeV1 {
+    schema: typeof SAVE_SCHEMA_V1;
+    content: BundleContent;
+    shared: SharedSave & {
+        props: PropsPartition;
+    };
+    flows: Record<string, FlowSave & {
+        props: PropsPartition;
+    }>;
+}
 /** One card that a restore refused to put back on the board.
  *
  *  `vanished` and `hand-vanished` are the edit's doing (the card, or the hand
@@ -1115,7 +1141,8 @@ interface LoadReport {
 declare const SAVEFILE_SCHEMA = "storylets/savefile@1";
 interface SaveFile {
     schema: typeof SAVEFILE_SCHEMA;
-    engine: SaveEnvelope;
+    /** The engine's envelope: version 2 when written today, version 1 still read. */
+    engine: SaveEnvelope | SaveEnvelopeV1;
     /** The host's @world values, saved and restored by the host. */
     world?: PropertyBag;
 }
@@ -1410,6 +1437,14 @@ interface ProjectShard {
          *  on state nothing writes) always warns, because that kills cards now. */
         warnUnreadWrites?: boolean;
     };
+    /**
+     * Where the game's shared scopes folder is, relative to the folder holding this file
+     * (`"../../shared/game-scopes"`). Authoring config, never compiled, and usually absent: the
+     * tools find a `game-scopes/` folder by walking up from the project on their own, stopping at
+     * the version-control root, so this is only for a folder that walk would not reach. A path
+     * that doesn't exist is a project error. (patterkit design/shared-scopes.md.)
+     */
+    gameScopes?: string;
     world: {
         properties: PropertyDecl[];
         registry?: unknown;
@@ -1508,4 +1543,4 @@ interface DeckShard {
     cards: Card<string>[];
 }
 
-export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, CONTRACTS_DIR, CONTRACT_SCHEMA, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type ContractProperty, type ContractShard, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, DEFAULT_PLAY_RUNG, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, type HoleRef, type HoleRefScope, type LoadEviction, type LoadProperty, type LoadReport, MAP_SCHEMA, type MapShard, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type PlayRung, type Polygon, type ProjectSettings, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ValueAddresses, type ViewPoint, type ViewShard, ambiguousValueAddressMessage, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, contractPropertyPath, contractPropertyType, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isHoleRef, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, parseHoleRef, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, turnSpan, unbindHand, valueAddresses, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };
+export { BOX_SCHEMA, BUNDLE_EXTENSION, BUNDLE_SCHEMA, type Box, type BoxMap, type BoxShard, type Bundle, type BundleBackground, type BundleContent, type BundleMap, type BundleSettings, CONTRACTS_DIR, CONTRACT_SCHEMA, type CanvasFurniture, type Card, type Comment, type CommentMark, type CommentMessage, type ContractProperty, type ContractShard, type CoverageConfig, type CoverageDriver, DECK_SCHEMA, DEFAULT_PLAY_RUNG, type Deck, type DeckCanvas, type DeckShard, FURNITURE_COLOURS, type FieldDecl, type FlowSave, type Frame, type FurnitureColour, HANDS_SCHEMA, type Hand, type HandBinding, type HandRule, type HandTemplate, type HandsShard, type HoleRef, type HoleRefScope, type LoadEviction, type LoadProperty, type LoadReport, MAP_SCHEMA, type MapShard, NOTES_SCHEMA, type NotesShard, type Outcome, PLACE_GROUP, PROJECT_FOLDER_EXTENSION, PROJECT_SCHEMA, type PlayRecord, type PlayRung, type Polygon, type ProjectSettings, type ProjectShard, type PropertyBag, type PropertyDecl, type PropertyType, type PropsPartition, type Rect, type RedrawPolicy, SAVEFILE_SCHEMA, SAVE_SCHEMA, SAVE_SCHEMA_V1, SHARD_EXTENSIONS, SPATIAL, type SaveEnvelope, type SaveEnvelopeV1, type SaveFile, type SharedSave, type SpatialBackground, type SpatialGroup, type StackMove, type Stacked, TAGS_SCHEMA, type Tag, type TagGroup, type TagsShard, VIEW_SCHEMA, type ValueAddresses, type ViewPoint, type ViewShard, ambiguousValueAddressMessage, backgroundsOf, bindHand, bundleAssetPath, byDisplayOrder, centroid, commentsOf, contractPropertyPath, contractPropertyType, droppedRect, effectiveGameId, framesOf, freeGameId, freeTitle, gameIdify, handBinding, inferDeclFromWrite, isHoleRef, isSpatial, isValidGameId, labelPoint, markOf, marksOn, openThreadCounts, parseHoleRef, pointInPolygon, polygonBounds, polygonOf, restack, spatialOf, stacked, threadsFor, turnSpan, unbindHand, valueAddresses, withBackgrounds, withPolygon, withSpatialGroup, withZ, zOf, zoneAt, zonesAt };

package/dist/index.js

@@ -468,7 +468,8 @@ var parseHoleRef = (value) => {
 };
 var BUNDLE_SCHEMA = "storylets/bundle@0";
 var DEFAULT_PLAY_RUNG = "solo";
-var SAVE_SCHEMA = "storylets/save@1";
+var SAVE_SCHEMA = "storylets/save@2";
+var SAVE_SCHEMA_V1 = "storylets/save@1";
 var SAVEFILE_SCHEMA = "storylets/savefile@1";
 var PROJECT_FOLDER_EXTENSION = ".storylets";
 var BUNDLE_EXTENSION = ".storyletsc";
@@ -541,6 +542,7 @@ export {
   RESERVED_PROPERTY_NAMES,
   SAVEFILE_SCHEMA,
   SAVE_SCHEMA,
+  SAVE_SCHEMA_V1,
   SHARD_EXTENSIONS,
   SPATIAL,
   TAGS_SCHEMA,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storylet-studio/model",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Storylets data-model types: source shards (project / box / tags / hands / deck), the compiled bundle, the save envelope. The shape source-of-truth.",
   "type": "module",
   "license": "MIT",