@patterkit/runtime 0.19.0 → 0.21.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
@@ -664,8 +680,6 @@ declare class Engine {
      *  across the family 2026-09-05, after a Storylets venue clock and this project's coverage driver
      *  were each refused the one property they existed to move.) */
     setProperty(ref: string, value: ScalarValue): void;
-    /** 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. */
@@ -677,6 +691,11 @@ 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>;
+    /** 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(): 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
@@ -664,8 +680,6 @@ declare class Engine {
      *  across the family 2026-09-05, after a Storylets venue clock and this project's coverage driver
      *  were each refused the one property they existed to move.) */
     setProperty(ref: string, value: ScalarValue): void;
-    /** 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. */
@@ -677,6 +691,11 @@ 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>;
+    /** 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(): 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 };