@storylet-studio/runtime 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -2,6 +2,7 @@ import { ScalarValue, ScopeResolver, ExprNode } from '@wildwinter/expr';
 export { Prng, makePrng, shuffleInPlace } from '@wildwinter/expr';
 import { Bundle, Card, Expression, Deck, Box, Hand, HandTemplate, TagGroup, PropertyDecl, FlowSave, SaveEnvelope, PropertyType, ScalarValue as ScalarValue$1 } from '@storylet-studio/model';
 import { PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+export { PropertyRow } from '@wildwinter/scoperegistry';
 
 interface EngineOptions {
     /** Default seed for each flow's PRNG; override per flow in openFlow
@@ -142,11 +143,6 @@ interface CardEntry {
     deck: Deck<Expression>;
     box: Box<Expression>;
 }
-/** One examiner row, addressed by the property-path grammar
- *  (getProperty / setProperty take the same `path`). */
-interface PropertyView extends PropertyRow {
-    path: string;
-}
 /** One kernel bag with its store path prefix (story / box.<id> / deck.<id>
  *  / hand.<id> / value.<id>): the state logger's mount surface
  *  (design/engine-runtimes.md 3.4 - the logger builds on the PropertyBag
@@ -308,7 +304,7 @@ declare class Engine {
     private resolveShared;
     /** The shared surface as examiner rows: @world (read through the
      *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
-    listProperties(): PropertyView[];
+    listProperties(): PropertyRow[];
     /** The SHARED kernel bags with their store path prefixes (the state
      *  logger's mount surface). The @world container is the host's own bag -
      *  the host mounts it itself. */
@@ -525,7 +521,7 @@ declare class Flow {
      *  resolver, then per scope the shared values and this flow's own.
      *  Bundle order: world, story, then per-box / per-deck / per-hand /
      *  per-tag stores. */
-    listProperties(): PropertyView[];
+    listProperties(): PropertyRow[];
     /** Read by path: "world.x", "story.gold", "value.v_docks.danger",
      *  "box.b_x.heat", "deck.k_main.n", "hand.h_board.owner" - the flow's
      *  merged view, routed by the declaration's sharing. */
@@ -653,4 +649,4 @@ interface BundleDescription {
  *  throughout; the same shape every runtime returns. */
 declare function describeBundle(bundle: Bundle): BundleDescription;
 
-export { type BagMount, type BoxSummary, type BoxView, type BundleDescription, type BundleIdentity, type DealtCard, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, Flow, type HandSummary, type LogEntry, type MapSummary, type OpenFlowOptions, type OutcomeView, type PlayOptions, type PropertyScopeKind, type PropertyScopeSummary, type PropertySummary, type PropertyView, type RankedList, type TagGroupSummary, type TraceEvent, type TraceHandler, type TraceVerdict, describeBundle };
+export { type BagMount, type BoxSummary, type BoxView, type BundleDescription, type BundleIdentity, type DealtCard, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, Flow, type HandSummary, type LogEntry, type MapSummary, type OpenFlowOptions, type OutcomeView, type PlayOptions, type PropertyScopeKind, type PropertyScopeSummary, type PropertySummary, type RankedList, type TagGroupSummary, type TraceEvent, type TraceHandler, type TraceVerdict, describeBundle };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { ScalarValue, ScopeResolver, ExprNode } from '@wildwinter/expr';
 export { Prng, makePrng, shuffleInPlace } from '@wildwinter/expr';
 import { Bundle, Card, Expression, Deck, Box, Hand, HandTemplate, TagGroup, PropertyDecl, FlowSave, SaveEnvelope, PropertyType, ScalarValue as ScalarValue$1 } from '@storylet-studio/model';
 import { PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+export { PropertyRow } from '@wildwinter/scoperegistry';
 
 interface EngineOptions {
     /** Default seed for each flow's PRNG; override per flow in openFlow
@@ -142,11 +143,6 @@ interface CardEntry {
     deck: Deck<Expression>;
     box: Box<Expression>;
 }
-/** One examiner row, addressed by the property-path grammar
- *  (getProperty / setProperty take the same `path`). */
-interface PropertyView extends PropertyRow {
-    path: string;
-}
 /** One kernel bag with its store path prefix (story / box.<id> / deck.<id>
  *  / hand.<id> / value.<id>): the state logger's mount surface
  *  (design/engine-runtimes.md 3.4 - the logger builds on the PropertyBag
@@ -308,7 +304,7 @@ declare class Engine {
     private resolveShared;
     /** The shared surface as examiner rows: @world (read through the
      *  resolver) then the shared partitions. Per-flow rows live on each Flow. */
-    listProperties(): PropertyView[];
+    listProperties(): PropertyRow[];
     /** The SHARED kernel bags with their store path prefixes (the state
      *  logger's mount surface). The @world container is the host's own bag -
      *  the host mounts it itself. */
@@ -525,7 +521,7 @@ declare class Flow {
      *  resolver, then per scope the shared values and this flow's own.
      *  Bundle order: world, story, then per-box / per-deck / per-hand /
      *  per-tag stores. */
-    listProperties(): PropertyView[];
+    listProperties(): PropertyRow[];
     /** Read by path: "world.x", "story.gold", "value.v_docks.danger",
      *  "box.b_x.heat", "deck.k_main.n", "hand.h_board.owner" - the flow's
      *  merged view, routed by the declaration's sharing. */
@@ -653,4 +649,4 @@ interface BundleDescription {
  *  throughout; the same shape every runtime returns. */
 declare function describeBundle(bundle: Bundle): BundleDescription;
 
-export { type BagMount, type BoxSummary, type BoxView, type BundleDescription, type BundleIdentity, type DealtCard, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, Flow, type HandSummary, type LogEntry, type MapSummary, type OpenFlowOptions, type OutcomeView, type PlayOptions, type PropertyScopeKind, type PropertyScopeSummary, type PropertySummary, type PropertyView, type RankedList, type TagGroupSummary, type TraceEvent, type TraceHandler, type TraceVerdict, describeBundle };
+export { type BagMount, type BoxSummary, type BoxView, type BundleDescription, type BundleIdentity, type DealtCard, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, Flow, type HandSummary, type LogEntry, type MapSummary, type OpenFlowOptions, type OutcomeView, type PlayOptions, type PropertyScopeKind, type PropertyScopeSummary, type PropertySummary, type RankedList, type TagGroupSummary, type TraceEvent, type TraceHandler, type TraceVerdict, describeBundle };

package/dist/index.js

@@ -423,8 +423,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) {
@@ -468,7 +472,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()];
@@ -477,7 +481,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;
@@ -500,13 +504,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
   };
 }
@@ -526,6 +536,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;
   }
 }
 
@@ -533,7 +550,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;
@@ -553,18 +570,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}.`)]
     ))))
   };
 };
@@ -674,7 +691,7 @@ var Engine = class {
     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) => {
@@ -850,11 +867,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);
@@ -1746,13 +1768,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);