@patterkit/runtime 0.7.1 → 0.9.0

package/dist/index.js

@@ -1,7 +1,8 @@
 // src/engine.ts
-import { evaluate, deserialiseAst } from "@wildwinter/expr";
+import { evaluate, deserialiseAst, makePrng, toUint32 } from "@wildwinter/expr";
 import { matchedSpecificity as scoreSpecificity } from "@wildwinter/expr-specificity";
 import { ScopeRegistry } from "@wildwinter/scoperegistry";
+import { defaultFor, PropertyBag } from "@wildwinter/scoperegistry";
 import { patterDialect, interpolate, splitRef, stripCaptions } from "@patterkit/dialect";
 import { walkNodes, effectiveGameId, castStringKey, DEFAULT_CAPTION_DELIMITERS, DEFAULT_CAPTION_CHARACTER } from "@patterkit/model";
 
@@ -60,6 +61,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;
@@ -95,7 +100,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 ScopeRegistry().defineOwned("patter", patterSharedDecls);
+    const shared = new ScopeRegistry().defineOwned("patter", patterSharedDecls, "@patter.");
     const hostBound = /* @__PURE__ */ new Set();
     if (options.world) {
       const worldSpec = bundle.scopeRegistry?.scopes.find((s) => s.token === "world");
@@ -114,6 +119,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,
@@ -488,14 +495,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: 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
@@ -528,7 +565,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
     };
   }
@@ -541,7 +578,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 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);
@@ -584,6 +627,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),
@@ -597,13 +641,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
@@ -612,10 +656,13 @@ 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;
-    this.rngState = seed >>> 0;
+    this.rngState = toUint32(seed);
     this.local = this.freshLocal();
     const scopes = { ...host.shared.toEvalContext().scopes };
     scopes["patter"] = this.patterResolver;
@@ -837,7 +884,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;
@@ -846,6 +903,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 ?? [];
   }
@@ -857,6 +932,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;
@@ -890,7 +966,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: {
@@ -913,7 +989,7 @@ var Flow = class {
   }
   /** @internal Restore this flow from a snapshot. */
   restore(snap) {
-    this.rngState = snap.rngState >>> 0;
+    this.rngState = toUint32(snap.rngState);
     this.visitCounts = new Map(Object.entries(snap.visits ?? {}));
     const c = snap.cursor;
     this.started = true;
@@ -928,7 +1004,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 PropertyBag(decls);
+      bag.load(values);
+      return [s, bag];
+    }));
     this.local = this.freshLocal();
     this.local.load(snap.scopes);
     this.activeSnippet = null;
@@ -1022,6 +1104,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;
     }
@@ -1030,6 +1113,7 @@ var Flow = class {
       this.enterChild(fallback);
       return;
     }
+    this.emit({ type: "dry", group: group.id });
     this.host.onDryChoice?.(group.id);
   }
   // -- Jumps (jump / call-return) ----------------------------------------
@@ -1044,6 +1128,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 = [];
@@ -1075,17 +1160,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:
@@ -1203,7 +1299,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) {
@@ -1228,14 +1327,19 @@ var Flow = class {
     this.visitCounts.set(id, (this.visitCounts.get(id) ?? 0) + 1);
     this.host.sharedVisits.set(id, (this.host.sharedVisits.get(id) ?? 0) + 1);
   }
-  /** Next float in [0, 1): the shared custom PRNG, or this flow's serialisable mulberry32. */
+  /** Next float in [0, 1): the shared custom PRNG, or this flow's serialisable mulberry32.
+   *
+   *  The mixing is @wildwinter/expr's makePrng, not a copy inline here. It is a
+   *  fixed published algorithm that both product families need and neither
+   *  owns, and it existed thirteen times across the two of them. `rngState` is
+   *  still the serialisable position, so saves are unaffected: a generator is
+   *  made from it, drawn once, and the new state written back. */
   rng = () => {
     if (this.host.customRng) return this.host.customRng();
-    const a = this.rngState + 1831565813 | 0;
-    this.rngState = a;
-    let t = Math.imul(a ^ a >>> 15, 1 | a);
-    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
-    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+    const prng = makePrng(this.rngState);
+    const draw = prng.next();
+    this.rngState = prng.state();
+    return draw;
   };
   // -- Strings / beats ------------------------------------------------------
   beatResult(beat) {
@@ -1342,7 +1446,7 @@ var Flow = class {
   }
   /** The per-flow registry: the NOT-shared `@patter` globals (the shared ones live on the host). */
   freshLocal() {
-    return new ScopeRegistry().defineOwned("patter", this.host.patterLocalDecls);
+    return new ScopeRegistry().defineOwned("patter", this.host.patterLocalDecls, "@patter.");
   }
   /**
    * Seed a scene's `@scene` props (spec §7). The not-shared props seed THIS flow's
@@ -1353,27 +1457,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 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 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, defaultFor(decl));
     }
   }
 };
@@ -1411,47 +1506,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), defaultFor(d));
   return {
     get: (name) => bag.get(key(name)),
     set: (name, value) => {
@@ -1459,23 +1520,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;