@storylet-studio/runtime 0.8.1 → 0.9.0

package/dist/index.d.cts

@@ -265,6 +265,7 @@ interface OwnerIndex {
     gameId: Map<string, string>;
     id: Map<string, string>;
     repeated: Map<string, string[]>;
+    zoneQualified: Map<string, string>;
 }
 type OwnerIndexes = Record<OwnedScope, OwnerIndex>;
 /** One side's five stores (shared on the engine, per-flow on each flow). */
@@ -297,9 +298,11 @@ interface Internals {
     /** The owner segment of a property address, both ways round (4.4). */
     owners: OwnerIndexes;
     templatesById: Map<string, HandTemplate<Expression>>;
+    /** Every group by internal id. `box` is absent for the project map's group,
+     *  which belongs to no box. */
     groupsById: Map<string, {
         group: TagGroup;
-        box: Box<Expression>;
+        box?: Box<Expression>;
     }>;
     requiredGroups: Set<string>;
     nodeCache: WeakMap<Expression, ExprNode>;
@@ -507,6 +510,20 @@ declare class Engine {
      *  `registry`, self-backed @world included; a game that passed a registry
      *  saves it once itself, beside each engine's envelope. */
     saveGame(): SaveEnvelope;
+    /** The registry's values in CANONICAL order, the order a load rebuilds them
+     *  in: the engine-wide keys as the constructor registered them, then each
+     *  flow's keys in `flows()` order (each flow's own registration order), then
+     *  anything else the registry holds (values still waiting for a key), as the
+     *  registry lists it. The registry itself lists keys in registration order,
+     *  and a flow replaced in place (`open()` above keeps its slot in
+     *  `flowsById`) re-registers its keys at the END, so `openFlow("a");
+     *  openFlow("b"); openFlow("a")` saved b's keys before a's while a load
+     *  rebuilt a's first: the same run, different `.storyletsave` bytes, and a
+     *  save loaded and saved again no longer equal to itself. It is the
+     *  2026-08-29 rule carried into the section save@2 moved the per-flow values
+     *  to (2026-10-01). Order does not matter on READ (`partitionsFromSections`
+     *  sorts by key shape), so a save written in the old order loads as before. */
+    private registrySection;
     /** ONE flow's blob, to park a visit that is walking away: the same shape
      *  the envelope carries per flow, and the same shape `openFlow`'s `restore`
      *  option takes back (design/engine-server.md 4.1). Saving the whole
@@ -618,7 +635,13 @@ declare class Flow {
     /** Tag group names are box-scoped: two boxes may name a group the same way
      *  (schema 1 - boxes namespace their groups), so a name is only ever
      *  resolved inside the box being asked, never bundle-wide. Ids are
-     *  project-unique and accepted here too, still confined to the box. */
+     *  project-unique and accepted here too, still confined to the box.
+     *
+     *  A box on the project map sees ONE namespace: its own groups, then the
+     *  map's group (design/project-map-contract.md 3.1). A box that has not
+     *  opted in does not see the map's name at all, so a peek naming it there
+     *  is the ordinary unknown-group refusal. Own groups first is stated for
+     *  determinism only: a bundle that loads never has the two share a name. */
     private groupInBox;
     /** Fold one play into the indexes. O(the card's tags), not O(the log). */
     private indexPlay;
@@ -626,8 +649,10 @@ declare class Flow {
      *  rather than appended to, which is `restore` alone. */
     private rebuildPlayIndex;
     /** `box` is the box whose ask is being evaluated: the play-history
-     *  functions take a bare group name, so it resolves there (a card's tags
-     *  reference its own box's group, which keeps the counts box-local).
+     *  functions take a bare group name, so it resolves there, and they count
+     *  only that box's own plays (the box is in the index key). That was
+     *  automatic while every group was a box's; a project-map zone is shared,
+     *  and its history is still not (design/project-map-contract.md 3.7, D7).
      *  History is THIS flow's: countPlayed answers "have I done this". */
     /** One host per box, built once.
      *
@@ -816,7 +841,8 @@ declare class Flow {
 
 /** What bundle this is: the staleness/identity triple plus the schema tag. */
 interface BundleIdentity {
-    /** The bundle schema tag ("storylets/bundle@0"). */
+    /** The bundle schema tag ("storylets/bundle@1", or "@0" from before the
+     *  project map). */
     schema: string;
     /** content.project - the project name a save must agree with. */
     project: string;
@@ -866,6 +892,10 @@ interface TagGroupSummary {
 interface BoxSummary {
     gameId: string;
     title?: string;
+    /** The box is on the project map (design/project-map-contract.md 3.7): it
+     *  may name the map's group in peek criteria beside its own `tagGroups`,
+     *  which list the box's OWN groups only. Absent is "not on the map". */
+    usesMap?: true;
     /** The only per-box ranking policy (Reboot 2.2). */
     ranking: {
         specificity: boolean;
@@ -911,7 +941,8 @@ interface PropertySummary {
 type PropertyScopeKind = "world" | "story" | "box" | "deck" | "hand" | "tag";
 /** One scope's declared properties. `owner` is the owning entity's gameId
  *  (empty for world / story); `box` names its box; `group` names a tag's
- *  group. */
+ *  group. A zone of the project map is a `tag` scope with `group` and NO
+ *  `box`: it belongs to none. */
 interface PropertyScopeSummary {
     scope: PropertyScopeKind;
     owner: string;
@@ -920,23 +951,28 @@ interface PropertyScopeSummary {
     properties: PropertySummary[];
 }
 /**
- * One map the bundle was asked to carry (design/graphical-views.md 2).
+ * The project map (design/project-map-contract.md 3.7): its group, which boxes
+ * are on it, and how much geometry the bundle carries.
  *
  * Counts rather than the geometry itself, which is the same judgement the rest
  * of this file makes: an inspector answers "what is in here", and a host that
- * wants the polygons reads `bundle.maps` directly. Reported because a bundle
- * that silently carried a map would fail the promise this API exists for.
+ * wants the polygons reads `bundle.map.geometry` directly. The geometry counts
+ * are zero when the build did not ask for geometry (`export.map`); the group is
+ * there regardless, because hands and cards reference it.
  */
 interface MapSummary {
-    /** The owning box, by gameId. */
-    box: string;
-    /** The tag group this is a map of, by gameId. */
+    /** The zone group's gameId: the name an opted-in box's peek criteria use. */
     group: string;
+    /** Its tags (the zones), by gameId. */
+    tags: string[];
+    /** The opted-in boxes, by gameId, in bundle order. */
+    boxes: string[];
+    /** Drawn zones in the carried geometry. */
     zones: number;
     backgrounds: number;
-    /** Placed hands standing on this map (design/engine-server.md 4.3): where the
-     *  kiosks are, in a bundle that carries geometry at all. */
-    sites: number;
+    /** Box gameId -> placed hands standing on the map (design/engine-server.md
+     *  4.3): where the kiosks are. Only boxes with a site have a key. */
+    sites: Record<string, number>;
 }
 /** What a bundle offers a host, read from the asset alone. */
 interface BundleDescription {
@@ -953,13 +989,13 @@ interface BundleDescription {
     boxes: BoxSummary[];
     /** Every hand in the bundle, box by box: the deal() surface. */
     hands: HandSummary[];
-    /** world, story, then per box: the box, its decks, its hands, its tags.
-     *  Scopes that declare nothing are omitted (world and story always show,
+    /** world, story, then per box: the box, its decks, its hands, its tags;
+     *  then the project map's zones, once. Scopes that declare nothing are omitted (world and story always show,
      *  so their absence reads as "this bundle declares none"). */
     properties: PropertyScopeSummary[];
-    /** Maps carried as inert payload, when the build asked for them. Empty is
-     *  the normal state and means the bundle has no geometry in it. */
-    maps: MapSummary[];
+    /** The project map, when the bundle has one. Absent is the bundle with no
+     *  map at all. */
+    map?: MapSummary;
 }
 /** Describe a compiled bundle: the callable surface of an imported asset, no
  *  session required (design/engine-runtimes.md 2, piece 6). Bundle order

package/dist/index.d.ts

@@ -265,6 +265,7 @@ interface OwnerIndex {
     gameId: Map<string, string>;
     id: Map<string, string>;
     repeated: Map<string, string[]>;
+    zoneQualified: Map<string, string>;
 }
 type OwnerIndexes = Record<OwnedScope, OwnerIndex>;
 /** One side's five stores (shared on the engine, per-flow on each flow). */
@@ -297,9 +298,11 @@ interface Internals {
     /** The owner segment of a property address, both ways round (4.4). */
     owners: OwnerIndexes;
     templatesById: Map<string, HandTemplate<Expression>>;
+    /** Every group by internal id. `box` is absent for the project map's group,
+     *  which belongs to no box. */
     groupsById: Map<string, {
         group: TagGroup;
-        box: Box<Expression>;
+        box?: Box<Expression>;
     }>;
     requiredGroups: Set<string>;
     nodeCache: WeakMap<Expression, ExprNode>;
@@ -507,6 +510,20 @@ declare class Engine {
      *  `registry`, self-backed @world included; a game that passed a registry
      *  saves it once itself, beside each engine's envelope. */
     saveGame(): SaveEnvelope;
+    /** The registry's values in CANONICAL order, the order a load rebuilds them
+     *  in: the engine-wide keys as the constructor registered them, then each
+     *  flow's keys in `flows()` order (each flow's own registration order), then
+     *  anything else the registry holds (values still waiting for a key), as the
+     *  registry lists it. The registry itself lists keys in registration order,
+     *  and a flow replaced in place (`open()` above keeps its slot in
+     *  `flowsById`) re-registers its keys at the END, so `openFlow("a");
+     *  openFlow("b"); openFlow("a")` saved b's keys before a's while a load
+     *  rebuilt a's first: the same run, different `.storyletsave` bytes, and a
+     *  save loaded and saved again no longer equal to itself. It is the
+     *  2026-08-29 rule carried into the section save@2 moved the per-flow values
+     *  to (2026-10-01). Order does not matter on READ (`partitionsFromSections`
+     *  sorts by key shape), so a save written in the old order loads as before. */
+    private registrySection;
     /** ONE flow's blob, to park a visit that is walking away: the same shape
      *  the envelope carries per flow, and the same shape `openFlow`'s `restore`
      *  option takes back (design/engine-server.md 4.1). Saving the whole
@@ -618,7 +635,13 @@ declare class Flow {
     /** Tag group names are box-scoped: two boxes may name a group the same way
      *  (schema 1 - boxes namespace their groups), so a name is only ever
      *  resolved inside the box being asked, never bundle-wide. Ids are
-     *  project-unique and accepted here too, still confined to the box. */
+     *  project-unique and accepted here too, still confined to the box.
+     *
+     *  A box on the project map sees ONE namespace: its own groups, then the
+     *  map's group (design/project-map-contract.md 3.1). A box that has not
+     *  opted in does not see the map's name at all, so a peek naming it there
+     *  is the ordinary unknown-group refusal. Own groups first is stated for
+     *  determinism only: a bundle that loads never has the two share a name. */
     private groupInBox;
     /** Fold one play into the indexes. O(the card's tags), not O(the log). */
     private indexPlay;
@@ -626,8 +649,10 @@ declare class Flow {
      *  rather than appended to, which is `restore` alone. */
     private rebuildPlayIndex;
     /** `box` is the box whose ask is being evaluated: the play-history
-     *  functions take a bare group name, so it resolves there (a card's tags
-     *  reference its own box's group, which keeps the counts box-local).
+     *  functions take a bare group name, so it resolves there, and they count
+     *  only that box's own plays (the box is in the index key). That was
+     *  automatic while every group was a box's; a project-map zone is shared,
+     *  and its history is still not (design/project-map-contract.md 3.7, D7).
      *  History is THIS flow's: countPlayed answers "have I done this". */
     /** One host per box, built once.
      *
@@ -816,7 +841,8 @@ declare class Flow {
 
 /** What bundle this is: the staleness/identity triple plus the schema tag. */
 interface BundleIdentity {
-    /** The bundle schema tag ("storylets/bundle@0"). */
+    /** The bundle schema tag ("storylets/bundle@1", or "@0" from before the
+     *  project map). */
     schema: string;
     /** content.project - the project name a save must agree with. */
     project: string;
@@ -866,6 +892,10 @@ interface TagGroupSummary {
 interface BoxSummary {
     gameId: string;
     title?: string;
+    /** The box is on the project map (design/project-map-contract.md 3.7): it
+     *  may name the map's group in peek criteria beside its own `tagGroups`,
+     *  which list the box's OWN groups only. Absent is "not on the map". */
+    usesMap?: true;
     /** The only per-box ranking policy (Reboot 2.2). */
     ranking: {
         specificity: boolean;
@@ -911,7 +941,8 @@ interface PropertySummary {
 type PropertyScopeKind = "world" | "story" | "box" | "deck" | "hand" | "tag";
 /** One scope's declared properties. `owner` is the owning entity's gameId
  *  (empty for world / story); `box` names its box; `group` names a tag's
- *  group. */
+ *  group. A zone of the project map is a `tag` scope with `group` and NO
+ *  `box`: it belongs to none. */
 interface PropertyScopeSummary {
     scope: PropertyScopeKind;
     owner: string;
@@ -920,23 +951,28 @@ interface PropertyScopeSummary {
     properties: PropertySummary[];
 }
 /**
- * One map the bundle was asked to carry (design/graphical-views.md 2).
+ * The project map (design/project-map-contract.md 3.7): its group, which boxes
+ * are on it, and how much geometry the bundle carries.
  *
  * Counts rather than the geometry itself, which is the same judgement the rest
  * of this file makes: an inspector answers "what is in here", and a host that
- * wants the polygons reads `bundle.maps` directly. Reported because a bundle
- * that silently carried a map would fail the promise this API exists for.
+ * wants the polygons reads `bundle.map.geometry` directly. The geometry counts
+ * are zero when the build did not ask for geometry (`export.map`); the group is
+ * there regardless, because hands and cards reference it.
  */
 interface MapSummary {
-    /** The owning box, by gameId. */
-    box: string;
-    /** The tag group this is a map of, by gameId. */
+    /** The zone group's gameId: the name an opted-in box's peek criteria use. */
     group: string;
+    /** Its tags (the zones), by gameId. */
+    tags: string[];
+    /** The opted-in boxes, by gameId, in bundle order. */
+    boxes: string[];
+    /** Drawn zones in the carried geometry. */
     zones: number;
     backgrounds: number;
-    /** Placed hands standing on this map (design/engine-server.md 4.3): where the
-     *  kiosks are, in a bundle that carries geometry at all. */
-    sites: number;
+    /** Box gameId -> placed hands standing on the map (design/engine-server.md
+     *  4.3): where the kiosks are. Only boxes with a site have a key. */
+    sites: Record<string, number>;
 }
 /** What a bundle offers a host, read from the asset alone. */
 interface BundleDescription {
@@ -953,13 +989,13 @@ interface BundleDescription {
     boxes: BoxSummary[];
     /** Every hand in the bundle, box by box: the deal() surface. */
     hands: HandSummary[];
-    /** world, story, then per box: the box, its decks, its hands, its tags.
-     *  Scopes that declare nothing are omitted (world and story always show,
+    /** world, story, then per box: the box, its decks, its hands, its tags;
+     *  then the project map's zones, once. Scopes that declare nothing are omitted (world and story always show,
      *  so their absence reads as "this bundle declares none"). */
     properties: PropertyScopeSummary[];
-    /** Maps carried as inert payload, when the build asked for them. Empty is
-     *  the normal state and means the bundle has no geometry in it. */
-    maps: MapSummary[];
+    /** The project map, when the bundle has one. Absent is the bundle with no
+     *  map at all. */
+    map?: MapSummary;
 }
 /** Describe a compiled bundle: the callable surface of an imported asset, no
  *  session required (design/engine-runtimes.md 2, piece 6). Bundle order