@storylet-studio/runtime 0.8.2 → 0.9.0

package/README.md

@@ -1,7 +1,7 @@
 # @storylet-studio/runtime
 
 The Storylet Engine **JS reference runtime**: the Engine and Flow surface of
-[the bundle format](https://storylet.studio/format/bundle/) section 5 -
+[the bundle format](https://storylets.dev/format/bundle/) section 5 -
 the engine (`openFlow` / `getFlow` / `flows` / `closeFlow` / `reset` /
 `saveGame` / `loadGame` / `saveFlow` / `previewLoad` / `previewFlowRestore` /
 `subscribeTrace` / `log` / `clearLog` /
@@ -24,4 +24,4 @@ game. Pass the game's as `new Engine(bundle, { registry })` to share it with any
 starting `storylets/`, `@world` is the game's to register, and `saveGame()` leaves the values
 to the game, which saves the registry once. Without one the engine makes its own registry, self-backs
 `@world`, and `saveGame()` carries every value, so one call is still the whole run. Version 1
-envelopes still load. See [Running it with Patter](https://storylet.studio/play/with-patter/#one-registry).
+envelopes still load. See [Running it with Patter](https://storylets.dev/play/with-patter/#one-registry).

package/dist/index.cjs

@@ -40,7 +40,7 @@ var import_scoperegistry = require("@wildwinter/scoperegistry");
 var import_expr = require("@wildwinter/expr");
 
 // src/engine.ts
-var tagKey = (groupId, tagId) => `${groupId}${tagId}`;
+var tagKey = (boxId, groupId, tagId) => `${boxId}${groupId}${tagId}`;
 var cardIsShared = (card, deckShared) => card.shared ?? deckShared;
 var sharedCap = (card) => card.sharedCopies ?? card.copies ?? 1;
 var OWNER = "Storylet Engine";
@@ -97,11 +97,12 @@ var isShared = (scope, d) => d.shared ?? SCOPE_DEFAULT_SHARED[scope];
 var sharedHalf = (scope, decls) => decls.filter((d) => isShared(scope, d));
 var flowHalf = (scope, decls) => decls.filter((d) => !isShared(scope, d));
 var OWNED_SCOPES = ["box", "deck", "hand", "value"];
+var emptyOwnerIndex = () => ({ gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map(), zoneQualified: /* @__PURE__ */ new Map() });
 var emptyOwnerIndexes = () => ({
-  box: { gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map() },
-  deck: { gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map() },
-  hand: { gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map() },
-  value: { gameId: /* @__PURE__ */ new Map(), id: /* @__PURE__ */ new Map(), repeated: /* @__PURE__ */ new Map() }
+  box: emptyOwnerIndex(),
+  deck: emptyOwnerIndex(),
+  hand: emptyOwnerIndex(),
+  value: emptyOwnerIndex()
 });
 var indexOwner = (index, entity) => {
   const gameId = (0, import_model.effectiveGameId)(entity);
@@ -113,6 +114,7 @@ var indexValueOwners = (index, bundle) => {
   for (const [id, segment] of addresses.print) index.gameId.set(id, segment);
   for (const [segment, id] of addresses.accept) index.id.set(segment, id);
   for (const [gameId, candidates] of addresses.repeated) index.repeated.set(gameId, candidates);
+  for (const [segment, zone] of addresses.zoneQualified) index.zoneQualified.set(segment, zone);
 };
 var handDeclsOf = (internals, hand) => {
   if (hand.template !== void 0) {
@@ -124,6 +126,8 @@ var addressOf = (internals, kind, id) => `${kind}.${internals.owners[kind].gameI
 var resolveOwner = (internals, kind, segment) => {
   const candidates = internals.owners[kind].repeated.get(segment);
   if (candidates !== void 0) return { ambiguous: candidates };
+  const zone = internals.owners[kind].zoneQualified.get(segment);
+  if (zone !== void 0) return { zone };
   const byGameId = internals.owners[kind].id.get(segment);
   if (byGameId !== void 0) return { id: byGameId, legacy: false };
   if (internals.owners[kind].gameId.has(segment)) return { id: segment, legacy: true };
@@ -133,6 +137,7 @@ var ownerOrThrow = (internals, kind, segment, name) => {
   const owner = resolveOwner(internals, kind, segment);
   if (owner === void 0) throw new Error(`no ${kind} store "${segment}"`);
   if ("ambiguous" in owner) throw new Error((0, import_model.ambiguousValueAddressMessage)(segment, name, owner.ambiguous));
+  if ("zone" in owner) throw new Error((0, import_model.zoneQualifiedValueAddressMessage)(segment, owner.zone, name));
   return owner;
 };
 var legacyAddressMessage = (internals, kind, segment, name) => `"${kind}.${segment}.${name}" names the ${kind} by its internal id; write "${addressOf(internals, kind, segment)}.${name}". The internal-id form is refused after the next release.`;
@@ -150,9 +155,12 @@ var buildPartition = (internals, half) => {
     hand: new Map(b.boxes.flatMap((box) => box.hands.map(
       (hand) => [hand.id, bagFromDecls(half("hand", handDeclsOf(internals, hand)), at("hand", hand.id))]
     ))),
-    value: new Map(b.boxes.flatMap((box) => box.tagGroups.flatMap((group) => group.tags.map(
+    // Every box's tags, then the project map's zones ONCE (design/project-
+    // map-contract.md 3.3): a zone is one bag per partition, whichever boxes'
+    // hands are dealt to it.
+    value: new Map((0, import_model.allTagGroups)(b).flatMap((group) => group.tags.map(
       (tag) => [tag.id, bagFromDecls(half("value", tag.properties ?? []), at("value", tag.id))]
-    ))))
+    )))
   };
 };
 var partitionValues = (p) => ({
@@ -269,6 +277,68 @@ function finishReport(bundle, saved, flows, draft) {
     retypedProperties
   };
 }
+var refuseUnreadableBundle = (bundle) => {
+  const schema = bundle.schema;
+  if (typeof schema !== "string" || !import_model.BUNDLE_SCHEMAS.includes(schema)) {
+    throw new Error(`unsupported bundle schema: ${String(schema)} (this runtime reads ${import_model.BUNDLE_SCHEMAS.join(" and ")})`);
+  }
+  const problems = [];
+  const map = bundle.map?.group;
+  const mapName = map !== void 0 ? (0, import_model.effectiveGameId)(map) : void 0;
+  if (map !== void 0 && mapName === import_model.PLACE_GROUP) {
+    problems.push(`the project map's tag group is called "${import_model.PLACE_GROUP}", which is reserved for a box's own hands`);
+  }
+  const boxTags = /* @__PURE__ */ new Map();
+  for (const box of bundle.boxes) {
+    for (const group of box.tagGroups) {
+      for (const tag of group.tags) {
+        const gameId = (0, import_model.effectiveGameId)(tag);
+        if (!boxTags.has(gameId)) boxTags.set(gameId, { box: (0, import_model.effectiveGameId)(box), group: (0, import_model.effectiveGameId)(group) });
+      }
+    }
+  }
+  for (const tag of map?.tags ?? []) {
+    const zone = (0, import_model.effectiveGameId)(tag);
+    const clash = boxTags.get(zone);
+    if (clash !== void 0) {
+      problems.push(`the project map's zone "${zone}" has the name of tag "${zone}" in box "${clash.box}", group "${clash.group}", so "value.${zone}.<name>" would name two things`);
+    }
+  }
+  for (const box of bundle.boxes) {
+    const boxName = (0, import_model.effectiveGameId)(box);
+    if (box.usesMap === true) {
+      if (map === void 0) {
+        problems.push(`box "${boxName}" uses the project map, but the bundle has no map`);
+        continue;
+      }
+      const twin = box.tagGroups.find((g) => (0, import_model.effectiveGameId)(g) === mapName);
+      if (twin !== void 0) {
+        problems.push(`box "${boxName}" uses the project map and declares its own tag group "${mapName}", the map's name`);
+      }
+      continue;
+    }
+    if (map === void 0) continue;
+    const names = (where) => {
+      problems.push(`box "${boxName}" is not on the project map, but ${where} names the map's tag group "${mapName}"`);
+    };
+    for (const deck of box.decks) {
+      for (const card of deck.cards) {
+        if (card.tags?.[map.id] !== void 0) names(`card "${(0, import_model.effectiveGameId)(card)}"`);
+      }
+    }
+    for (const template of box.handTemplates) {
+      if (template.bindings?.[map.id] !== void 0 || template.chooses?.includes(map.id) === true) {
+        names(`hand template "${(0, import_model.effectiveGameId)(template)}"`);
+      }
+    }
+    for (const hand of box.hands) {
+      if (hand.chosen?.[map.id] !== void 0 || hand.rule?.bindings?.[map.id] !== void 0) {
+        names(`hand "${(0, import_model.effectiveGameId)(hand)}"`);
+      }
+    }
+  }
+  if (problems.length > 0) throw new Error(`bundle refused: ${problems.join("; ")}`);
+};
 var Engine = class _Engine {
   internals;
   seed;
@@ -285,6 +355,7 @@ var Engine = class _Engine {
    *  hotSwap puts this engine back exactly as it was. */
   sharedMounts = [];
   constructor(bundle, opts = {}) {
+    refuseUnreadableBundle(bundle);
     this.creationOptions = opts;
     this.seed = opts.seed ?? 0;
     this.onReplacedFlow = opts.onReplacedFlow;
@@ -368,6 +439,10 @@ var Engine = class _Engine {
         indexOwner(internals.owners.hand, hand);
       }
     }
+    if (bundle.map !== void 0) {
+      internals.groupsById.set(bundle.map.group.id, { group: bundle.map.group });
+      if (bundle.map.group.required === true) internals.requiredGroups.add(bundle.map.group.id);
+    }
     this.initLadders();
     const declSet = (half) => ({
       story: half("story", bundle.story.properties),
@@ -378,9 +453,9 @@ var Engine = class _Engine {
       hand: new Map(bundle.boxes.flatMap((box) => box.hands.map(
         (hand) => [hand.id, half("hand", handDeclsOf(internals, hand))]
       ))),
-      value: new Map(bundle.boxes.flatMap((box) => box.tagGroups.flatMap((group) => group.tags.map(
+      value: new Map((0, import_model.allTagGroups)(bundle).flatMap((group) => group.tags.map(
         (tag) => [tag.id, half("value", tag.properties ?? [])]
-      ))))
+      )))
     });
     internals.flowDecls = declSet(flowHalf);
     internals.sharedDecls = declSet(sharedHalf);
@@ -481,6 +556,7 @@ var Engine = class _Engine {
       }
       for (const hand of box.hands) internals.ladders.hand.set(hand.id, grab(handDeclsOf(internals, hand)));
     }
+    for (const tag of b.map?.group.tags ?? []) internals.ladders.value.set(tag.id, grab(tag.properties));
     const any = (m) => [...m.values()].some((x) => x.size > 0);
     internals.hasQualities = internals.ladders.world.size > 0 || internals.ladders.story.size > 0 || any(internals.ladders.box) || any(internals.ladders.deck) || any(internals.ladders.value) || any(internals.ladders.hand);
   }
@@ -804,11 +880,35 @@ var Engine = class _Engine {
     return structuredClone({
       schema: import_model2.SAVE_SCHEMA,
       content: this.internals.bundle.content,
-      ...this.internals.ownsRegistry ? { registry: this.internals.registry.save() } : {},
+      ...this.internals.ownsRegistry ? { registry: this.registrySection() } : {},
       shared: { spent: [...this.spent].sort() },
       flows: Object.fromEntries([...this.flowsById].map(([id, flow]) => [id, flow.snapshot(false)]))
     });
   }
+  /** 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. */
+  registrySection() {
+    const all = this.internals.registry.save();
+    const out = {};
+    const take = (key) => {
+      if (Object.prototype.hasOwnProperty.call(all, key) && !Object.prototype.hasOwnProperty.call(out, key)) out[key] = all[key];
+    };
+    for (const { key } of this.sharedMounts) take(key);
+    for (const flow of this.flowsById.values()) for (const key of flow.registeredKeys()) take(key);
+    for (const key of Object.keys(all)) take(key);
+    return out;
+  }
   /** 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
@@ -1138,9 +1238,16 @@ var Flow = class {
   /** 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. */
   groupInBox(box, ref) {
-    return box.tagGroups.find((g) => (0, import_model.effectiveGameId)(g) === ref) ?? box.tagGroups.find((g) => g.id === ref);
+    const groups = (0, import_model.groupsOfBox)(this.internals.bundle, box);
+    return groups.find((g) => (0, import_model.effectiveGameId)(g) === ref) ?? groups.find((g) => g.id === ref);
   }
   /** Fold one play into the indexes. O(the card's tags), not O(the log). */
   indexPlay(record) {
@@ -1150,7 +1257,7 @@ var Flow = class {
     if (!entry) return;
     for (const [groupId, tagIds] of Object.entries(entry.card.tags ?? {})) {
       for (const tagId of tagIds) {
-        const key = tagKey(groupId, tagId);
+        const key = tagKey(entry.box.id, groupId, tagId);
         this.tagPlayCount.set(key, (this.tagPlayCount.get(key) ?? 0) + 1);
         this.lastPlayInTag.set(key, record);
       }
@@ -1166,8 +1273,10 @@ var Flow = class {
     for (const record of this.playLog) this.indexPlay(record);
   }
   /** `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.
    *
@@ -1192,7 +1301,7 @@ var Flow = class {
     const keyOf = (group, tag) => {
       const found = this.groupInBox(box, group);
       const t = found?.tags.find((v) => v.gameId === tag);
-      return found && t ? tagKey(found.id, t.id) : void 0;
+      return found && t ? tagKey(box.id, found.id, t.id) : void 0;
     };
     const since = (record) => {
       const entry = this.internals.cardsByGameId.get(record.card);
@@ -1399,7 +1508,7 @@ var Flow = class {
    * is what says otherwise.
    */
   bindStateGroups(box, boundTags, askNames) {
-    for (const group of box.tagGroups) {
+    for (const group of (0, import_model.groupsOfBox)(this.internals.bundle, box)) {
       if (group.boundBy === void 0 || boundTags.has(group.id)) continue;
       const ref = /^@(world|story)\.([a-z][a-z0-9_-]*)$/.exec(group.boundBy);
       if (!ref) {
@@ -2074,12 +2183,12 @@ var handDecls = (hand, box) => {
   }
   return hand.properties ?? [];
 };
-var movableHoles = (hand, box) => {
+var movableHoles = (bundle, hand, box) => {
   const filled = hand.template !== void 0 ? hand.chosen : hand.rule?.bindings;
   const out = [];
   for (const [groupId, value] of Object.entries(filled ?? {})) {
     if (!(0, import_model3.isHoleRef)(value)) continue;
-    const group = box.tagGroups.find((g) => g.id === groupId);
+    const group = (0, import_model3.groupsOfBox)(bundle, box).find((g) => g.id === groupId);
     if (group === void 0) continue;
     out.push({ group: (0, import_model3.effectiveGameId)(group), from: value });
   }
@@ -2104,6 +2213,7 @@ function describeBundle(bundle) {
     boxes.push({
       gameId: boxGameId,
       ...box.title !== void 0 ? { title: box.title } : {},
+      ...box.usesMap === true ? { usesMap: true } : {},
       ranking: { specificity: box.ranking.specificity },
       ...box.turn !== void 0 ? { turn: { seconds: box.turn.seconds } } : {},
       ...durableCardCount(box) > 0 ? { durableCards: durableCardCount(box) } : {},
@@ -2127,7 +2237,7 @@ function describeBundle(bundle) {
     totals.tagGroups += box.tagGroups.length;
     for (const hand of box.hands) {
       const template = hand.template !== void 0 ? box.handTemplates.find((t) => t.id === hand.template) : void 0;
-      const movable = movableHoles(hand, box);
+      const movable = movableHoles(bundle, hand, box);
       hands.push({
         gameId: (0, import_model3.effectiveGameId)(hand),
         ...hand.title !== void 0 ? { title: hand.title } : {},
@@ -2156,6 +2266,15 @@ function describeBundle(bundle) {
       }
     }
   }
+  const map = bundle.map;
+  if (map !== void 0) {
+    const group = (0, import_model3.effectiveGameId)(map.group);
+    for (const tag of map.group.tags) {
+      const decls = tag.properties ?? [];
+      if (decls.length > 0) properties.push({ scope: "tag", owner: (0, import_model3.effectiveGameId)(tag), group, properties: summarise(decls) });
+    }
+    totals.tagGroups += 1;
+  }
   return {
     identity: {
       schema: bundle.schema,
@@ -2168,13 +2287,16 @@ function describeBundle(bundle) {
     boxes,
     hands,
     properties,
-    maps: (bundle.maps ?? []).map((map) => ({
-      box: map.box,
-      group: map.group,
-      zones: map.zones.length,
-      backgrounds: map.backgrounds?.length ?? 0,
-      sites: map.sites?.length ?? 0
-    }))
+    ...map !== void 0 ? {
+      map: {
+        group: (0, import_model3.effectiveGameId)(map.group),
+        tags: map.group.tags.map((tag) => (0, import_model3.effectiveGameId)(tag)),
+        boxes: bundle.boxes.filter((box) => box.usesMap === true).map((box) => (0, import_model3.effectiveGameId)(box)),
+        zones: map.geometry?.zones.length ?? 0,
+        backgrounds: map.geometry?.backgrounds?.length ?? 0,
+        sites: Object.fromEntries(Object.entries(map.geometry?.sites ?? {}).map(([box, sites]) => [box, sites.length]))
+      }
+    } : {}
   };
 }
 // Annotate the CommonJS export names for ESM import in node: