@patterkit/runtime 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,626 @@
+import { ScalarValue } from '@wildwinter/expr';
+import { ScopeResolver, ScopeRegistry, ScopeDeclaration } from '@wildwinter/scoperegistry';
+import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, PropertyType, GameDataField, GameDataNodeKind } from '@patterkit/model';
+export { Bundle } from '@patterkit/model';
+
+type SelectableNode = CompiledGroup | CompiledSnippet;
+/** A property-state snapshot: owned scope -> property name -> value. */
+type EngineSave = Record<string, Record<string, ScalarValue>>;
+/** Serialised `sequence` selector visit state for one group (spec §4 / §7). */
+interface SelectorSnapshot {
+    seq?: number;
+    bag?: string[];
+    last?: string;
+}
+/** One entry on a flow's continuation stack: a position within a container's children. */
+interface StackFrame {
+    sceneId: string;
+    /** A block id or a run-group id (both are sequential containers). */
+    containerId: string;
+    index: number;
+    /** SNAPSHOT-ONLY (never set on a live frame): the id of the child at `index` when the save was
+     *  taken. On restore the child is re-found by this id, so a save survives siblings being inserted,
+     *  removed, or reordered before the cursor (live bundle refresh / patched-game saves). Absent (an
+     *  older save, or a frame saved at its container's end) falls back to the raw `index`. */
+    nextId?: string;
+}
+/** The serialised cursor + scopes + PRNG of a single flow. */
+interface FlowSnapshot {
+    /** This flow's owned-scope values = the NOT-shared `@patter` globals (under token "patter"). */
+    scopes: EngineSave;
+    /** Per-scene NOT-shared `@scene` bags (scene id -> name -> value); persist across re-entries (spec §7). */
+    sceneBags: Record<string, Record<string, ScalarValue>>;
+    /** This flow's built-in PRNG position (mulberry32 state). */
+    rngState: number;
+    /** This flow's per-node entry counts (node id -> times entered by this flow). */
+    visits: Record<string, number>;
+    cursor: {
+        flowEnded: boolean;
+        currentSceneId: string | null;
+        /** The continuation stack (call frames + the active block run). */
+        stack: StackFrame[];
+        activeSnippetId: string | null;
+        beatIndex: number;
+        /** The pending choice's exact option set, REPLAYED on load (schema 9.3). */
+        pendingChoice: SavedChoice | null;
+        /** The chosen option owning a prompt still to be replayed (save taken between choose + advance).
+         *  Optional / absent in older saves -> no pending prompt. */
+        pendingPromptOwnerId?: string | null;
+        /** This flow's `sequence` selector cursors. */
+        selectors: Record<string, SelectorSnapshot>;
+    };
+}
+/**
+ * A pending choice as saved: the option set the player was shown, restored
+ * verbatim - re-deriving on load would re-evaluate conditions (consuming PRNG
+ * draws a second time) and could mutate the choice under the player.
+ */
+interface SavedChoice {
+    groupId: string;
+    options: ChoiceOption[];
+}
+/** A full resumable save-game: shared `@patter` state + every live flow. */
+interface SaveGame {
+    version: number;
+    /** Shared `@patter` globals (owned scope "patter"). */
+    shared: EngineSave;
+    /** World-wide per-node entry counts (node id -> times entered by any flow). */
+    sharedVisits: Record<string, number>;
+    /** Shared selector cursors (node id -> snapshot) for `shared` memoried selectors. */
+    sharedSelectors: Record<string, SelectorSnapshot>;
+    /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value) - the shared scene props. */
+    stageBags: Record<string, Record<string, ScalarValue>>;
+    /** Each live flow's snapshot, keyed by flow id. */
+    flows: Record<string, FlowSnapshot>;
+}
+/** What `Flow.advance()` surfaces to the host at each stop. */
+type StepResult = {
+    type: "line";
+    id: string;
+    text: string;
+    character?: string;
+    characterName?: string;
+    direction?: string;
+    gameData?: GameData;
+    tags?: string[];
+} | {
+    type: "text";
+    id: string;
+    text: string;
+    gameData?: GameData;
+    tags?: string[];
+} | {
+    type: "gameEvent";
+    id: string;
+    gameData?: GameData;
+    tags?: string[];
+} | {
+    type: "choice";
+    groupId: string;
+    options: ChoiceOption[];
+} | {
+    type: "end";
+};
+/** One beat's static data - the same shape a delivered step carries, resolved at the source locale. */
+interface BeatInfo {
+    id: string;
+    kind: "line" | "text" | "gameEvent";
+    /** Speaker token (line only). */
+    character?: string;
+    /** Resolved display name for `character` (source locale), if the cast declares one. */
+    characterName?: string;
+    /** Performance direction (line only). */
+    direction?: string;
+    /** Source text, un-interpolated (line / text). Omitted for gameEvent and IDs-only bundles. */
+    text?: string;
+    /** Author gameData overrides on this beat (raw, as the step carries them). Omitted when empty. */
+    gameData?: GameData;
+    /** Accumulated author tags (scene -> block -> group(s) -> snippet -> beat). Omitted when empty. */
+    tags?: string[];
+}
+/** A node in the outline tree: a group (with its selector + children) or a snippet (with its beats). */
+interface OutlineNode {
+    type: "group" | "snippet";
+    id: string;
+    tags?: string[];
+    selector?: string;
+    /** A choice/option group's prompt beat, if any. */
+    prompt?: BeatInfo;
+    children?: OutlineNode[];
+    beats?: BeatInfo[];
+    jumpTo?: string;
+    jumpMode?: "jump" | "call";
+}
+/** A block in the outline tree. */
+interface OutlineBlock {
+    id: string;
+    gameId?: string;
+    name: string;
+    tags?: string[];
+    children: OutlineNode[];
+}
+/** A scene in the outline tree. */
+interface OutlineScene {
+    id: string;
+    gameId?: string;
+    name: string;
+    tags?: string[];
+    blocks: OutlineBlock[];
+}
+/** One beat in document order, with the scene/block/snippet it lives in (the flat view). */
+interface FlatBeat {
+    sceneId: string;
+    blockId: string;
+    snippetId: string;
+    beat: BeatInfo;
+}
+/** What {@link Flow.advanceToStop} returns: the beats walked, and the choice / end that stopped it. */
+interface AdvanceToStopResult {
+    /** The line / text / game-event beats played on the way to the stop (never a choice / end). */
+    played: Array<Extract<StepResult, {
+        type: "line" | "text" | "gameEvent";
+    }>>;
+    stop: Extract<StepResult, {
+        type: "choice" | "end";
+    }>;
+}
+/** The choice text of an option (spec §5): its `prompt` beat, resolved + interpolated. */
+interface ChoicePrompt {
+    kind: "line" | "text";
+    /** Display text (interpolated; may be empty - the host can render from gameData / an icon). */
+    text: string;
+    /** Speaker / direction - present only for a `line` prompt (the PC's spoken choice). */
+    character?: string;
+    /** The speaker's resolved player-facing name (locale-aware; absent when the character has none). */
+    characterName?: string;
+    direction?: string;
+}
+/** A single option of a pending `choice` group. */
+interface ChoiceOption {
+    /** The option's id (an Option group, or a degenerate option snippet) - pass to `choose()`. */
+    id: string;
+    /**
+     * The option's `prompt` (spec §5) - the choice text as a structured line/text beat. For the
+     * degenerate bare-snippet tolerance, derived from the snippet's first content line. Undefined
+     * only when even that is absent; internal ids are never leaked as display text.
+     */
+    prompt?: ChoicePrompt;
+    /** False when the option's condition fails; still returned (greyed) unless hidden. */
+    eligible: boolean;
+    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
+ * are never stored or saved by this engine.
+ */
+type WorldResolver = ScopeResolver;
+interface EngineOptions {
+    /**
+     * Custom float-in-[0,1) source for `random()` / shuffle, shared by all flows.
+     * Overrides the built-in seeded PRNG - but its position is NOT captured by
+     * `saveGame()`. For resumable runs, use the built-in per-flow seed instead.
+     */
+    rng?: () => number;
+    /** Default seed for each flow's built-in (serialisable) PRNG; override per flow in `openFlow`. */
+    seed?: number;
+    /** 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. Shared by all flows. */
+    world?: WorldResolver;
+    /**
+     * Replay a chosen option's `prompt` as its first played beat (spec §5). Default `false`:
+     * the prompt is a label only and `choose()` plays just the option's content. `true`: the
+     * prompt beat is delivered first (the choice "spoken back"). A host decision, not authored.
+     */
+    replayPromptOnChoose?: boolean;
+    /** Closed captions (#214): show non-spoken caption cues inside dialogue lines (the `[sigh]` in
+     *  `Oh dear. [sigh] What now?`). Default `true` (full text). `false` strips every cue + its delimiters
+     *  and collapses the whitespace - for a player who hears the audio and doesn't want the captions.
+     *  Toggle live with `engine.setClosedCaptions(...)`. */
+    closedCaptions?: boolean;
+    /** Diagnostics hook (opt-in, dev tooling only): fired with the choice's group id whenever a choice runs
+     *  DRY - no takeable option and no eligible fallback - so it falls through silently. The behaviour is
+     *  unchanged; this only makes the fall-through observable. The coverage harness uses it to flag choices
+     *  that ran dry. Leave it unset in shipped games (zero cost). */
+    onDryChoice?: (groupId: string) => void;
+}
+/** One shared `@patter` property, for a live state inspector: its ref, declared type, current value,
+ *  declared default (for reset), and enum options. Mirrors the Unity / Godot ports' ListProperties. */
+interface PropertyRow {
+    ref: string;
+    type: PropertyType;
+    value: ScalarValue | undefined;
+    default: ScalarValue;
+    values?: string[];
+}
+/** Options for opening a flow. */
+interface OpenFlowOptions {
+    /** Scene to start at - its host-facing gameId (address) OR its internal id; defaults to the
+     *  bundle's first scene. */
+    scene?: string;
+    /** Block within the scene to start at - its gameId (scene-scoped address) OR its internal id. */
+    block?: string;
+    /** Seed for this flow's PRNG (defaults to the engine's `seed`). */
+    seed?: number;
+}
+interface SelectorState {
+    seq?: number;
+    bag?: string[];
+    last?: string;
+}
+/** Shared, read-mostly context the engine hands to every flow it owns. */
+interface FlowHost {
+    bundle: Bundle;
+    /** IDs-only build (`localisation.mode === "ids"`, no source-debug): the engine emits each beat's ID as
+     *  its text and omits character display names, leaving localisation to the game (use `flow.interpolate`
+     *  to apply `{@ref}` property replacement to a string the game looked up itself). */
+    emitIds: boolean;
+    strings: Record<string, string>;
+    /** The DEFAULT locale's string table - fallback for a key the active locale is missing (notably the
+     *  cast display-name keys, seeded there from `displayName`). */
+    defaultStrings: Record<string, string>;
+    /** Cast canonical name -> authoring `displayName` (the unlocalised fallback when no loc string exists). */
+    castDisplay: Map<string, string>;
+    nodeIndex: Map<string, SelectableNode>;
+    blockIndex: Map<string, {
+        sceneId: string;
+    }>;
+    blockById: Map<string, CompiledBlock>;
+    /** Author tags (#215): node id -> accumulated tags (own + every ancestor's, deduped). Built once. */
+    tagIndex: Map<string, string[]>;
+    /** The SHARED `@patter` globals (owned scope "patter") + world properties (`@world`). */
+    shared: ScopeRegistry;
+    /** Decls for the shared `@patter` globals - (re)seed on `engine.reset()`. */
+    patterSharedDecls: ScopeDeclaration[];
+    /** Decls for the per-flow `@patter` globals - seed each flow's local registry. */
+    patterLocalDecls: ScopeDeclaration[];
+    /** Lowercase names of the SHARED globals (route a `@patter` ref to engine vs flow). */
+    patterSharedNames: Set<string>;
+    /** Per-scene set of SHARED `@scene` prop names (route a `@scene` ref to stage vs flow). */
+    sceneSharedNames: Map<string, Set<string>>;
+    /** World-wide per-node entry counts (node id -> times entered by any flow). */
+    sharedVisits: Map<string, number>;
+    /** Shared selector cursors (node id -> SelectorState) for `shared` memoried selectors. */
+    sharedSelectors: Map<string, SelectorState>;
+    /** Shared, scene-namespaced `@scene` bags (scene id -> name -> value) for shared scene props. */
+    stageBags: Map<string, Record<string, ScalarValue>>;
+    customRng?: () => number;
+    /** Play a chosen option's prompt as its first beat (spec §5); default false. */
+    replayPromptOnChoose?: boolean;
+    /** Closed captions (#214). `captionsOn`: show caption cues in dialogue lines (default true); when
+     *  false the engine strips `captionOpen`…`captionClose` spans from line text. Mutable via
+     *  `setClosedCaptions` (one toggle, all flows - like setLocale). */
+    captionsOn: boolean;
+    captionOpen: string;
+    captionClose: string;
+    /** A cast member whose lines are pure captions: when captions are off ALL of its dialogue + speaker is
+     *  omitted (a silent line), delimiters or not. Default `SFX`. Empty = no caption character. */
+    captionCharacter: string;
+    /** Diagnostics hook (opt-in, dev only): fired when a choice runs DRY - nothing takeable and no eligible
+     *  fallback - so it falls through and the flow continues past it. Zero cost when unset; the coverage
+     *  harness passes it to surface silent fall-throughs. Not a gameplay signal (the behaviour is unchanged). */
+    onDryChoice?: (groupId: string) => void;
+    /** Memoised `splitRef` results (ref string -> {scope,name}). The split depends only on `shared`'s scope
+     *  set, which is fixed for the engine's life, so every effect target / `{@ref}` slot parses once. */
+    refSplitCache: Map<string, {
+        scope: string;
+        name: string;
+    }>;
+}
+declare class Engine {
+    private readonly host;
+    private readonly defaultSeed;
+    private readonly flowsById;
+    /** Every locale's string table (the inline `bundle.strings`), kept so the active locale can be swapped
+     *  live (setLocale) without rebuilding the engine. Reassigned wholesale by `replaceStrings`
+     *  (live bundle refresh, tier 1), hence not readonly. */
+    private allStrings;
+    /** The currently active locale (string lookups + character names resolve in it). */
+    private currentLocale;
+    /** True for a source-only DEBUG build (`localisation: { mode: "ids", sourceDebug: true }`) - the strings
+     *  are the source language, embedded only so the build can be played; not a shippable localised build. */
+    private readonly sourceDebug;
+    /** Host-facing addresses (spec §6): scene gameId -> internal id (project-wide), and per-scene
+     *  block gameId -> internal id. The effective gameId falls back to the name slug when unpinned. */
+    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. */
+    private readonly creationOptions;
+    constructor(bundle: Bundle, options?: EngineOptions);
+    /** The active locale (string + character-name lookups resolve in it). */
+    get locale(): string;
+    /** 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;
+    /**
+     * 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
+     * locale; everything else - flow position, `@patter`/`@scene` state, visit counts, the PRNG - is
+     * untouched (already-emitted text isn't retro-translated; that's the host's call). A locale with no
+     * table resolves every string via the `<Untranslated: {id}>` source fallback. All open flows share the
+     * engine's string table, so the swap reaches every flow at once.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Live bundle refresh, tier 1 (strings only): swap every locale's string table in place from a
+     * freshly compiled bundle whose STRUCTURE is unchanged (same `content.structureHash`). Like
+     * setLocale, nothing restarts and no flow is touched: the next delivered beat reads the new text,
+     * `{@ref}` slots re-interpolate, and beats the host already received keep the words it saw. The
+     * swap reaches every open flow at once and is not part of save state. Structural edits need the
+     * full save/load hot swap instead (a structure change here simply won't show).
+     */
+    replaceStrings(bundle: Bundle): void;
+    /**
+     * Live bundle refresh, tier 2 (full swap): rebuild on an edited bundle with the whole run carried
+     * over. Snapshot (`saveGame`), construct a fresh engine on `bundle` with THIS engine's original
+     * options (same world resolver, RNG, hooks), restore (`loadGame`), and carry over the presentation
+     * state that deliberately isn't save state (active locale, closed-captions toggle). The
+     * content-drift policy (§9.8) resolves edits under the cursor: stack frames re-find their next
+     * child by id, drifted options drop, a vanished snippet is skipped.
+     *
+     * Returns the REPLACEMENT engine; this one is left untouched and should be discarded. Hosts
+     * re-bind their flow handles via `next.getFlow(id)`. If the restore throws (defensive - §9.8
+     * makes this unreachable for ordinary edits), the swap falls back to a cold engine with each
+     * saved flow restarted from the top of the scene it was in.
+     */
+    hotSwap(bundle: Bundle): Engine;
+    /** Whether closed captions are currently shown (full dialogue text). */
+    get closedCaptions(): boolean;
+    /**
+     * Turn closed captions on/off LIVE (#214). When OFF, subsequent dialogue lines have their caption
+     * cues (`[sigh]` etc., between the project's delimiters) and the surrounding whitespace stripped;
+     * narration, choice prompts, and everything else are untouched. Like setLocale this is a presentation
+     * toggle - it reaches every open flow at once and isn't part of save state; already-emitted text is
+     * not retro-edited. An IDs-only game applies the same rule itself via `flow.stripCaptions`.
+     */
+    setClosedCaptions(on: boolean): void;
+    /**
+     * Open (and start) a named flow. Each flow has its own cursor, PRNG, and per-flow
+     * half of the scopes (not-shared `@patter`/`@scene`); all flows share the shared
+     * half. Re-opening an existing id replaces it with a fresh flow.
+     */
+    openFlow(id: string, opts?: OpenFlowOptions): Flow;
+    /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
+    private resolveSceneRef;
+    /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
+    private resolveBlockRef;
+    /** The host-facing address (gameId) of a scene / block by internal id, or undefined if unknown.
+     *  The inverse of the resolve helpers - for a host that wants to display / log the address. */
+    sceneAddress(sceneId: string): string | undefined;
+    blockAddress(blockId: string): string | undefined;
+    /**
+     * Author tags (#215) accumulated for a beat by id: its own tags unioned with every ancestor's
+     * (scene → block → group(s) → snippet → beat), deduped, outermost-first. The same value the beat's
+     * delivered step carries. Empty array for an unknown id or a beat with no tags anywhere up the chain.
+     */
+    tagsForBeat(beatId: string): string[];
+    /** A scene's own tags (by internal id or gameId address). Empty when none / unknown. */
+    tagsForScene(sceneRef: string): string[];
+    /** A block's accumulated tags (scene + block), by scene + block ref (id or gameId). Empty when none / unknown. */
+    tagsForBlock(sceneRef: string, blockRef: string): string[];
+    /**
+     * The authored structure as a nested tree: scenes -> blocks -> children (groups + snippets, groups
+     * preserved) -> a snippet's beats. Static (no flow / play state); per-beat data is read at the source
+     * locale. For dev tooling that builds against the writer's structure (see also {@link getBeatSequence}).
+     */
+    getOutline(): OutlineScene[];
+    /**
+     * Every beat in document order, flattened (through groups), each with the scene / block / snippet it
+     * belongs to and its static data. The linear view of {@link getOutline} - hand it to a tool that lays
+     * one item per beat (e.g. an Unreal Sequencer of subsequences).
+     */
+    getBeatSequence(): FlatBeat[];
+    /** A node's outline entry: a group (selector + prompt + children) or a snippet (beats + jump). */
+    private outlineNode;
+    /** One beat's static data (source locale), the same shape a delivered step carries. */
+    private beatInfo;
+    /** A `{ tags }` fragment for an id, present only when the id has accumulated tags (keeps output tidy). */
+    private tagsField;
+    /** Retrieve an open flow by id (undefined if none / closed). */
+    getFlow(id: string): Flow | undefined;
+    /** All currently-open flows. */
+    flows(): Flow[];
+    /** Close (remove) a flow. */
+    closeFlow(id: string): void;
+    /**
+     * Reset the whole game to its initial state: drop every flow, re-seed the shared
+     * `@patter` globals to their declared defaults, and clear all shared state (shared
+     * `@scene` bags, world visit counts). World properties are host-owned and untouched.
+     * After reset, open fresh flows with `openFlow`.
+     */
+    reset(): void;
+    /** Read a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
+    getProperty(ref: string): ScalarValue | undefined;
+    /** Write a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
+    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. */
+    listProperties(): PropertyRow[];
+    private splitShared;
+    /** Snapshot shared `@patter` state only (for a unified cross-engine save blob, Phase D). */
+    save(): EngineSave;
+    /** Restore shared `@patter` values (world properties untouched). */
+    load(blob: EngineSave): void;
+    /** Snapshot the whole game: shared `@patter` + visit counts + every live flow. */
+    saveGame(): SaveGame;
+    /** Restore a `saveGame()`: shared globals + visit counts + shared scene bags + reconstruct every flow. */
+    loadGame(save: SaveGame): void;
+}
+declare class Flow {
+    readonly id: string;
+    private readonly host;
+    private local;
+    private rngState;
+    private started;
+    private flowEnded;
+    private currentSceneId;
+    private stack;
+    private activeSnippet;
+    private beatIndex;
+    private pendingChoice;
+    /** When `replayPromptOnChoose`, the chosen option's prompt beat to deliver before its content. */
+    private pendingPromptBeat;
+    /** The chosen option that owns `pendingPromptBeat`, so a save taken between choose() and the next
+     *  advance() can re-derive the prompt on load (the beat isn't otherwise reachable by id). */
+    private pendingPromptOwnerId;
+    private selectors;
+    /** Per-node entry counts for this flow (node id -> times entered). */
+    private visitCounts;
+    private sceneBags;
+    private readonly patterResolver;
+    private readonly sceneResolver;
+    private readonly evalCtx;
+    constructor(id: string, host: FlowHost, seed: number);
+    /** Begin this flow at a scene (and optionally a specific block within it). */
+    start(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()`.
+     */
+    reset(sceneId?: string, blockId?: string): void;
+    /** The scene the cursor is currently in - set on entry and whenever a jump crosses scenes. Read
+     *  right after `advance()` to know which scene the just-played beat lives in (tooling that mirrors
+     *  the playhead, e.g. an editor following a cross-scene jump). `null` before the flow has started. */
+    get currentScene(): string | null;
+    /** Run until the next line, game event, choice, or the end of the flow. */
+    advance(): StepResult;
+    /**
+     * Advance repeatedly, collecting every played beat, until a choice or the end - the "play to the
+     * next stop" a host's play UI / tooling wants. The terminal `choice` / `end` is returned as `stop`;
+     * `played` holds the line / text / game-event results walked on the way to it. Termination is guaranteed
+     * (each `advance()` makes progress or `settle()` throws on a contentless jump cycle).
+     */
+    advanceToStop(): AdvanceToStopResult;
+    /**
+     * Drive the cursor to the next *deliverable* stop: a beat ready on the active
+     * snippet, a pending choice, or the end. Runs onExit/jump seams and walks the
+     * block run (sequentially, skipping ineligible children); a finished block pops
+     * to its caller (call-return) or ends the flow.
+     */
+    private settle;
+    /** 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. */
+    choose(id: string): void;
+    isEnded(): boolean;
+    /** Read a property by ref - `@patter` / `@scene` (each routed by its `shared` flag) or foreign. */
+    getProperty(ref: string): ScalarValue | undefined;
+    /** Write a property by ref (routed by scope, then by the property's `shared` flag). */
+    setProperty(ref: string, value: ScalarValue): void;
+    /** @internal Snapshot this flow's cursor + per-flow scopes (not-shared `@patter`/`@scene`) + PRNG. */
+    snapshot(): FlowSnapshot;
+    /** @internal Restore this flow from a snapshot. */
+    restore(snap: FlowSnapshot): void;
+    /** Set the current scene, reset its scene-local props, run onEntry. */
+    private enterSceneSetup;
+    /**
+     * Play one child of the active run. A snippet begins delivering. A group is
+     * walked by its selector: the default `run` pushes a nested run (its children
+     * play in order, gathering back); `choice` stops for the host; a select-one
+     * selector (branch, or a `sequence` in any order x exhaust mode) picks ONE child (recursing
+     * to a leaf) - selecting nothing contributes no content and the run continues.
+     */
+    private enterChild;
+    /** A container's children, whether it's a block or a run-group; undefined if the id is gone. */
+    private childrenOf;
+    private beginSnippet;
+    private setupChoice;
+    private resolveJump;
+    /**
+     * Route to a target (scene / block / `END`). `call` PUSHES a return frame (the
+     * caller's block run, already advanced to its next child, stays below); `jump`
+     * is absolute - it REPLACES the whole stack, discarding pending returns. `END`
+     * hard-ends the flow regardless of the callstack.
+     */
+    private enterTarget;
+    private selectChild;
+    /** `sequence` with `order: "sequential"` - walk children in authored order. */
+    private pickSequential;
+    /**
+     * `sequence` with `order: "shuffle"` - draw WITHOUT replacement (a bag), never
+     * repeating the immediately-previous pick across a reshuffle (no line twice in a
+     * row when >=2 are eligible). `stick` holds out the last authored child as the
+     * permanent terminal; `once` stops after one pass; `repeat` reshuffles.
+     */
+    private pickShuffle;
+    /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
+    private selectorState;
+    private runEffects;
+    private eligible;
+    private evalExpr;
+    /** Record an entry of a node (entered-only; spec §7): bumps the flow + world counts. */
+    private enter;
+    /** Next float in [0, 1): the shared custom PRNG, or this flow's serialisable mulberry32. */
+    private readonly rng;
+    private beatResult;
+    /**
+     * Expand inline `{@ref}` slots (spec §16) against this flow's CURRENT property state. Public so an
+     * IDs-only game can apply the same property replacement to a string it looked up in its own loc system:
+     * the engine handed it the beat ID, the game fetched its translation, then calls `flow.interpolate(...)`.
+     */
+    interpolate(raw: string): string;
+    /**
+     * Apply the project's caption rule to a string UNCONDITIONALLY (#214): remove every cue span between
+     * the project's delimiters and collapse the whitespace. Public so an IDs-only game - which looks up
+     * its own strings - can match the embedded runtime: `flow.stripCaptions(flow.interpolate(text))` when
+     * its own captions setting is off. (Embedded play does this automatically for dialogue lines.)
+     */
+    stripCaptions(raw: string): string;
+    /** Caption-strip a dialogue line ONLY when captions are off; otherwise pass the text through. The
+     *  internal gate the engine applies to every `line` beat / line-kind prompt. */
+    private captionLine;
+    /**
+     * An option's prompt (spec §5): the Option group's `prompt` beat, resolved + interpolated
+     * (choice labels are on-screen text, so they interpolate, spec §16). For the degenerate
+     * bare-snippet tolerance - or an Option group authored without a prompt - it falls back to the
+     * option's first content line. NO look-ahead. Undefined only when even that is absent.
+     */
+    private promptFor;
+    /** The prompt BEAT of an option: the Option group's `prompt`, else (tolerance) its first content line. */
+    private promptBeatOf;
+    /** The first snippet with a line/text beat within a child list, depth-first in authored order. */
+    private firstTextSnippetIn;
+    private resolveString;
+    /** A character's player-facing name: the `cast:<name>` string in the active locale, else the default
+     *  locale, else the authoring `displayName`. Undefined when the character has no display name at all
+     *  (the host falls back to the `character` token itself). */
+    private resolveCharacterName;
+    /** Split a ref into scope + name. Tokens: `@scene`, foreign tokens, else `@patter` (incl. bare `@name`). */
+    private splitRef;
+    /** The per-flow registry: the NOT-shared `@patter` globals (the shared ones live on the host). */
+    private freshLocal;
+    /**
+     * Seed a scene's `@scene` props (spec §7). The not-shared props seed THIS flow's
+     * bag the first time it enters (persist across re-entries thereafter); the shared
+     * props seed the host's stage bag the first time ANY flow enters the scene (shared
+     * and persistent thereafter - a later flow finds it present and leaves it).
+     * `temporary` props are the exception: reseeded to their default on every entry.
+     */
+    private seedScene;
+}
+
+/** The author-defined gameData fields declared for a node TYPE in a bundle (empty when none). */
+declare function gameDataFields(bundle: Bundle, kind: GameDataNodeKind): GameDataField[];
+/** One node's effective value for a field: its sparse OVERRIDE if present, else the field's declared
+ *  default (undefined if neither is set). `fields` is the schema for the node's type. */
+declare function gameDataValue(fields: GameDataField[], node: GameData | undefined, name: string): unknown;
+/** A node's FULL effective gameData: every declared field resolved (override or default), plus any
+ *  override keys with no matching field (orphans, kept verbatim). Fields left with no value are omitted. */
+declare function effectiveGameData(fields: GameDataField[], node: GameData | undefined): GameData;
+
+/**
+ * Map every node id (scene / block / group / snippet / beat) to its accumulated
+ * tags. Node ids are globally unique within a project (the validator enforces
+ * it), so one flat map suffices. Nodes with no tags anywhere up the chain map to
+ * an empty array.
+ */
+declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
+
+export { type AdvanceToStopResult, type BeatInfo, type ChoiceOption, Engine, type EngineOptions, type EngineSave, type FlatBeat, Flow, type FlowSnapshot, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type PropertyRow, type SaveGame, type SavedChoice, type SelectorSnapshot, type StackFrame, type StepResult, type WorldResolver, buildTagIndex, effectiveGameData, gameDataFields, gameDataValue };