@patterkit/runtime 0.19.0 → 0.20.0

package/dist/index.d.cts

@@ -127,12 +127,14 @@ interface ChoiceOption {
     gameData?: GameData;
 }
 /**
- * The host's **World Properties** resolver: a `{ get, set? }` the game provides so the story can read
- * (and, if you allow it, write) its `@world.*` values at runtime. Property metadata (types, read-only)
- * comes from the compiled bundle's declared world properties; the values themselves live in the host and
+ * A host scope's resolver: a `{ get, set? }` the game provides so the story can read (and, if you allow
+ * it, write) values the game owns, `@world.*` among them, at runtime. Property metadata (types,
+ * read-only) comes from the compiled bundle's declarations; the values themselves live in the host and
  * are never stored or saved by this engine.
  */
-type WorldResolver = ScopeResolver;
+type HostScope = ScopeResolver;
+/** @deprecated Use {@link HostScope}, the name every Patterplay runtime uses. */
+type WorldResolver = HostScope;
 /** What the engine DECIDED, as opposed to what it produced. A step tells you the line that
  *  played; a trace event tells you why that line and not its siblings - which children were
  *  eligible, where the selector's cursor stood, which choice options were live.
@@ -222,6 +224,8 @@ interface PlayError {
     source?: string;
     message: string;
 }
+/** @deprecated Nothing takes one: a flow has no tap of its own, and `onTrace` takes an
+ *  {@link EngineTraceHandler}. Goes in a later release. */
 type TraceHandler = (event: TraceEvent) => void;
 /** The engine-level tap: every flow's events, tagged with the flow id - one stream for tools. */
 type EngineTraceHandler = (flow: string, event: TraceEvent) => void;
@@ -249,14 +253,18 @@ interface EngineOptions {
     /** Active locale for string lookups (embedded localisation). Defaults to the bundle's default locale.
      *  Ignored by an "ids" bundle, which emits beat IDs for the game to localise itself. */
     locale?: string;
-    /** The host's resolver for **World Properties** (`@world.*`): the values the game owns and the story
-     *  reads. Omit it and the runtime self-backs `@world` from the declared defaults, as a property the
-     *  registry stores and saves. Shared by all flows. A game running several engines registers `@world`
-     *  in its registry itself instead, and no engine is given a resolver. */
-    world?: WorldResolver;
+    /** The host scopes the game binds, by token: for each, a resolver over values the game owns and the
+     *  story reads, such as `{ world: { get, set } }` for **World Properties** (`@world.*`). A declared
+     *  scope left unbound is self-backed from its defaults, as a property the registry stores and saves.
+     *  Shared by all flows. A game running several engines registers its scopes in its registry itself
+     *  instead, and binds none here. The same option on every runtime. */
+    hostScopes?: Record<string, HostScope>;
+    /** @deprecated Use `hostScopes: { world }`, the option every Patterplay runtime takes. Goes in a later
+     *  release. */
+    world?: HostScope;
     /** The game's registry: ONE per game, holding every engine's properties except those the game keeps
      *  itself, saved once. Given one, the engine registers its own scopes in it (`@patter` under `patter`,
-     *  its per-flow and per-scene bags under keys starting `patter/`, and `@world` if `world` is passed),
+     *  its per-flow and per-scene bags under keys starting `patter/`, and each scope `hostScopes` binds),
      *  reads every other scope from it, and `saveGame()` leaves the property values to the game. Host
      *  scopes the bundle declares (`@world`) are then the game's to register: owned if the registry should
      *  store them, foreign if the game keeps them. Omit it and the engine makes its own registry and acts as
@@ -324,8 +332,13 @@ declare class Checkpoint {
 }
 /** Shared, read-mostly context the engine hands to every flow it owns. */
 interface FlowHost {
-    /** True when the run asked for a log; flows skip building entries otherwise. */
+    /** True when the run asked for a log. */
     logEnabled: boolean;
+    /** Each declaration set's quality ladders, built on first use (see `ladders`). */
+    qualityLadders: Map<string, Map<string, readonly string[]>>;
+    /** True when anything takes the decisions: the log, or an {@link Engine.onTrace} handler. Flows skip
+     *  the work only a decision needs (a `run` walk's entry, a write's previous value) otherwise. */
+    tracing: boolean;
     /** A flow's events reach the ENGINE's stream through here, tagged with the flow id. */
     emitEngine: (flow: string, event: TraceEvent, scene?: string) => void;
     bundle: Bundle;
@@ -419,7 +432,7 @@ declare class Engine {
     private readonly sceneGameIdToId;
     private readonly blockGameIdToId;
     /** 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. */
     private readonly creationOptions;
     /** The run's ordered stream: every flow's events, each naming its flow. Empty and
      *  unwritten unless `options.log` asked for it. */
@@ -433,6 +446,9 @@ declare class Engine {
     /** True for a source-only DEBUG build: the embedded strings are the source language (for debugging),
      *  not a shippable localised build. An IDs-only ship build is `false`. */
     get isSourceDebug(): boolean;
+    /** 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(): string;
     /**
      * 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
@@ -677,6 +693,9 @@ declare class Engine {
      *  retained. Returns its own unsubscribe. */
     onTrace(handler: EngineTraceHandler): () => void;
     private emitEngine;
+    /** 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(): Record<string, number>;
     listProperties(): PropertyRow[];
     private splitShared;
     /** The shared `@patter` values alone, as `{ patter: {...} }`.
@@ -744,15 +763,20 @@ declare class Flow {
     /** The stage ladder of `@scope.name` when it is a declared quality, else undefined. Names compare
      *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
     private stagesFor;
-    /** Begin this flow at a scene (and optionally a specific block within it). */
-    start(sceneId?: string, blockId?: string): void;
+    /** 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?: string, blockId?: string): void;
     /**
      * 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?: string, blockId?: string): void;
+    /** @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?: string, blockId?: string): void;
     /**
      * Send this flow's cursor to an ADDRESS, exactly as an authored `go` jump would: the target scene's
      * `onEntry` effects run, entering counts as a visit, and the callstack is REPLACED - any pending
@@ -782,6 +806,13 @@ declare class Flow {
      * cannot quietly mutate the world. Terminal: unlike ending, a close is never revived.
      */
     close(): void;
+    /**
+     * 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.
+     */
+    private clearPending;
     /** Inside a checkpoint, the first change to this flow records its cursor and PRNG, so a rollback can
      *  put them back: a handful of fields and a copy of the call stack (a few frames), never its history.
      *  Its visits, selector cursors, and property values are recorded change by change as they happen. */
@@ -820,9 +851,11 @@ declare class Flow {
     log(): readonly LogEntry[];
     /** Drop the retained entries. `seq` keeps counting, so order survives a clear. */
     clearLog(): void;
-    /** 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. */
     private emit;
+    /** How many times this flow has entered each node, by node id. */
+    getVisitCounts(): Record<string, number>;
     /** The options of a pending choice (empty when not at a choice point). */
     getChoices(): ChoiceOption[];
     /** Pick an eligible option by id; the next `advance()` runs it. */
@@ -1139,4 +1172,4 @@ declare function effectiveGameData(fields: GameDataField[], node: GameData | und
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, Checkpoint, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, type FlatBeat, Flow, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PlayError, type PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, Checkpoint, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, type FlatBeat, Flow, type GameDataFieldSummary, type GameDataSummary, type HostScope, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PlayError, type PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };

package/dist/index.d.ts

@@ -127,12 +127,14 @@ interface ChoiceOption {
     gameData?: GameData;
 }
 /**
- * The host's **World Properties** resolver: a `{ get, set? }` the game provides so the story can read
- * (and, if you allow it, write) its `@world.*` values at runtime. Property metadata (types, read-only)
- * comes from the compiled bundle's declared world properties; the values themselves live in the host and
+ * A host scope's resolver: a `{ get, set? }` the game provides so the story can read (and, if you allow
+ * it, write) values the game owns, `@world.*` among them, at runtime. Property metadata (types,
+ * read-only) comes from the compiled bundle's declarations; the values themselves live in the host and
  * are never stored or saved by this engine.
  */
-type WorldResolver = ScopeResolver;
+type HostScope = ScopeResolver;
+/** @deprecated Use {@link HostScope}, the name every Patterplay runtime uses. */
+type WorldResolver = HostScope;
 /** What the engine DECIDED, as opposed to what it produced. A step tells you the line that
  *  played; a trace event tells you why that line and not its siblings - which children were
  *  eligible, where the selector's cursor stood, which choice options were live.
@@ -222,6 +224,8 @@ interface PlayError {
     source?: string;
     message: string;
 }
+/** @deprecated Nothing takes one: a flow has no tap of its own, and `onTrace` takes an
+ *  {@link EngineTraceHandler}. Goes in a later release. */
 type TraceHandler = (event: TraceEvent) => void;
 /** The engine-level tap: every flow's events, tagged with the flow id - one stream for tools. */
 type EngineTraceHandler = (flow: string, event: TraceEvent) => void;
@@ -249,14 +253,18 @@ interface EngineOptions {
     /** Active locale for string lookups (embedded localisation). Defaults to the bundle's default locale.
      *  Ignored by an "ids" bundle, which emits beat IDs for the game to localise itself. */
     locale?: string;
-    /** The host's resolver for **World Properties** (`@world.*`): the values the game owns and the story
-     *  reads. Omit it and the runtime self-backs `@world` from the declared defaults, as a property the
-     *  registry stores and saves. Shared by all flows. A game running several engines registers `@world`
-     *  in its registry itself instead, and no engine is given a resolver. */
-    world?: WorldResolver;
+    /** The host scopes the game binds, by token: for each, a resolver over values the game owns and the
+     *  story reads, such as `{ world: { get, set } }` for **World Properties** (`@world.*`). A declared
+     *  scope left unbound is self-backed from its defaults, as a property the registry stores and saves.
+     *  Shared by all flows. A game running several engines registers its scopes in its registry itself
+     *  instead, and binds none here. The same option on every runtime. */
+    hostScopes?: Record<string, HostScope>;
+    /** @deprecated Use `hostScopes: { world }`, the option every Patterplay runtime takes. Goes in a later
+     *  release. */
+    world?: HostScope;
     /** The game's registry: ONE per game, holding every engine's properties except those the game keeps
      *  itself, saved once. Given one, the engine registers its own scopes in it (`@patter` under `patter`,
-     *  its per-flow and per-scene bags under keys starting `patter/`, and `@world` if `world` is passed),
+     *  its per-flow and per-scene bags under keys starting `patter/`, and each scope `hostScopes` binds),
      *  reads every other scope from it, and `saveGame()` leaves the property values to the game. Host
      *  scopes the bundle declares (`@world`) are then the game's to register: owned if the registry should
      *  store them, foreign if the game keeps them. Omit it and the engine makes its own registry and acts as
@@ -324,8 +332,13 @@ declare class Checkpoint {
 }
 /** Shared, read-mostly context the engine hands to every flow it owns. */
 interface FlowHost {
-    /** True when the run asked for a log; flows skip building entries otherwise. */
+    /** True when the run asked for a log. */
     logEnabled: boolean;
+    /** Each declaration set's quality ladders, built on first use (see `ladders`). */
+    qualityLadders: Map<string, Map<string, readonly string[]>>;
+    /** True when anything takes the decisions: the log, or an {@link Engine.onTrace} handler. Flows skip
+     *  the work only a decision needs (a `run` walk's entry, a write's previous value) otherwise. */
+    tracing: boolean;
     /** A flow's events reach the ENGINE's stream through here, tagged with the flow id. */
     emitEngine: (flow: string, event: TraceEvent, scene?: string) => void;
     bundle: Bundle;
@@ -419,7 +432,7 @@ declare class Engine {
     private readonly sceneGameIdToId;
     private readonly blockGameIdToId;
     /** 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. */
     private readonly creationOptions;
     /** The run's ordered stream: every flow's events, each naming its flow. Empty and
      *  unwritten unless `options.log` asked for it. */
@@ -433,6 +446,9 @@ declare class Engine {
     /** True for a source-only DEBUG build: the embedded strings are the source language (for debugging),
      *  not a shippable localised build. An IDs-only ship build is `false`. */
     get isSourceDebug(): boolean;
+    /** 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(): string;
     /**
      * 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
@@ -677,6 +693,9 @@ declare class Engine {
      *  retained. Returns its own unsubscribe. */
     onTrace(handler: EngineTraceHandler): () => void;
     private emitEngine;
+    /** 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(): Record<string, number>;
     listProperties(): PropertyRow[];
     private splitShared;
     /** The shared `@patter` values alone, as `{ patter: {...} }`.
@@ -744,15 +763,20 @@ declare class Flow {
     /** The stage ladder of `@scope.name` when it is a declared quality, else undefined. Names compare
      *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
     private stagesFor;
-    /** Begin this flow at a scene (and optionally a specific block within it). */
-    start(sceneId?: string, blockId?: string): void;
+    /** 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?: string, blockId?: string): void;
     /**
      * 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?: string, blockId?: string): void;
+    /** @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?: string, blockId?: string): void;
     /**
      * Send this flow's cursor to an ADDRESS, exactly as an authored `go` jump would: the target scene's
      * `onEntry` effects run, entering counts as a visit, and the callstack is REPLACED - any pending
@@ -782,6 +806,13 @@ declare class Flow {
      * cannot quietly mutate the world. Terminal: unlike ending, a close is never revived.
      */
     close(): void;
+    /**
+     * 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.
+     */
+    private clearPending;
     /** Inside a checkpoint, the first change to this flow records its cursor and PRNG, so a rollback can
      *  put them back: a handful of fields and a copy of the call stack (a few frames), never its history.
      *  Its visits, selector cursors, and property values are recorded change by change as they happen. */
@@ -820,9 +851,11 @@ declare class Flow {
     log(): readonly LogEntry[];
     /** Drop the retained entries. `seq` keeps counting, so order survives a clear. */
     clearLog(): void;
-    /** 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. */
     private emit;
+    /** How many times this flow has entered each node, by node id. */
+    getVisitCounts(): Record<string, number>;
     /** The options of a pending choice (empty when not at a choice point). */
     getChoices(): ChoiceOption[];
     /** Pick an eligible option by id; the next `advance()` runs it. */
@@ -1139,4 +1172,4 @@ declare function effectiveGameData(fields: GameDataField[], node: GameData | und
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, Checkpoint, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, type FlatBeat, Flow, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PlayError, type PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, Checkpoint, type ChoiceOption, Engine, type EngineLogEntry, type EngineOptions, type EngineTraceHandler, type FlatBeat, Flow, type GameDataFieldSummary, type GameDataSummary, type HostScope, type HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PlayError, type PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };

package/dist/index.js

@@ -81,7 +81,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 +133,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 +158,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,
@@ -180,6 +181,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 +208,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 +333,7 @@ var Engine = class _Engine {
       });
     }
     this.flowsById.set(id, flow);
-    flow.start(sceneId, blockId);
+    flow.begin(sceneId, blockId);
     return flow;
   }
   /**
@@ -690,7 +697,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) {
@@ -727,13 +734,22 @@ 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);
+  }
   listProperties() {
     return this.host.patterSharedDecls.map((d) => ({
       name: d.name,
@@ -938,19 +954,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 +980,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 +1005,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 +1037,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 +1052,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 +1080,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 +1185,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 +1221,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 +1246,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 +1442,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 +1451,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 +1466,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 +1503,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 +1668,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 +1691,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);
@@ -1946,6 +1978,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 };
 }