@storylet-studio/runtime 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -453,8 +453,12 @@ var PropertyBag = class _PropertyBag {
    *  long-standing contract); a product whose names are case-significant
    *  passes identity. */
   norm;
+  /** The address prefix this bag's rows carry, separator included (`@`,
+   *  `@scene.`, `world.`, `deck.<id>.`). Empty means a row's path is its name. */
+  pathPrefix;
   constructor(declarations = [], opts) {
     this.norm = opts?.normalise ?? ((n) => n.toLowerCase());
+    this.pathPrefix = opts?.pathPrefix ?? "";
     this.seed(declarations);
   }
   seed(declarations) {
@@ -498,7 +502,7 @@ var PropertyBag = class _PropertyBag {
   /** Examiner rows: the declared surface only (stray values are storage,
    *  not surface). */
   rows() {
-    return [...this.decls.entries()].map(([name, d]) => rowFor(d, this.get(name), void 0, name));
+    return [...this.decls.entries()].map(([name, d]) => rowFor(d, this.get(name), void 0, name, this.pathPrefix));
   }
   declarations() {
     return [...this.decls.values()];
@@ -507,7 +511,7 @@ var PropertyBag = class _PropertyBag {
    *  duplicated, the normalisation policy carried, subscriptions NOT
    *  carried. */
   clone() {
-    const c = new _PropertyBag([], { normalise: this.norm });
+    const c = new _PropertyBag([], { normalise: this.norm, pathPrefix: this.pathPrefix });
     c.decls = new Map(this.decls);
     Object.assign(c.values, structuredClone(this.values));
     return c;
@@ -530,13 +534,19 @@ var PropertyBag = class _PropertyBag {
     for (const [k, v] of Object.entries(values)) this.values[this.norm(k)] = v;
   }
 };
-function rowFor(d, value, writable, name) {
+function rowFor(d, value, writable, name, pathPrefix = "") {
+  const rowName = name ?? d.name.toLowerCase();
   return {
-    name: name ?? d.name.toLowerCase(),
+    name: rowName,
+    path: pathPrefix + rowName,
     type: d.type,
     value,
     default: d.default ?? defaultFor(d),
     ...d.values !== void 0 ? { values: d.values } : {},
+    // `stages` was added to the row so an examiner could offer a quality's ladder
+    // instead of a free-text box, and then never populated here: every quality row
+    // this function built came out without one. Fixed 2026-09-02.
+    ...d.stages !== void 0 ? { stages: d.stages } : {},
     writable: writable ?? d.writable ?? true
   };
 }
@@ -556,6 +566,13 @@ function defaultFor(d) {
     // A quality starts at the first rung of its ladder.
     case "quality":
       return d.stages?.[0] ?? "";
+    // Unreachable for a well-typed declaration, and deliberately present anyway: a bundle
+    // is DATA, and a hand-edited or newer-than-this-build one can carry a type string the
+    // union does not have. Falling off the switch would seed `undefined`, which is not a
+    // ScalarValue and travels a long way before it fails. Patterplay's copy of this had the
+    // guard and this one did not, which is the drift you only find by removing a duplicate.
+    default:
+      return false;
   }
 }
 
@@ -563,7 +580,7 @@ function defaultFor(d) {
 var tagKey = (groupId, tagId) => `${groupId}${tagId}`;
 var cardIsShared = (card, deckShared) => card.shared ?? deckShared;
 var sharedCap = (card) => card.sharedCopies ?? card.copies ?? 1;
-var bagFromDecls = (decls) => new PropertyBag(decls, { normalise: (n) => n });
+var bagFromDecls = (decls, pathPrefix) => new PropertyBag(decls, { normalise: (n) => n, pathPrefix });
 function conditionPasses(v) {
   if (typeof v === "boolean") return v;
   if (typeof v === "number") return v !== 0;
@@ -583,18 +600,18 @@ var handDeclsOf = (internals, hand) => {
 var buildPartition = (internals, half) => {
   const b = internals.bundle;
   return {
-    story: bagFromDecls(half("story", b.story.properties)),
-    box: new Map(b.boxes.map((box) => [box.id, bagFromDecls(half("box", box.properties))])),
+    story: bagFromDecls(half("story", b.story.properties), "story."),
+    box: new Map(b.boxes.map((box) => [box.id, bagFromDecls(half("box", box.properties), `box.${box.id}.`)])),
     deck: new Map(b.boxes.flatMap((box) => box.decks.map(
-      (deck) => [deck.id, bagFromDecls(half("deck", deck.properties))]
+      (deck) => [deck.id, bagFromDecls(half("deck", deck.properties), `deck.${deck.id}.`)]
     ))),
     // A template instance inherits the template's property declarations;
     // a standalone hand declares its own (schema 2.6).
     hand: new Map(b.boxes.flatMap((box) => box.hands.map(
-      (hand) => [hand.id, bagFromDecls(half("hand", handDeclsOf(internals, hand)))]
+      (hand) => [hand.id, bagFromDecls(half("hand", handDeclsOf(internals, hand)), `hand.${hand.id}.`)]
     ))),
     value: new Map(b.boxes.flatMap((box) => box.tagGroups.flatMap((group) => group.tags.map(
-      (tag) => [tag.id, bagFromDecls(half("value", tag.properties ?? []))]
+      (tag) => [tag.id, bagFromDecls(half("value", tag.properties ?? []), `value.${tag.id}.`)]
     ))))
   };
 };
@@ -616,6 +633,7 @@ var loadPartition = (p, values) => {
 var Engine = class {
   internals;
   seed;
+  onReplacedFlow;
   flowsById = /* @__PURE__ */ new Map();
   engineTraceHandlers = /* @__PURE__ */ new Set();
   /** The host's @world binding, if the engine was built with one: it
@@ -624,6 +642,7 @@ var Engine = class {
   hostWorld;
   constructor(bundle, opts = {}) {
     this.seed = opts.seed ?? 0;
+    this.onReplacedFlow = opts.onReplacedFlow;
     if (opts.world !== void 0) this.hostWorld = opts.world;
     const internals = {
       bundle,
@@ -644,6 +663,7 @@ var Engine = class {
       flowDecls: { story: [], box: /* @__PURE__ */ new Map(), deck: /* @__PURE__ */ new Map(), hand: /* @__PURE__ */ new Map(), value: /* @__PURE__ */ new Map() },
       shared: void 0,
       worldResolver: void 0,
+      worldReadOnly: /* @__PURE__ */ new Set(),
       emitEngine: (flow, event, turn) => {
         if (this.internals.logCap !== void 0) {
           this.engineLog.push({ ...event, flow, seq: this.engineSeq++, ...turn !== void 0 ? { turn } : {} });
@@ -701,10 +721,11 @@ var Engine = class {
   initShared(hostWorld) {
     const internals = this.internals;
     internals.shared = buildPartition(internals, sharedHalf);
+    internals.worldReadOnly = new Set(internals.bundle.world.properties.filter((d) => d.writable === false).map((d) => d.name));
     if (hostWorld !== void 0) {
       internals.worldResolver = hostWorld;
     } else {
-      const bag = bagFromDecls(internals.bundle.world.properties);
+      const bag = bagFromDecls(internals.bundle.world.properties, "world.");
       internals.worldResolver = {
         get: (n) => bag.get(n),
         set: (n, v) => {
@@ -744,7 +765,12 @@ var Engine = class {
    *  state; shared state is untouched. There is no default flow: "main" is
    *  a caller convention, not an engine rule. */
   openFlow(id, opts = {}) {
-    this.flowsById.get(id)?.markClosed();
+    const existing = this.flowsById.get(id);
+    if (existing) {
+      const dealt = existing.heldCardIds().length;
+      if (dealt > 0) this.onReplacedFlow?.(id, dealt);
+      existing.markClosed();
+    }
     const flow = new Flow(this, this.internals, id, opts.seed ?? this.seed);
     this.flowsById.set(id, flow);
     return flow;
@@ -880,11 +906,16 @@ var Engine = class {
         value: value ?? d.default,
         default: d.default,
         ...d.values !== void 0 ? { values: d.values } : {},
-        ...d.stages !== void 0 ? { stages: d.stages } : {}
+        ...d.stages !== void 0 ? { stages: d.stages } : {},
+        // @world is FOREIGN - a host resolver backs it - so writability is whether that
+        // resolver can be written at all, which is the shared registry's own rule for a
+        // foreign scope. The `as PropertyView` cast this replaced was hiding the field's
+        // absence: the row type has always required it, and these rows shipped without one.
+        writable: this.internals.worldResolver.set !== void 0
       });
     }
-    const add = (prefix, bag) => {
-      for (const row of bag.rows()) out.push({ path: `${prefix}.${row.name}`, ...row });
+    const add = (_prefix, bag) => {
+      for (const row of bag.rows()) out.push(row);
     };
     add("story", this.internals.shared.story);
     for (const [id, bag] of this.internals.shared.box) add(`box.${id}`, bag);
@@ -1705,6 +1736,7 @@ var Flow = class {
       case "world": {
         const resolver = this.internals.worldResolver;
         if (!resolver.set) throw new Error(`@world.${name} cannot be written: the host bound @world read-only`);
+        if (this.internals.worldReadOnly.has(name)) throw new Error(`'@world.${name}' is read-only (writable: false)`);
         const prev = resolver.get(name);
         resolver.set(name, value);
         return { path: `world.${name}`, ...prev !== void 0 ? { prev } : {} };
@@ -1776,13 +1808,18 @@ var Flow = class {
         value: value ?? d.default,
         default: d.default,
         ...d.values !== void 0 ? { values: d.values } : {},
-        ...d.stages !== void 0 ? { stages: d.stages } : {}
+        ...d.stages !== void 0 ? { stages: d.stages } : {},
+        // @world is FOREIGN - a host resolver backs it - so writability is whether that
+        // resolver can be written at all, which is the shared registry's own rule for a
+        // foreign scope. The `as PropertyView` cast this replaced was hiding the field's
+        // absence: the row type has always required it, and these rows shipped without one.
+        writable: this.internals.worldResolver.set !== void 0
       });
     }
-    const add = (prefix, shared, own) => {
+    const add = (_prefix, shared, own) => {
       for (const bag of [shared, own]) {
         if (bag === void 0) continue;
-        for (const row of bag.rows()) out.push({ path: `${prefix}.${row.name}`, ...row });
+        for (const row of bag.rows()) out.push(row);
       }
     };
     add("story", this.internals.shared.story, this.stores.story);