@patterkit/runtime 0.19.0 → 0.21.0

package/dist/index.js

@@ -43,6 +43,18 @@ function buildTagIndex(bundle) {
 // src/engine.ts
 import { SAVE_VERSION } from "@patterkit/model";
 var astCache = /* @__PURE__ */ new WeakMap();
+var tagIndexCache = /* @__PURE__ */ new WeakMap();
+function tagIndexFor(bundle) {
+  let index = tagIndexCache.get(bundle);
+  if (!index) {
+    index = buildTagIndex(bundle);
+    tagIndexCache.set(bundle, index);
+  }
+  return index;
+}
+function tagsOf(host, id) {
+  return host.tagIndex.get(id)?.slice();
+}
 var OWNER = "Patter";
 var esc = (id) => id.replace(/%/g, "%25").replace(/\//g, "%2F");
 var OWNS_REGISTRY = /* @__PURE__ */ Symbol("ownsRegistry");
@@ -81,7 +93,7 @@ var Engine = class _Engine {
   sceneGameIdToId = /* @__PURE__ */ new Map();
   blockGameIdToId = /* @__PURE__ */ new Map();
   /** 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. */
+   *  engine keeps the same host scopes, 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. */
@@ -133,12 +145,12 @@ var Engine = class _Engine {
       registry.mountOwned("patter", patterBag, { owner: OWNER });
       registered.push("patter");
       const hostBound = /* @__PURE__ */ new Set();
-      if (options.world) {
-        const worldSpec = bundle.scopeRegistry?.scopes.find((s) => s.token === "world");
-        const decls = (worldSpec?.declarations ?? []).map(toForeignDecl);
-        registry.defineForeign("world", options.world, decls, { writable: worldSpec?.writable ?? true, owner: OWNER });
-        registered.push("world");
-        hostBound.add("world");
+      for (const [token, resolver] of Object.entries(boundScopes(options))) {
+        const spec = bundle.scopeRegistry?.scopes.find((s) => s.token === token);
+        const decls = (spec?.declarations ?? []).map(toForeignDecl);
+        registry.defineForeign(token, resolver, decls, { writable: spec?.writable ?? true, owner: OWNER });
+        registered.push(token);
+        hostBound.add(token);
       }
       for (const spec of ownsRegistry ? bundle.scopeRegistry?.scopes ?? [] : []) {
         if (hostBound.has(spec.token) || registry.has(spec.token)) continue;
@@ -158,6 +170,7 @@ var Engine = class _Engine {
     }
     this.host = {
       logEnabled: options.log ?? false,
+      tracing: options.log ?? false,
       emitEngine: (flow, event, scene) => this.emitEngine(flow, event, scene),
       bundle,
       emitIds,
@@ -170,7 +183,7 @@ var Engine = class _Engine {
       sceneGameIdToId: this.sceneGameIdToId,
       blockGameIdToId: this.blockGameIdToId,
       // same instances the engine resolves with
-      tagIndex: buildTagIndex(bundle),
+      tagIndex: tagIndexFor(bundle),
       registry,
       ownsRegistry,
       patterBag,
@@ -180,6 +193,7 @@ var Engine = class _Engine {
       patterSharedNames,
       sceneSharedNames,
       sharedVisits: /* @__PURE__ */ new Map(),
+      qualityLadders: /* @__PURE__ */ new Map(),
       sharedSelectors: /* @__PURE__ */ new Map(),
       stageBags: /* @__PURE__ */ new Map(),
       journal: null,
@@ -206,6 +220,11 @@ var Engine = class _Engine {
   get isSourceDebug() {
     return this.sourceDebug;
   }
+  /** The bundle's build identity (its content hash), the one a debug link handshakes with, or an empty
+   *  string for a bundle compiled without one. */
+  get buildId() {
+    return this.host.bundle.content?.hash ?? "";
+  }
   /**
    * Switch the active locale LIVE - a real game's "language" setting can change mid-session. Subsequent
    * string lookups (new beats, re-resolved character names, `{@ref}` interpolation) render in the new
@@ -326,7 +345,7 @@ var Engine = class _Engine {
       });
     }
     this.flowsById.set(id, flow);
-    flow.start(sceneId, blockId);
+    flow.begin(sceneId, blockId);
     return flow;
   }
   /**
@@ -423,18 +442,18 @@ var Engine = class _Engine {
    * delivered step carries. Empty array for an unknown id or a beat with no tags anywhere up the chain.
    */
   tagsForBeat(beatId) {
-    return this.host.tagIndex.get(beatId) ?? [];
+    return tagsOf(this.host, beatId) ?? [];
   }
   /** A scene's own tags (by internal id or gameId address). Empty when none / unknown. */
   tagsForScene(sceneRef) {
     const id = this.resolveSceneRef(sceneRef);
-    return (id != null ? this.host.tagIndex.get(id) : void 0) ?? [];
+    return (id != null ? tagsOf(this.host, id) : void 0) ?? [];
   }
   /** A block's accumulated tags (scene + block), by scene + block ref (id or gameId). Empty when none / unknown. */
   tagsForBlock(sceneRef, blockRef) {
     const sceneId = this.resolveSceneRef(sceneRef);
     const id = this.resolveBlockRef(sceneId, blockRef);
-    return (id != null ? this.host.tagIndex.get(id) : void 0) ?? [];
+    return (id != null ? tagsOf(this.host, id) : void 0) ?? [];
   }
   /**
    * A scene's own author gameData (by internal id or gameId address): the RAW sparse overrides, exactly
@@ -553,7 +572,7 @@ var Engine = class _Engine {
   }
   /** One beat's static data (source locale), the same shape a delivered step carries. */
   beatInfo(beat) {
-    const tags = this.host.tagIndex.get(beat.id);
+    const tags = tagsOf(this.host, beat.id);
     const info = { id: beat.id, kind: beat.kind };
     if (beat.kind === "line") {
       if (beat.character !== void 0) {
@@ -573,7 +592,7 @@ var Engine = class _Engine {
   }
   /** A `{ tags }` fragment for an id, present only when the id has accumulated tags (keeps output tidy). */
   tagsField(id) {
-    const tags = this.host.tagIndex.get(id);
+    const tags = tagsOf(this.host, id);
     return tags && tags.length ? { tags } : {};
   }
   /** Retrieve an open flow by id (undefined if none / closed). */
@@ -690,7 +709,7 @@ var Engine = class _Engine {
     for (const s of this.host.stageBags.keys()) reg.remove(keys.stage(s), { keep });
     this.host.stageBags.clear();
     for (const t of ["patter", ...this.host.hostScopes]) if (reg.has(t)) reg.remove(t, { keep });
-    if (this.creationOptions.world && reg.has("world")) reg.remove("world");
+    for (const t of Object.keys(boundScopes(this.creationOptions))) if (reg.has(t)) reg.remove(t);
   }
   /** Read a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
   getProperty(ref) {
@@ -710,8 +729,6 @@ var Engine = class _Engine {
     this.host.registry.set(scope, name, value, { host: true });
     if (this.host.journal && prev !== void 0) this.host.journal.undo.push(() => this.host.registry.set(scope, name, prev, { host: true }));
   }
-  /** 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. */
@@ -727,13 +744,24 @@ var Engine = class _Engine {
    *  retained. Returns its own unsubscribe. */
   onTrace(handler) {
     this.engineTraceHandlers.add(handler);
-    return () => this.engineTraceHandlers.delete(handler);
+    this.host.tracing = true;
+    return () => {
+      this.engineTraceHandlers.delete(handler);
+      this.host.tracing = this.host.logEnabled || this.engineTraceHandlers.size > 0;
+    };
   }
   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.engineSeq++, ...scene ? { scene } : {} });
   }
+  /** How many times each node has been entered across every flow, by node id: the shared count. With a
+   *  flow's own {@link Flow.getVisitCounts}, every visit count the run keeps, read without a save. */
+  getVisitCounts() {
+    return Object.fromEntries(this.host.sharedVisits);
+  }
+  /** The shared `@patter` properties, for a live state inspector: each with its ref, type, current
+   *  value, declared default (for reset), and enum options. Every runtime has the same call. */
   listProperties() {
     return this.host.patterSharedDecls.map((d) => ({
       name: d.name,
@@ -938,19 +966,21 @@ var Flow = class {
    *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
   stagesFor(scope, name) {
     const key = name.toLowerCase();
-    const fromDecls = (decls) => decls?.find((d) => d.name.toLowerCase() === key && d.type === "quality")?.stages;
     if (scope === "patter") {
-      return fromDecls(this.host.patterSharedDecls) ?? fromDecls(this.host.patterLocalDecls);
+      return ladders(this.host, "patter", () => [...this.host.patterSharedDecls, ...this.host.patterLocalDecls]).get(key);
     }
     if (scope === "scene") {
-      const scene = this.currentSceneId != null ? this.host.bundle.scenes[this.currentSceneId] : void 0;
-      return fromDecls(scene?.sceneProps);
+      const sceneId = this.currentSceneId;
+      if (sceneId == null) return void 0;
+      return ladders(this.host, `scene/${sceneId}`, () => this.host.bundle.scenes[sceneId]?.sceneProps).get(key);
     }
-    return this.registryQualities?.(scope, name) ?? fromDecls(this.host.bundle.scopeRegistry?.scopes.find((s) => s.token === scope)?.declarations);
+    return this.registryQualities?.(scope, name) ?? ladders(this.host, `host/${scope}`, () => this.host.bundle.scopeRegistry?.scopes.find((s) => s.token === scope)?.declarations).get(key);
   }
   // -- Host API -------------------------------------------------------------
-  /** Begin this flow at a scene (and optionally a specific block within it). */
-  start(sceneId, blockId) {
+  /** Begin this flow at a scene (and optionally a specific block within it). The engine's own entry point:
+   *  openFlow and a goto on an unstarted flow begin a flow here. A game calls {@link reset}.
+   *  @internal */
+  begin(sceneId, blockId) {
     if (this.host.journal && !this.host.journal.opened.has(this)) throw new Error("a flow can't be started or reset while a checkpoint is open");
     this.releaseBags(false);
     this.host.registry.discardParked(keys.flow(this.id));
@@ -962,7 +992,7 @@ var Flow = class {
     this.flowEnded = false;
     this.activeSnippet = null;
     this.beatIndex = 0;
-    this.pendingChoice = null;
+    this.clearPending();
     this.started = true;
     if (blockId) {
       const loc = this.host.blockIndex.get(blockId);
@@ -987,10 +1017,15 @@ var Flow = class {
    * Forget everything in this flow and begin again - its per-flow state (not-shared
    * `@patter` globals + `@scene` props), cursor, callstack, selector cursors, and
    * visit counts. Shared state (shared `@patter` / `@scene`, world visit counts) is
-   * untouched. A clearer-named alias of `start()`.
+   * untouched. The one public way to begin a flow again (openFlow begins a new one).
    */
   reset(sceneId, blockId) {
-    this.start(sceneId, blockId);
+    this.begin(sceneId, blockId);
+  }
+  /** @deprecated Use {@link reset}, the one public name for beginning a flow again on every runtime. `start`
+   *  was the same call under a second name, and goes in a later release. */
+  start(sceneId, blockId) {
+    this.reset(sceneId, blockId);
   }
   /**
    * Send this flow's cursor to an ADDRESS, exactly as an authored `go` jump would: the target scene's
@@ -1014,9 +1049,7 @@ var Flow = class {
     this.touch();
     if (scene === "END") {
       this.started = true;
-      this.pendingChoice = null;
-      this.pendingPrompt = null;
-      this.pendingPromptOwnerId = null;
+      this.clearPending();
       this.activeSnippet = null;
       this.beatIndex = 0;
       this.flowEnded = true;
@@ -1031,12 +1064,10 @@ var Flow = class {
       if (blockId === void 0) return false;
     }
     if (!this.started) {
-      this.start(sceneId, blockId);
+      this.begin(sceneId, blockId);
       return true;
     }
-    this.pendingChoice = null;
-    this.pendingPrompt = null;
-    this.pendingPromptOwnerId = null;
+    this.clearPending();
     this.activeSnippet = null;
     this.beatIndex = 0;
     this.flowEnded = false;
@@ -1061,6 +1092,15 @@ var Flow = class {
     this.stack = [];
     this.activeSnippet = null;
     this.beatIndex = 0;
+    this.clearPending();
+  }
+  /**
+   * Drop everything waiting to be delivered: an open choice, and a chosen option's prompt still to be
+   * replayed. Every move that abandons the flow's place (start and reset, goto, close) does this, so none
+   * leaves a stale prompt behind. start() cleared only the choice, so a reset between choose() and the
+   * next advance() replayed the abandoned run's prompt as the new run's first beat.
+   */
+  clearPending() {
     this.pendingChoice = null;
     this.pendingPrompt = null;
     this.pendingPromptOwnerId = null;
@@ -1157,7 +1197,7 @@ var Flow = class {
       }
       const from = frame.index;
       while (frame.index < children.length && !this.eligible(children[frame.index])) frame.index++;
-      if (this.host.logEnabled && frame.index !== from) {
+      if (this.host.tracing && frame.index !== from) {
         this.emit({
           type: "select",
           group: frame.containerId,
@@ -1193,14 +1233,18 @@ var Flow = class {
   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. */
+  /** Record one decision, on this flow's log and the engine's, and hand it to any `onTrace`. Each call
+   *  site checks `host.tracing` first, so with nothing logging or tracing 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 } : {} });
   }
+  /** How many times this flow has entered each node, by node id. */
+  getVisitCounts() {
+    return Object.fromEntries(this.visitCounts);
+  }
   /** The options of a pending choice (empty when not at a choice point). */
   getChoices() {
     return this.pendingChoice?.options ?? [];
@@ -1214,7 +1258,7 @@ var Flow = class {
     if (!option.eligible) throw new Error(`choice option is not eligible: ${id}`);
     this.touch();
     const node = choice.byId.get(id);
-    this.emit({ type: "chose", group: choice.groupId, option: id });
+    if (this.host.tracing) this.emit({ type: "chose", group: choice.groupId, option: id });
     this.pendingChoice = null;
     const authored = this.host.replayPromptOnChoose ? this.authoredPromptOf(node) : void 0;
     this.pendingPrompt = authored && option.prompt ? { beat: authored, shown: { ...option.prompt } } : null;
@@ -1410,7 +1454,7 @@ var Flow = class {
       byId.set(child.id, child);
     }
     if (options.some((o) => o.eligible)) {
-      this.emit({ type: "choice", group: group.id, options: options.map((o) => ({ id: o.id, eligible: o.eligible })) });
+      if (this.host.tracing) 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;
     }
@@ -1419,7 +1463,7 @@ var Flow = class {
       this.enterChild(fallback);
       return;
     }
-    this.emit({ type: "dry", group: group.id });
+    if (this.host.tracing) this.emit({ type: "dry", group: group.id });
     this.host.onDryChoice?.(group.id);
   }
   // -- Jumps (jump / call-return) ----------------------------------------
@@ -1434,7 +1478,7 @@ var Flow = class {
    * hard-ends the flow regardless of the callstack.
    */
   enterTarget(to, mode) {
-    this.emit({ type: "jump", to, mode });
+    if (this.host.tracing) this.emit({ type: "jump", to, mode });
     if (to === "END") {
       this.flowEnded = true;
       this.stack = [];
@@ -1471,7 +1515,7 @@ var Flow = class {
     const order = group.options?.order ?? "sequential";
     const exhaust = group.options?.exhaust ?? "once";
     const trace = (picked) => {
-      this.emit({
+      if (this.host.tracing) this.emit({
         type: "select",
         group: group.id,
         selector: group.selector ?? "default",
@@ -1636,9 +1680,9 @@ var Flow = class {
       let value;
       try {
         value = this.evalExpr(e.value);
-        const prev = this.host.logEnabled ? this.getProperty(e.target) : void 0;
+        const prev = this.host.tracing ? this.getProperty(e.target) : void 0;
         this.writeProperty(e.target, value, false);
-        this.emit({ type: "write", target: e.target, value, ...prev !== void 0 ? { prev } : {} });
+        if (this.host.tracing) this.emit({ type: "write", target: e.target, value, ...prev !== void 0 ? { prev } : {} });
       } catch (err) {
         this.reportError("effect", owner, e.value, err);
       }
@@ -1659,7 +1703,7 @@ var Flow = class {
     const message = err instanceof Error ? err.message : String(err);
     const source = expr?.src;
     this.host.onError({ flow: this.id, kind, node, ...source ? { source } : {}, message });
-    this.emit({ type: "diagnostic", kind, node, ...source ? { source } : {}, message });
+    if (this.host.tracing) this.emit({ type: "diagnostic", kind, node, ...source ? { source } : {}, message });
   }
   evalExpr(expr) {
     return evaluate(this.conditionAst(expr), this.context(), patterDialect);
@@ -1705,7 +1749,7 @@ var Flow = class {
   };
   // -- Strings / beats ------------------------------------------------------
   beatResult(beat) {
-    const tags = this.host.tagIndex.get(beat.id);
+    const tags = tagsOf(this.host, beat.id);
     const withTags = tags && tags.length ? { tags } : {};
     switch (beat.kind) {
       case "gameEvent":
@@ -1772,7 +1816,7 @@ var Flow = class {
   /** A replayed prompt as a step: the beat's id, gameData, and tags, and the text and speaker fields the
    *  choice showed. */
   promptResult(beat, shown) {
-    const tags = this.host.tagIndex.get(beat.id);
+    const tags = tagsOf(this.host, beat.id);
     const withTags = tags && tags.length ? { tags } : {};
     if (shown.kind === "text") return { type: "text", id: beat.id, text: shown.text, gameData: beat.gameData, ...withTags };
     return {
@@ -1946,6 +1990,21 @@ function mountClaims(registry, key, bag, ask) {
 function toDecl(decl) {
   return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default };
 }
+function boundScopes(options) {
+  return { ...options.world ? { world: options.world } : {}, ...options.hostScopes };
+}
+function ladders(host, cacheKey, decls) {
+  let found = host.qualityLadders.get(cacheKey);
+  if (!found) {
+    found = /* @__PURE__ */ new Map();
+    for (const d of decls() ?? []) {
+      const k = d.name.toLowerCase();
+      if (d.type === "quality" && d.stages && !found.has(k)) found.set(k, d.stages);
+    }
+    host.qualityLadders.set(cacheKey, found);
+  }
+  return found;
+}
 function toForeignDecl(decl) {
   return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default, writable: decl.writable };
 }