@patterkit/runtime 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -33,6 +33,55 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-02
+
+### Changed
+
+- **BREAKING: a property row's address is `path`, not `ref`, and the row carries `name` and
+  `writable`.** `listProperties()` returns the row type from `@wildwinter/scoperegistry` itself,
+  rather than a local interface redeclaring it. `path` holds exactly what `ref`
+  held: the reference `getProperty` / `setProperty` take. `name` is the bare declared name.
+  `writable` is always true here, because Patter has no read-only shared property; it is carried
+  because the row is shared with the Storylet Engine, which does declare them.
+
+  The fork it replaces was not free. A quality's `stages` was added to the local copy and so never
+  reached the shared type, and the Storylet Engine - reading the same property model through the
+  same registry - could not carry a ladder at all: it edited a quality as free text on every
+  platform it ships. One row, one place to add the next field.
+- **BREAKING: a row's address is the qualified one, `@patter.gold`, not `@gold`.** Both forms
+  have always resolved on input and still do - an unqualified name defaults to the `patter`
+  scope - so `getProperty("@gold")` is unaffected. What changed is the address a row REPORTS,
+  which is what a state panel displays and what an inspector writes back through. It matches
+  what `@scene` and the other family's scopes have always looked like.
+
+- **Scene and stage state is held in the shared property bag.** `@scene` properties lived in
+  hand-rolled maps that duplicated the bag's own seeding, so they missed its guards: two flows
+  entering one scene now never share a mutable flags list, and a `temporary` property's reset on
+  re-entry goes through the bag, which means a state logger sees it. **The save format is
+  unchanged** - a flat name/value map per scene, and a load that seeds from the bundle's
+  declarations before laying saved values over, so a property a save predates keeps its default.
+- **BREAKING: `PropertyView` is gone; `listProperties()` returns `PropertyRow`.** It was the
+  shared row plus a `path`, and `path` is on the shared row now, so the name was a second name
+  for one type. `PropertyRow` is re-exported from `@patterkit/runtime`, so naming a row needs no
+  dependency on `@wildwinter/scoperegistry`.
+- **Requires `@wildwinter/scoperegistry` ^0.4.0**, which is where the row's `path` lives.
+
+### Added
+
+- **A decision log, and `onDryChoice`.** Opening a run with `log: true` records what the engine
+  decided and why - each choice with the options it offered, the ones it greyed out and the
+  reason, each jump, each property write with the value it replaced. `Engine.log()` is the whole
+  run in order, a `Flow`'s own log is flow-local, and `onTrace` streams entries live rather than
+  retaining them. `onDryChoice` fires when a choice runs dry - no takeable option, no eligible
+  fallback - so the silent fall-through is observable; it survives alongside the log because it is
+  live feedback, not a record.
+
+### Fixed
+
+- **A quality row carries its ladder.** `stages` was on the row so an examiner could offer the
+  stages instead of a free-text box, and the code that builds rows never filled it in - on this
+  runtime and two others. Every quality row came out without one.
+
 ## [0.8.0] - 2026-09-01
 
 ### Changed

package/dist/index.cjs

@@ -34,6 +34,7 @@ module.exports = __toCommonJS(index_exports);
 var import_expr = require("@wildwinter/expr");
 var import_expr_specificity = require("@wildwinter/expr-specificity");
 var import_scoperegistry = require("@wildwinter/scoperegistry");
+var import_scoperegistry2 = require("@wildwinter/scoperegistry");
 var import_dialect = require("@patterkit/dialect");
 var import_model = require("@patterkit/model");
 
@@ -92,6 +93,10 @@ var Engine = class _Engine {
   /** The options this engine was built with - reused verbatim by `hotSwap` so the replacement
    *  engine keeps the same world resolver, custom RNG, and diagnostic hooks. */
   creationOptions;
+  /** The run's ordered stream: every flow's events, each naming its flow. Empty and
+   *  unwritten unless `options.log` asked for it. */
+  engineLog = [];
+  engineTraceHandlers = /* @__PURE__ */ new Set();
   constructor(bundle, options = {}) {
     this.creationOptions = options;
     const locale = options.locale ?? bundle.locales.default;
@@ -127,7 +132,7 @@ var Engine = class _Engine {
     const patterSharedDecls = props.filter((p) => p.shared ?? true).map(toDecl);
     const patterLocalDecls = props.filter((p) => !(p.shared ?? true)).map(toDecl);
     const patterSharedNames = new Set(patterSharedDecls.map((d) => d.name.toLowerCase()));
-    const shared = new import_scoperegistry.ScopeRegistry().defineOwned("patter", patterSharedDecls);
+    const shared = new import_scoperegistry.ScopeRegistry().defineOwned("patter", patterSharedDecls, "@patter.");
     const hostBound = /* @__PURE__ */ new Set();
     if (options.world) {
       const worldSpec = bundle.scopeRegistry?.scopes.find((s) => s.token === "world");
@@ -146,6 +151,8 @@ var Engine = class _Engine {
       sceneSharedNames.set(sceneId, names);
     }
     this.host = {
+      logEnabled: options.log ?? false,
+      emitEngine: (flow, event, scene) => this.emitEngine(flow, event, scene),
       bundle,
       emitIds,
       strings,
@@ -520,14 +527,44 @@ var Engine = class _Engine {
   }
   /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
    *  value, declared default (for reset), and enum options. Mirrors the Unity / Godot ports. */
+  /** The run's decisions, in order, each naming the flow it happened in. Empty unless the
+   *  run was opened with `log: true`. A flow's own log stays flow-local; this is the only
+   *  place a story spanning several flows reads as one sequence. */
+  log() {
+    return this.engineLog;
+  }
+  /** Drop the retained entries. `seq` does NOT restart: two reads of a log either side of a
+   *  clear still agree about what came first. */
+  clearLog() {
+    this.engineLog.length = 0;
+  }
+  /** Live tap on the run's decisions, for tooling that wants them as they happen rather than
+   *  retained. Returns its own unsubscribe. */
+  onTrace(handler) {
+    this.engineTraceHandlers.add(handler);
+    return () => this.engineTraceHandlers.delete(handler);
+  }
+  emitEngine(flow, event, scene) {
+    for (const h of this.engineTraceHandlers) h(flow, event);
+    if (!this.host.logEnabled) return;
+    this.engineLog.push({ ...event, flow, seq: this.engineLog.length, ...scene ? { scene } : {} });
+  }
   listProperties() {
     return this.host.patterSharedDecls.map((d) => ({
-      ref: `@${d.name}`,
+      name: d.name,
+      // The qualified address, matching what the bag composes for every other scope.
+      // `@gold` still resolves on input; it is the shorthand, not the address.
+      path: `@patter.${d.name}`,
       type: d.type,
       values: d.values,
       stages: d.stages,
       value: this.getProperty(`@${d.name}`),
-      default: declDefault(d)
+      default: (0, import_scoperegistry2.defaultFor)(d),
+      // Part of the shared row. Always true here today: `toDecl` never sets it, because
+      // Patter has no read-only shared property. The Storylet Engine does declare them
+      // and its panels disable the editor accordingly, so the field is carried rather
+      // than dropped - and the day a read-only @patter property exists, the row says so.
+      writable: d.writable ?? true
     }));
   }
   // @scene is scene-namespaced and needs a flow's current scene - silently
@@ -560,7 +597,7 @@ var Engine = class _Engine {
       shared: this.host.shared.save(),
       sharedVisits: Object.fromEntries(this.host.sharedVisits),
       sharedSelectors: serialiseSelectors(this.host.sharedSelectors),
-      stageBags: Object.fromEntries([...this.host.stageBags].map(([s, bag]) => [s, { ...bag }])),
+      stageBags: Object.fromEntries([...this.host.stageBags].map(([s, bag]) => [s, bag.save()])),
       flows
     };
   }
@@ -573,7 +610,13 @@ var Engine = class _Engine {
     this.host.sharedSelectors.clear();
     for (const [id, st] of deserialiseSelectors(save.sharedSelectors)) this.host.sharedSelectors.set(id, st);
     this.host.stageBags.clear();
-    for (const [s, bag] of Object.entries(save.stageBags ?? {})) this.host.stageBags.set(s, { ...bag });
+    for (const [s, values] of Object.entries(save.stageBags ?? {})) {
+      const shared = this.host.sceneSharedNames.get(s) ?? /* @__PURE__ */ new Set();
+      const decls = (this.host.bundle.scenes[s]?.sceneProps ?? []).filter((d) => shared.has(d.name.toLowerCase()));
+      const bag = new import_scoperegistry2.PropertyBag(decls);
+      bag.load(values);
+      this.host.stageBags.set(s, bag);
+    }
     this.flowsById.clear();
     for (const [id, snap] of Object.entries(save.flows)) {
       const flow = new Flow(id, this.host, this.defaultSeed);
@@ -616,6 +659,7 @@ var Flow = class {
   // The SHARED halves live on the host (`host.shared` / `host.stageBags`). Each
   // resolver presents one merged scope, routing each property to its half by the
   // declared `shared` flag.
+  /** This flow's per-scene LOCAL scene props; see FlowHost.stageBags. */
   sceneBags = /* @__PURE__ */ new Map();
   patterResolver = {
     get: (n) => this.host.patterSharedNames.has(n) ? this.host.shared.get("patter", n) : this.local.get("patter", n),
@@ -629,13 +673,13 @@ var Flow = class {
       const s = this.currentSceneId;
       if (s === null) return void 0;
       const bag = this.host.sceneSharedNames.get(s)?.has(n) ? this.host.stageBags.get(s) : this.sceneBags.get(s);
-      return bag?.[n];
+      return bag?.get(n);
     },
     set: (n, v) => {
       const s = this.currentSceneId;
       if (s === null) return;
       const bag = this.host.sceneSharedNames.get(s)?.has(n) ? this.host.stageBags.get(s) : this.sceneBags.get(s);
-      if (bag) bag[n] = v;
+      if (bag) bag.set(n, v);
     }
   };
   // The eval context is built ONCE: every constituent resolves live state at
@@ -644,6 +688,9 @@ var Flow = class {
   // `local`/`sceneBags`/`currentSceneId`; the host callbacks read current flow
   // fields). Rebuilding it per evaluation was the engine's hottest allocation.
   evalCtx;
+  flowLog = [];
+  /** Monotonic across the flow's life; survives clearLog so two reads agree on order. */
+  flowSeq = 0;
   constructor(id, host, seed) {
     this.id = id;
     this.host = host;
@@ -869,7 +916,17 @@ var Flow = class {
         this.stack.pop();
         continue;
       }
+      const from = frame.index;
       while (frame.index < children.length && !this.eligible(children[frame.index])) frame.index++;
+      if (this.host.logEnabled && frame.index !== from) {
+        this.emit({
+          type: "select",
+          group: frame.containerId,
+          selector: "run",
+          children: children.slice(from, frame.index + 1).map((c, i) => ({ id: c.id, eligible: from + i === frame.index })),
+          picked: children[frame.index]?.id ?? null
+        });
+      }
       if (frame.index >= children.length) {
         this.stack.pop();
         continue;
@@ -878,6 +935,24 @@ var Flow = class {
     }
   }
   /** The options of a pending choice (empty when not at a choice point). */
+  /** This flow's decisions, in order. Empty unless the run was opened with `log: true`.
+   *  The engine's log carries the same events tagged with the flow; this one is what a
+   *  single conversation reads as. */
+  log() {
+    return this.flowLog;
+  }
+  /** Drop the retained entries. `seq` keeps counting, so order survives a clear. */
+  clearLog() {
+    this.flowLog.length = 0;
+  }
+  /** Record one decision, on this flow's log and the engine's. Cheap to call with logging
+   *  off: the entry is never built. */
+  emit(event) {
+    const scene = this.currentSceneId ?? void 0;
+    this.host.emitEngine(this.id, event, scene);
+    if (!this.host.logEnabled) return;
+    this.flowLog.push({ ...event, seq: this.flowSeq++, ...scene ? { scene } : {} });
+  }
   getChoices() {
     return this.pendingChoice?.options ?? [];
   }
@@ -889,6 +964,7 @@ var Flow = class {
     if (!option) throw new Error(`unknown choice option: ${id}`);
     if (!option.eligible) throw new Error(`choice option is not eligible: ${id}`);
     const node = choice.byId.get(id);
+    this.emit({ type: "chose", group: choice.groupId, option: id });
     this.pendingChoice = null;
     this.pendingPromptBeat = this.host.replayPromptOnChoose ? this.promptBeatOf(node) ?? null : null;
     this.pendingPromptOwnerId = this.pendingPromptBeat ? node.id : null;
@@ -922,7 +998,7 @@ var Flow = class {
     return {
       scopes: this.local.save(),
       // owned scope "patter" = the NOT-shared globals (@scene saved separately)
-      sceneBags: Object.fromEntries([...this.sceneBags].map(([s, bag]) => [s, { ...bag }])),
+      sceneBags: Object.fromEntries([...this.sceneBags].map(([s, bag]) => [s, bag.save()])),
       rngState: this.rngState,
       visits: Object.fromEntries(this.visitCounts),
       cursor: {
@@ -960,7 +1036,13 @@ var Flow = class {
       }
       return { ...frame };
     });
-    this.sceneBags = new Map(Object.entries(snap.sceneBags ?? {}).map(([s, bag]) => [s, { ...bag }]));
+    this.sceneBags = new Map(Object.entries(snap.sceneBags ?? {}).map(([s, values]) => {
+      const shared = this.host.sceneSharedNames.get(s) ?? /* @__PURE__ */ new Set();
+      const decls = (this.host.bundle.scenes[s]?.sceneProps ?? []).filter((d) => !shared.has(d.name.toLowerCase()));
+      const bag = new import_scoperegistry2.PropertyBag(decls);
+      bag.load(values);
+      return [s, bag];
+    }));
     this.local = this.freshLocal();
     this.local.load(snap.scopes);
     this.activeSnippet = null;
@@ -1054,6 +1136,7 @@ var Flow = class {
       byId.set(child.id, child);
     }
     if (options.length > 0) {
+      this.emit({ type: "choice", group: group.id, options: options.map((o) => ({ id: o.id, eligible: o.eligible })) });
       this.pendingChoice = { groupId: group.id, options, byId };
       return;
     }
@@ -1062,6 +1145,7 @@ var Flow = class {
       this.enterChild(fallback);
       return;
     }
+    this.emit({ type: "dry", group: group.id });
     this.host.onDryChoice?.(group.id);
   }
   // -- Jumps (jump / call-return) ----------------------------------------
@@ -1076,6 +1160,7 @@ var Flow = class {
    * hard-ends the flow regardless of the callstack.
    */
   enterTarget(to, mode) {
+    this.emit({ type: "jump", to, mode });
     if (to === "END") {
       this.flowEnded = true;
       this.stack = [];
@@ -1107,17 +1192,28 @@ var Flow = class {
   }
   // -- Selectors ------------------------------------------------------------
   selectChild(group) {
+    const verdicts = group.children.map((c) => ({ id: c.id, eligible: this.eligible(c) }));
     const eligible = group.children.filter((c) => this.eligible(c));
-    if (eligible.length === 0) return null;
+    const order = group.options?.order ?? "sequential";
+    const exhaust = group.options?.exhaust ?? "once";
+    const trace = (picked) => {
+      this.emit({
+        type: "select",
+        group: group.id,
+        selector: group.selector ?? "default",
+        ...group.selector === "sequence" ? { order, exhaust } : {},
+        children: verdicts,
+        picked: picked?.id ?? null
+      });
+      return picked;
+    };
+    if (eligible.length === 0) return trace(null);
     const st = this.selectorState(group);
     switch (group.selector) {
       case "branch":
-        return eligible[0];
-      case "sequence": {
-        const order = group.options?.order ?? "sequential";
-        const exhaust = group.options?.exhaust ?? "once";
-        return order === "shuffle" ? this.pickShuffle(eligible, exhaust, st) : order === "specificity" ? this.pickSpecificity(eligible, exhaust, st) : this.pickSequential(eligible, exhaust, st);
-      }
+        return trace(eligible[0]);
+      case "sequence":
+        return trace(order === "shuffle" ? this.pickShuffle(eligible, exhaust, st) : order === "specificity" ? this.pickSpecificity(eligible, exhaust, st) : this.pickSequential(eligible, exhaust, st));
       case "run":
       case "choice":
       default:
@@ -1235,7 +1331,10 @@ var Flow = class {
   // -- Effects + expressions ------------------------------------------------
   runEffects(effects) {
     for (const e of effects ?? []) {
-      this.setProperty(e.target, this.evalExpr(e.value));
+      const value = this.evalExpr(e.value);
+      const prev = this.host.logEnabled ? this.getProperty(e.target) : void 0;
+      this.setProperty(e.target, value);
+      this.emit({ type: "write", target: e.target, value, ...prev !== void 0 ? { prev } : {} });
     }
   }
   eligible(node) {
@@ -1379,7 +1478,7 @@ var Flow = class {
   }
   /** The per-flow registry: the NOT-shared `@patter` globals (the shared ones live on the host). */
   freshLocal() {
-    return new import_scoperegistry.ScopeRegistry().defineOwned("patter", this.host.patterLocalDecls);
+    return new import_scoperegistry.ScopeRegistry().defineOwned("patter", this.host.patterLocalDecls, "@patter.");
   }
   /**
    * Seed a scene's `@scene` props (spec §7). The not-shared props seed THIS flow's
@@ -1390,27 +1489,18 @@ var Flow = class {
    */
   seedScene(scene) {
     const shared = this.host.sceneSharedNames.get(scene.id) ?? /* @__PURE__ */ new Set();
+    const props = scene.sceneProps ?? [];
     if (!this.sceneBags.has(scene.id)) {
-      const bag = {};
-      for (const decl of scene.sceneProps ?? []) {
-        const name = decl.name.toLowerCase();
-        if (!shared.has(name)) bag[name] = sceneDefault(decl);
-      }
-      this.sceneBags.set(scene.id, bag);
+      this.sceneBags.set(scene.id, new import_scoperegistry2.PropertyBag(props.filter((d) => !shared.has(d.name.toLowerCase()))));
     }
     if (!this.host.stageBags.has(scene.id)) {
-      const bag = {};
-      for (const decl of scene.sceneProps ?? []) {
-        const name = decl.name.toLowerCase();
-        if (shared.has(name)) bag[name] = sceneDefault(decl);
-      }
-      this.host.stageBags.set(scene.id, bag);
+      this.host.stageBags.set(scene.id, new import_scoperegistry2.PropertyBag(props.filter((d) => shared.has(d.name.toLowerCase()))));
     }
     for (const decl of scene.sceneProps ?? []) {
       if (!decl.temporary) continue;
       const name = decl.name.toLowerCase();
       const bag = shared.has(name) ? this.host.stageBags.get(scene.id) : this.sceneBags.get(scene.id);
-      if (bag) bag[name] = sceneDefault(decl);
+      if (bag) bag.set(name, (0, import_scoperegistry2.defaultFor)(decl));
     }
   }
 };
@@ -1448,47 +1538,13 @@ function deserialiseSelectors(rec) {
 function toDecl(decl) {
   return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default };
 }
-function declDefault(d) {
-  if (d.default !== void 0) return d.default;
-  switch (d.type) {
-    case "number":
-      return 0;
-    case "string":
-      return "";
-    case "flags":
-      return [];
-    case "enum":
-      return d.values?.[0] ?? "";
-    case "quality":
-      return d.stages?.[0] ?? "";
-    default:
-      return false;
-  }
-}
 function toForeignDecl(decl) {
   return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default, writable: decl.writable };
 }
-function hostScopeDefault(decl) {
-  if (decl.default !== void 0) return decl.default;
-  switch (decl.type) {
-    case "boolean":
-      return false;
-    case "number":
-      return 0;
-    case "string":
-      return "";
-    case "flags":
-      return [];
-    case "enum":
-      return decl.values?.[0] ?? "";
-    case "quality":
-      return decl.stages?.[0] ?? "";
-  }
-}
 function selfBackedResolver(decls) {
   const key = (name) => name.toLowerCase();
   const bag = /* @__PURE__ */ new Map();
-  for (const d of decls) bag.set(key(d.name), hostScopeDefault(d));
+  for (const d of decls) bag.set(key(d.name), (0, import_scoperegistry2.defaultFor)(d));
   return {
     get: (name) => bag.get(key(name)),
     set: (name, value) => {
@@ -1496,23 +1552,6 @@ function selfBackedResolver(decls) {
     }
   };
 }
-function sceneDefault(decl) {
-  if (decl.default !== void 0) return decl.default;
-  switch (decl.type) {
-    case "boolean":
-      return false;
-    case "number":
-      return 0;
-    case "string":
-      return "";
-    case "flags":
-      return [];
-    case "enum":
-      return decl.values?.[0] ?? "";
-    case "quality":
-      return decl.stages?.[0] ?? "";
-  }
-}
 function truthy(v) {
   if (typeof v === "boolean") return v;
   if (typeof v === "number") return v !== 0;