@patterkit/runtime 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1281 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Engine: () => Engine,
+  Flow: () => Flow,
+  buildTagIndex: () => buildTagIndex,
+  effectiveGameData: () => effectiveGameData,
+  gameDataFields: () => gameDataFields,
+  gameDataValue: () => gameDataValue
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/engine.ts
+var import_expr = require("@wildwinter/expr");
+var import_scoperegistry = require("@wildwinter/scoperegistry");
+var import_dialect = require("@patterkit/dialect");
+var import_model = require("@patterkit/model");
+
+// src/tags.ts
+function dedupe(tags) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const t of tags) if (!seen.has(t)) {
+    seen.add(t);
+    out.push(t);
+  }
+  return out;
+}
+function buildTagIndex(bundle) {
+  const index = /* @__PURE__ */ new Map();
+  const visit = (node, inherited) => {
+    const acc = dedupe([...inherited, ...node.tags ?? []]);
+    index.set(node.id, acc);
+    if (node.type === "group") {
+      for (const child of node.children) visit(child, acc);
+    } else {
+      for (const beat of node.beats ?? []) index.set(beat.id, dedupe([...acc, ...beat.tags ?? []]));
+    }
+  };
+  for (const scene of Object.values(bundle.scenes)) {
+    const sceneAcc = dedupe(scene.tags ?? []);
+    index.set(scene.id, sceneAcc);
+    for (const block of scene.blocks) {
+      const blockAcc = dedupe([...sceneAcc, ...block.tags ?? []]);
+      index.set(block.id, blockAcc);
+      for (const child of block.children) visit(child, blockAcc);
+    }
+  }
+  return index;
+}
+
+// src/engine.ts
+var astCache = /* @__PURE__ */ new WeakMap();
+var Engine = class _Engine {
+  host;
+  defaultSeed;
+  flowsById = /* @__PURE__ */ new Map();
+  /** 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. */
+  allStrings;
+  /** The currently active locale (string lookups + character names resolve in it). */
+  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. */
+  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. */
+  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. */
+  creationOptions;
+  constructor(bundle, options = {}) {
+    this.creationOptions = options;
+    const locale = options.locale ?? bundle.locales.default;
+    const allStrings = bundle.strings;
+    this.allStrings = allStrings;
+    this.currentLocale = locale;
+    const strings = allStrings[locale] ?? {};
+    const defaultStrings = allStrings[bundle.locales.default] ?? {};
+    const loc = bundle.localisation;
+    const emitIds = loc?.mode === "ids" && !loc.sourceDebug;
+    this.sourceDebug = loc?.mode === "ids" && !!loc.sourceDebug;
+    if (this.sourceDebug && typeof console !== "undefined") {
+      console.warn("[Patterplay] source-only DEBUG build: strings are the source language for debugging, not a shippable localised build.");
+    }
+    const castDisplay = /* @__PURE__ */ new Map();
+    for (const c of bundle.cast ?? []) if (c.displayName) castDisplay.set(c.name, c.displayName);
+    this.defaultSeed = (options.seed ?? 2654435769) >>> 0;
+    const nodeIndex = /* @__PURE__ */ new Map();
+    const blockIndex = /* @__PURE__ */ new Map();
+    const blockById = /* @__PURE__ */ new Map();
+    for (const [sceneId, scene] of Object.entries(bundle.scenes)) {
+      this.sceneGameIdToId.set((0, import_model.effectiveGameId)(scene), sceneId);
+      const blockAddrs = /* @__PURE__ */ new Map();
+      for (const block of scene.blocks) {
+        blockIndex.set(block.id, { sceneId });
+        blockById.set(block.id, block);
+        blockAddrs.set((0, import_model.effectiveGameId)(block), block.id);
+        (0, import_model.walkNodes)(block.children, (n) => nodeIndex.set(n.id, n));
+      }
+      this.blockGameIdToId.set(sceneId, blockAddrs);
+    }
+    const props = bundle.properties ?? [];
+    const patterSharedDecls = props.filter((p) => p.shared ?? true).map(toDecl);
+    const patterLocalDecls = props.filter((p) => !(p.shared ?? true)).map(toDecl);
+    const patterSharedNames = new Set(patterSharedDecls.map((d) => d.name.toLowerCase()));
+    const shared = new import_scoperegistry.ScopeRegistry().defineOwned("patter", patterSharedDecls);
+    const hostBound = /* @__PURE__ */ new Set();
+    if (options.world) {
+      const worldSpec = bundle.scopeRegistry?.scopes.find((s) => s.token === "world");
+      const decls = (worldSpec?.declarations ?? []).map(toForeignDecl);
+      shared.defineForeign("world", options.world, decls, worldSpec?.writable ?? true);
+      hostBound.add("world");
+    }
+    for (const spec of bundle.scopeRegistry?.scopes ?? []) {
+      if (hostBound.has(spec.token)) continue;
+      const decls = (spec.declarations ?? []).map(toForeignDecl);
+      shared.defineForeign(spec.token, selfBackedResolver(spec.declarations ?? []), decls, spec.writable ?? true);
+    }
+    const sceneSharedNames = /* @__PURE__ */ new Map();
+    for (const [sceneId, scene] of Object.entries(bundle.scenes)) {
+      const names = new Set((scene.sceneProps ?? []).filter((p) => p.shared ?? false).map((p) => p.name.toLowerCase()));
+      sceneSharedNames.set(sceneId, names);
+    }
+    this.host = {
+      bundle,
+      emitIds,
+      strings,
+      defaultStrings,
+      castDisplay,
+      nodeIndex,
+      blockIndex,
+      blockById,
+      tagIndex: buildTagIndex(bundle),
+      shared,
+      patterSharedDecls,
+      patterLocalDecls,
+      patterSharedNames,
+      sceneSharedNames,
+      sharedVisits: /* @__PURE__ */ new Map(),
+      sharedSelectors: /* @__PURE__ */ new Map(),
+      stageBags: /* @__PURE__ */ new Map(),
+      customRng: options.rng,
+      onDryChoice: options.onDryChoice,
+      replayPromptOnChoose: options.replayPromptOnChoose ?? false,
+      captionsOn: options.closedCaptions ?? true,
+      // captions shown by default (full text)
+      captionOpen: (bundle.closedCaptions ?? import_model.DEFAULT_CAPTION_DELIMITERS).open,
+      captionClose: (bundle.closedCaptions ?? import_model.DEFAULT_CAPTION_DELIMITERS).close,
+      captionCharacter: bundle.closedCaptions?.character || import_model.DEFAULT_CAPTION_CHARACTER,
+      // absent/empty -> SFX
+      refSplitCache: /* @__PURE__ */ new Map()
+    };
+  }
+  /** The active locale (string + character-name lookups resolve in it). */
+  get locale() {
+    return this.currentLocale;
+  }
+  /** 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() {
+    return this.sourceDebug;
+  }
+  /**
+   * 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) {
+    this.currentLocale = locale;
+    this.host.strings = this.allStrings[locale] ?? {};
+  }
+  /**
+   * 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) {
+    this.allStrings = bundle.strings;
+    this.host.strings = this.allStrings[this.currentLocale] ?? {};
+    this.host.defaultStrings = this.allStrings[this.host.bundle.locales.default] ?? {};
+  }
+  /**
+   * 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) {
+    const snapshot = this.saveGame();
+    const carryOver = (next2) => {
+      next2.setLocale(this.currentLocale);
+      next2.setClosedCaptions(this.host.captionsOn);
+      return next2;
+    };
+    const next = new _Engine(bundle, this.creationOptions);
+    try {
+      next.loadGame(snapshot);
+      return carryOver(next);
+    } catch {
+      const fresh = new _Engine(bundle, this.creationOptions);
+      for (const [id, f] of Object.entries(snapshot.flows)) {
+        const sceneId = f.cursor.currentSceneId;
+        try {
+          fresh.openFlow(id, sceneId !== null ? { scene: sceneId } : {});
+        } catch {
+        }
+      }
+      return carryOver(fresh);
+    }
+  }
+  /** Whether closed captions are currently shown (full dialogue text). */
+  get closedCaptions() {
+    return this.host.captionsOn;
+  }
+  /**
+   * 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) {
+    this.host.captionsOn = on;
+  }
+  /**
+   * 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, opts = {}) {
+    const sceneId = this.resolveSceneRef(opts.scene);
+    const blockId = this.resolveBlockRef(sceneId, opts.block);
+    const flow = new Flow(id, this.host, opts.seed ?? this.defaultSeed);
+    this.flowsById.set(id, flow);
+    flow.start(sceneId, blockId);
+    return flow;
+  }
+  /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
+  resolveSceneRef(ref) {
+    if (ref == null) return void 0;
+    if (this.host.bundle.scenes[ref]) return ref;
+    return this.sceneGameIdToId.get(ref) ?? ref;
+  }
+  /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
+  resolveBlockRef(sceneId, ref) {
+    if (ref == null) return void 0;
+    if (this.host.blockById.has(ref)) return ref;
+    if (sceneId != null) {
+      const id = this.blockGameIdToId.get(sceneId)?.get(ref);
+      if (id) return id;
+    }
+    return ref;
+  }
+  /** 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) {
+    const scene = this.host.bundle.scenes[sceneId];
+    return scene ? (0, import_model.effectiveGameId)(scene) : void 0;
+  }
+  blockAddress(blockId) {
+    const block = this.host.blockById.get(blockId);
+    return block ? (0, import_model.effectiveGameId)(block) : void 0;
+  }
+  /**
+   * 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) {
+    return this.host.tagIndex.get(beatId) ?? [];
+  }
+  /** A scene's own tags (by internal id or gameId address). Empty when none / unknown. */
+  tagsForScene(sceneRef) {
+    const id = this.resolveSceneRef(sceneRef);
+    return (id != null ? this.host.tagIndex.get(id) : void 0) ?? [];
+  }
+  /** A block's accumulated tags (scene + block), by scene + block ref (id or gameId). Empty when none / unknown. */
+  tagsForBlock(sceneRef, blockRef) {
+    const sceneId = this.resolveSceneRef(sceneRef);
+    const id = this.resolveBlockRef(sceneId, blockRef);
+    return (id != null ? this.host.tagIndex.get(id) : void 0) ?? [];
+  }
+  /**
+   * 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() {
+    return Object.values(this.host.bundle.scenes).map((scene) => ({
+      id: scene.id,
+      ...(0, import_model.effectiveGameId)(scene) ? { gameId: (0, import_model.effectiveGameId)(scene) } : {},
+      name: scene.name,
+      ...this.tagsField(scene.id),
+      blocks: scene.blocks.map((block) => ({
+        id: block.id,
+        ...(0, import_model.effectiveGameId)(block) ? { gameId: (0, import_model.effectiveGameId)(block) } : {},
+        name: block.name,
+        ...this.tagsField(block.id),
+        children: block.children.map((n) => this.outlineNode(n))
+      }))
+    }));
+  }
+  /**
+   * 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() {
+    const out = [];
+    for (const scene of Object.values(this.host.bundle.scenes)) {
+      for (const block of scene.blocks) {
+        (0, import_model.walkNodes)(block.children, (n) => {
+          if (n.type !== "snippet") return;
+          for (const beat of n.beats ?? []) {
+            out.push({ sceneId: scene.id, blockId: block.id, snippetId: n.id, beat: this.beatInfo(beat) });
+          }
+        });
+      }
+    }
+    return out;
+  }
+  /** A node's outline entry: a group (selector + prompt + children) or a snippet (beats + jump). */
+  outlineNode(n) {
+    if (n.type === "group") {
+      return {
+        type: "group",
+        id: n.id,
+        ...this.tagsField(n.id),
+        ...n.selector ? { selector: n.selector } : {},
+        ...n.prompt ? { prompt: this.beatInfo(n.prompt) } : {},
+        children: n.children.map((c) => this.outlineNode(c))
+      };
+    }
+    return {
+      type: "snippet",
+      id: n.id,
+      ...this.tagsField(n.id),
+      beats: (n.beats ?? []).map((b) => this.beatInfo(b)),
+      ...n.jump ? { jumpTo: n.jump.to, ...n.jump.mode ? { jumpMode: n.jump.mode } : {} } : {}
+    };
+  }
+  /** One beat's static data (source locale), the same shape a delivered step carries. */
+  beatInfo(beat) {
+    const tags = this.host.tagIndex.get(beat.id);
+    const info = { id: beat.id, kind: beat.kind };
+    if (beat.kind === "line") {
+      if (beat.character !== void 0) {
+        info.character = beat.character;
+        const name = this.host.defaultStrings[(0, import_model.castStringKey)(beat.character)] ?? this.host.castDisplay.get(beat.character);
+        if (name !== void 0) info.characterName = name;
+      }
+      if (beat.direction !== void 0) info.direction = beat.direction;
+    }
+    if (beat.kind === "line" || beat.kind === "text") {
+      const source = this.host.defaultStrings[beat.id];
+      if (source !== void 0) info.text = source;
+    }
+    if (beat.gameData && Object.keys(beat.gameData).length) info.gameData = beat.gameData;
+    if (tags && tags.length) info.tags = tags;
+    return info;
+  }
+  /** A `{ tags }` fragment for an id, present only when the id has accumulated tags (keeps output tidy). */
+  tagsField(id) {
+    const tags = this.host.tagIndex.get(id);
+    return tags && tags.length ? { tags } : {};
+  }
+  /** Retrieve an open flow by id (undefined if none / closed). */
+  getFlow(id) {
+    return this.flowsById.get(id);
+  }
+  /** All currently-open flows. */
+  flows() {
+    return [...this.flowsById.values()];
+  }
+  /** Close (remove) a flow. */
+  closeFlow(id) {
+    this.flowsById.delete(id);
+  }
+  /**
+   * 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() {
+    this.flowsById.clear();
+    this.host.shared.reseedOwned("patter", this.host.patterSharedDecls);
+    this.host.sharedVisits.clear();
+    this.host.sharedSelectors.clear();
+    this.host.stageBags.clear();
+  }
+  /** Read a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
+  getProperty(ref) {
+    const { scope, name } = this.splitShared(ref);
+    return this.host.shared.get(scope, name);
+  }
+  /** Write a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
+  setProperty(ref, value) {
+    const { scope, name } = this.splitShared(ref);
+    this.host.shared.set(scope, name, value);
+  }
+  /** 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() {
+    return this.host.patterSharedDecls.map((d) => ({
+      ref: `@${d.name}`,
+      type: d.type,
+      values: d.values,
+      value: this.getProperty(`@${d.name}`),
+      default: declDefault(d)
+    }));
+  }
+  // @scene is scene-namespaced and needs a flow's current scene - silently
+  // routing it into the shared bag (as a junk "scene.x" key) was a trap.
+  splitShared(ref) {
+    let split = this.host.refSplitCache.get(ref);
+    if (!split) {
+      split = (0, import_dialect.splitRef)(ref, (t) => t === "scene" || this.host.shared.has(t));
+      this.host.refSplitCache.set(ref, split);
+    }
+    if (split.scope === "scene") {
+      throw new Error(`'${ref}': @scene properties are scene-scoped - read/write them on a Flow, not the Engine`);
+    }
+    return split;
+  }
+  /** Snapshot shared `@patter` state only (for a unified cross-engine save blob, Phase D). */
+  save() {
+    return this.host.shared.save();
+  }
+  /** Restore shared `@patter` values (world properties untouched). */
+  load(blob) {
+    this.host.shared.load(blob);
+  }
+  /** Snapshot the whole game: shared `@patter` + visit counts + every live flow. */
+  saveGame() {
+    const flows = {};
+    for (const [id, flow] of this.flowsById) flows[id] = flow.snapshot();
+    return {
+      version: 2,
+      shared: this.host.shared.save(),
+      sharedVisits: Object.fromEntries(this.host.sharedVisits),
+      sharedSelectors: serialiseSelectors(this.host.sharedSelectors),
+      stageBags: Object.fromEntries([...this.host.stageBags].map(([s, bag]) => [s, { ...bag }])),
+      flows
+    };
+  }
+  /** Restore a `saveGame()`: shared globals + visit counts + shared scene bags + reconstruct every flow. */
+  loadGame(save) {
+    if (save.version !== 2) throw new Error(`unsupported save version: ${save.version}`);
+    this.host.shared.load(save.shared);
+    this.host.sharedVisits.clear();
+    for (const [id, n] of Object.entries(save.sharedVisits ?? {})) this.host.sharedVisits.set(id, n);
+    this.host.sharedSelectors.clear();
+    for (const [id, st] of deserialiseSelectors(save.sharedSelectors)) this.host.sharedSelectors.set(id, st);
+    this.host.stageBags.clear();
+    for (const [s, bag] of Object.entries(save.stageBags ?? {})) this.host.stageBags.set(s, { ...bag });
+    this.flowsById.clear();
+    for (const [id, snap] of Object.entries(save.flows)) {
+      const flow = new Flow(id, this.host, this.defaultSeed);
+      flow.restore(snap);
+      this.flowsById.set(id, flow);
+    }
+  }
+};
+var Flow = class {
+  id;
+  host;
+  local;
+  // owns "patter" = the NOT-shared globals (this flow's copy)
+  rngState;
+  // Execution cursor. The `stack` is the continuation stack: each frame is a
+  // position within a block's children (the top frame is the active block run;
+  // lower frames are pending call-returns). A snippet's beats deliver from
+  // `activeSnippet`/`beatIndex`.
+  started = false;
+  flowEnded = false;
+  currentSceneId = null;
+  stack = [];
+  activeSnippet = null;
+  beatIndex = 0;
+  pendingChoice = null;
+  /** When `replayPromptOnChoose`, the chosen option's prompt beat to deliver before its content. */
+  pendingPromptBeat = null;
+  /** 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). */
+  pendingPromptOwnerId = null;
+  selectors = /* @__PURE__ */ new Map();
+  /** Per-node entry counts for this flow (node id -> times entered). */
+  visitCounts = /* @__PURE__ */ new Map();
+  // Per-flow halves of the two scopes. The NOT-shared `@patter` globals live in
+  // `local` (owned scope "patter"); the NOT-shared `@scene` props live in
+  // `sceneBags` (namespaced per scene; they PERSIST across re-entries, spec §7).
+  // The SHARED halves live on the host (`host.shared` / `host.stageBags`). Each
+  // resolver presents one merged scope, routing each property to its half by the
+  // declared `shared` flag.
+  sceneBags = /* @__PURE__ */ new Map();
+  patterResolver = {
+    get: (n) => this.host.patterSharedNames.has(n) ? this.host.shared.get("patter", n) : this.local.get("patter", n),
+    set: (n, v) => {
+      if (this.host.patterSharedNames.has(n)) this.host.shared.set("patter", n, v);
+      else this.local.set("patter", n, v);
+    }
+  };
+  sceneResolver = {
+    get: (n) => {
+      const s = this.currentSceneId;
+      if (s === null) return void 0;
+      const bag = this.host.sceneSharedNames.get(s)?.has(n) ? this.host.stageBags.get(s) : this.sceneBags.get(s);
+      return bag?.[n];
+    },
+    set: (n, v) => {
+      const s = this.currentSceneId;
+      if (s === null) return;
+      const bag = this.host.sceneSharedNames.get(s)?.has(n) ? this.host.stageBags.get(s) : this.sceneBags.get(s);
+      if (bag) bag[n] = v;
+    }
+  };
+  // The eval context is built ONCE: every constituent resolves live state at
+  // call time (shared bags mutate in place per scoperegistry's contract;
+  // patter/scene route through this flow's resolvers, which read the current
+  // `local`/`sceneBags`/`currentSceneId`; the host callbacks read current flow
+  // fields). Rebuilding it per evaluation was the engine's hottest allocation.
+  evalCtx;
+  constructor(id, host, seed) {
+    this.id = id;
+    this.host = host;
+    this.rngState = seed >>> 0;
+    this.local = this.freshLocal();
+    const scopes = { ...host.shared.toEvalContext().scopes };
+    scopes["patter"] = this.patterResolver;
+    scopes["scene"] = this.sceneResolver;
+    this.evalCtx = {
+      scopes,
+      host: {
+        nextRandom: this.rng,
+        visits: (id2) => this.visitCounts.get(id2) ?? 0,
+        patterVisits: (id2) => this.host.sharedVisits.get(id2) ?? 0
+      }
+    };
+  }
+  // -- Host API -------------------------------------------------------------
+  /** Begin this flow at a scene (and optionally a specific block within it). */
+  start(sceneId, blockId) {
+    this.sceneBags.clear();
+    this.local = this.freshLocal();
+    this.selectors.clear();
+    this.visitCounts.clear();
+    this.stack = [];
+    this.currentSceneId = null;
+    this.flowEnded = false;
+    this.activeSnippet = null;
+    this.beatIndex = 0;
+    this.pendingChoice = null;
+    this.started = true;
+    if (blockId) {
+      const loc = this.host.blockIndex.get(blockId);
+      if (!loc) throw new Error(`unknown block: ${blockId}`);
+      this.enterSceneSetup(loc.sceneId);
+      this.stack = [{ sceneId: loc.sceneId, containerId: blockId, index: 0 }];
+      this.enter(blockId);
+    } else {
+      const id = sceneId ?? Object.keys(this.host.bundle.scenes)[0];
+      const scene = id ? this.host.bundle.scenes[id] : void 0;
+      if (!scene) throw new Error(id ? `unknown scene: ${id}` : "no scenes in bundle");
+      this.enterSceneSetup(id);
+      const first = scene.blocks[0];
+      if (first) {
+        this.stack = [{ sceneId: id, containerId: first.id, index: 0 }];
+        this.enter(first.id);
+      }
+    }
+    this.settle();
+  }
+  /**
+   * 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, blockId) {
+    this.start(sceneId, blockId);
+  }
+  /** 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() {
+    return this.currentSceneId;
+  }
+  /** Run until the next line, game event, choice, or the end of the flow. */
+  advance() {
+    if (!this.started) throw new Error("flow has not been started");
+    if (this.pendingPromptBeat) {
+      const b = this.pendingPromptBeat;
+      this.pendingPromptBeat = null;
+      this.pendingPromptOwnerId = null;
+      return this.beatResult(b);
+    }
+    this.settle();
+    if (this.flowEnded) return { type: "end" };
+    if (this.pendingChoice) return { type: "choice", groupId: this.pendingChoice.groupId, options: this.pendingChoice.options };
+    if (!this.activeSnippet) {
+      this.flowEnded = true;
+      return { type: "end" };
+    }
+    return this.beatResult(this.activeSnippet.beats[this.beatIndex++]);
+  }
+  /**
+   * 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() {
+    const played = [];
+    for (; ; ) {
+      const r = this.advance();
+      if (r.type === "choice" || r.type === "end") return { played, stop: r };
+      played.push(r);
+    }
+  }
+  /**
+   * 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.
+   */
+  settle() {
+    let transitions = 0;
+    for (; ; ) {
+      if (++transitions > 1e4) {
+        throw new Error("flow did not settle after 10000 transitions - likely a jump cycle with no deliverable content");
+      }
+      if (this.flowEnded || this.pendingChoice) return;
+      if (this.activeSnippet) {
+        if (this.beatIndex < (this.activeSnippet.beats?.length ?? 0)) return;
+        this.runEffects(this.activeSnippet.onExit);
+        const jump = this.activeSnippet.jump;
+        this.activeSnippet = null;
+        this.beatIndex = 0;
+        this.resolveJump(jump);
+        continue;
+      }
+      const frame = this.stack[this.stack.length - 1];
+      if (!frame) {
+        this.flowEnded = true;
+        return;
+      }
+      if (frame.sceneId !== this.currentSceneId) this.currentSceneId = frame.sceneId;
+      const children = this.childrenOf(frame.containerId);
+      if (!children) {
+        this.stack.pop();
+        continue;
+      }
+      while (frame.index < children.length && !this.eligible(children[frame.index])) frame.index++;
+      if (frame.index >= children.length) {
+        this.stack.pop();
+        continue;
+      }
+      this.enterChild(children[frame.index++]);
+    }
+  }
+  /** The options of a pending choice (empty when not at a choice point). */
+  getChoices() {
+    return this.pendingChoice?.options ?? [];
+  }
+  /** Pick an eligible option by id; the next `advance()` runs it. */
+  choose(id) {
+    const choice = this.pendingChoice;
+    if (!choice) throw new Error("no choice is pending");
+    const option = choice.options.find((o) => o.id === id);
+    if (!option) throw new Error(`unknown choice option: ${id}`);
+    if (!option.eligible) throw new Error(`choice option is not eligible: ${id}`);
+    const node = choice.byId.get(id);
+    this.pendingChoice = null;
+    this.pendingPromptBeat = this.host.replayPromptOnChoose ? this.promptBeatOf(node) ?? null : null;
+    this.pendingPromptOwnerId = this.pendingPromptBeat ? node.id : null;
+    this.enterChild(node);
+  }
+  isEnded() {
+    return this.flowEnded;
+  }
+  /** Read a property by ref - `@patter` / `@scene` (each routed by its `shared` flag) or foreign. */
+  getProperty(ref) {
+    const { scope, name } = this.splitRef(ref);
+    if (scope === "patter") return this.patterResolver.get(name);
+    if (scope === "scene") return this.sceneResolver.get(name);
+    return this.host.shared.get(scope, name);
+  }
+  /** Write a property by ref (routed by scope, then by the property's `shared` flag). */
+  setProperty(ref, value) {
+    const { scope, name } = this.splitRef(ref);
+    if (scope === "patter") {
+      this.patterResolver.set(name, value);
+    } else if (scope === "scene") {
+      if (this.currentSceneId === null) throw new Error(`'${ref}': the flow has not entered a scene yet`);
+      this.sceneResolver.set(name, value);
+    } else {
+      this.host.shared.set(scope, name, value);
+    }
+  }
+  // -- Save / restore (engine-driven) --------------------------------------
+  /** @internal Snapshot this flow's cursor + per-flow scopes (not-shared `@patter`/`@scene`) + PRNG. */
+  snapshot() {
+    return {
+      scopes: this.local.save(),
+      // owned scope "patter" = the NOT-shared globals (@scene saved separately)
+      sceneBags: Object.fromEntries([...this.sceneBags].map(([s, bag]) => [s, { ...bag }])),
+      rngState: this.rngState,
+      visits: Object.fromEntries(this.visitCounts),
+      cursor: {
+        flowEnded: this.flowEnded,
+        currentSceneId: this.currentSceneId,
+        // Stamp each frame with the id of the child it would run next (nextId), so a restore against
+        // an EDITED bundle re-finds the position by id instead of trusting the raw index (§9.8 /
+        // live bundle refresh). A frame saved at its container's end has no next child - no stamp.
+        stack: this.stack.map((f) => {
+          const next = this.childrenOf(f.containerId)?.[f.index];
+          return next ? { ...f, nextId: next.id } : { ...f };
+        }),
+        activeSnippetId: this.activeSnippet?.id ?? null,
+        beatIndex: this.beatIndex,
+        pendingChoice: this.pendingChoice ? { groupId: this.pendingChoice.groupId, options: this.pendingChoice.options.map((o) => ({ ...o })) } : null,
+        pendingPromptOwnerId: this.pendingPromptOwnerId,
+        selectors: serialiseSelectors(this.selectors)
+      }
+    };
+  }
+  /** @internal Restore this flow from a snapshot. */
+  restore(snap) {
+    this.rngState = snap.rngState >>> 0;
+    this.visitCounts = new Map(Object.entries(snap.visits ?? {}));
+    const c = snap.cursor;
+    this.started = true;
+    this.flowEnded = c.flowEnded;
+    this.beatIndex = c.beatIndex;
+    this.currentSceneId = c.currentSceneId;
+    this.stack = c.stack.map((f) => {
+      const { nextId, ...frame } = f;
+      if (nextId !== void 0) {
+        const at = this.childrenOf(frame.containerId)?.findIndex((ch) => ch.id === nextId) ?? -1;
+        if (at >= 0) return { ...frame, index: at };
+      }
+      return { ...frame };
+    });
+    this.sceneBags = new Map(Object.entries(snap.sceneBags ?? {}).map(([s, bag]) => [s, { ...bag }]));
+    this.local = this.freshLocal();
+    this.local.load(snap.scopes);
+    this.activeSnippet = null;
+    if (c.activeSnippetId !== null) {
+      const node = this.host.nodeIndex.get(c.activeSnippetId);
+      if (node && node.type === "snippet") this.activeSnippet = node;
+    }
+    this.selectors = deserialiseSelectors(c.selectors);
+    this.pendingChoice = null;
+    if (c.pendingChoice !== null) {
+      const byId = /* @__PURE__ */ new Map();
+      const options = [];
+      for (const o of c.pendingChoice.options) {
+        const node = this.host.nodeIndex.get(o.id);
+        if (!node) continue;
+        byId.set(o.id, node);
+        options.push({ ...o });
+      }
+      if (options.length > 0) this.pendingChoice = { groupId: c.pendingChoice.groupId, options, byId };
+    }
+    this.pendingPromptBeat = null;
+    this.pendingPromptOwnerId = c.pendingPromptOwnerId ?? null;
+    if (this.pendingPromptOwnerId) {
+      const owner = this.host.nodeIndex.get(this.pendingPromptOwnerId);
+      this.pendingPromptBeat = owner ? this.promptBeatOf(owner) ?? null : null;
+      if (!this.pendingPromptBeat) this.pendingPromptOwnerId = null;
+    }
+  }
+  // -- Scene / block / node entry ------------------------------------------
+  /** Set the current scene, reset its scene-local props, run onEntry. */
+  enterSceneSetup(sceneId) {
+    const scene = this.host.bundle.scenes[sceneId];
+    if (!scene) throw new Error(`unknown scene: ${sceneId}`);
+    this.currentSceneId = sceneId;
+    this.enter(sceneId);
+    this.seedScene(scene);
+    this.runEffects(scene.onEntry);
+  }
+  /**
+   * 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.
+   */
+  enterChild(node) {
+    this.enter(node.id);
+    if (node.type === "snippet") {
+      this.beginSnippet(node);
+      return;
+    }
+    const selector = node.selector ?? "run";
+    if (selector === "run") {
+      this.stack.push({ sceneId: this.currentSceneId, containerId: node.id, index: 0 });
+      return;
+    }
+    if (selector === "choice") {
+      this.setupChoice(node);
+      return;
+    }
+    const pick = this.selectChild(node);
+    if (pick) this.enterChild(pick);
+  }
+  /** A container's children, whether it's a block or a run-group; undefined if the id is gone. */
+  childrenOf(containerId) {
+    const block = this.host.blockById.get(containerId);
+    if (block) return block.children;
+    const node = this.host.nodeIndex.get(containerId);
+    if (node && node.type === "group") return node.children;
+    return void 0;
+  }
+  beginSnippet(snippet) {
+    this.runEffects(snippet.onEnter);
+    this.activeSnippet = snippet;
+    this.beatIndex = 0;
+  }
+  setupChoice(group) {
+    const options = [];
+    const byId = /* @__PURE__ */ new Map();
+    const fallbacks = [];
+    for (const child of group.children) {
+      if (child.fallback === true) {
+        fallbacks.push(child);
+        continue;
+      }
+      if (child.sticky !== true && (this.visitCounts.get(child.id) ?? 0) >= 1) continue;
+      const eligible = this.eligible(child);
+      const hidden = child.secretUntilEligible === true;
+      if (!eligible && hidden) continue;
+      options.push({ id: child.id, prompt: this.promptFor(child), eligible, gameData: child.gameData });
+      byId.set(child.id, child);
+    }
+    if (options.length > 0) {
+      this.pendingChoice = { groupId: group.id, options, byId };
+      return;
+    }
+    const fallback = fallbacks.find((f) => this.eligible(f));
+    if (fallback) {
+      this.enterChild(fallback);
+      return;
+    }
+    this.host.onDryChoice?.(group.id);
+  }
+  // -- Jumps (jump / call-return) ----------------------------------------
+  resolveJump(jump) {
+    if (!jump) return;
+    this.enterTarget(jump.to, jump.mode === "call" ? "call" : "jump");
+  }
+  /**
+   * 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.
+   */
+  enterTarget(to, mode) {
+    if (to === "END") {
+      this.flowEnded = true;
+      this.stack = [];
+      return;
+    }
+    let sceneId;
+    let containerId;
+    const scene = this.host.bundle.scenes[to];
+    if (scene) {
+      this.enterSceneSetup(to);
+      const first = scene.blocks[0];
+      if (!first) {
+        if (mode === "jump") this.stack = [];
+        return;
+      }
+      sceneId = to;
+      containerId = first.id;
+    } else {
+      const loc = this.host.blockIndex.get(to);
+      if (!loc) throw new Error(`jump target not found: ${to}`);
+      if (loc.sceneId !== this.currentSceneId) this.enterSceneSetup(loc.sceneId);
+      sceneId = loc.sceneId;
+      containerId = to;
+    }
+    this.enter(containerId);
+    const frame = { sceneId, containerId, index: 0 };
+    if (mode === "call") this.stack.push(frame);
+    else this.stack = [frame];
+  }
+  // -- Selectors ------------------------------------------------------------
+  selectChild(group) {
+    const eligible = group.children.filter((c) => this.eligible(c));
+    if (eligible.length === 0) return null;
+    const st = this.selectorState(group);
+    switch (group.selector) {
+      case "branch":
+        return eligible[0];
+      case "sequence": {
+        const order = group.options?.order ?? "sequential";
+        const exhaust = group.options?.exhaust ?? "once";
+        return order === "shuffle" ? this.pickShuffle(eligible, exhaust, st) : this.pickSequential(eligible, exhaust, st);
+      }
+      case "run":
+      case "choice":
+      default:
+        return null;
+    }
+  }
+  /** `sequence` with `order: "sequential"` - walk children in authored order. */
+  pickSequential(eligible, exhaust, st) {
+    const len = eligible.length;
+    const n = st.seq ?? 0;
+    st.seq = n + 1;
+    if (exhaust === "repeat") return eligible[n % len];
+    if (n < len) return eligible[n];
+    if (exhaust === "stick") return eligible[len - 1];
+    return null;
+  }
+  /**
+   * `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.
+   */
+  pickShuffle(eligible, exhaust, st) {
+    const len = eligible.length;
+    const stick = exhaust === "stick";
+    const fill = () => (stick ? eligible.slice(0, len - 1) : eligible).map((c) => c.id);
+    if (st.bag === void 0) st.bag = fill();
+    if (st.bag.length === 0) {
+      if (exhaust === "once") return null;
+      if (stick) {
+        const last = eligible[len - 1];
+        st.last = last.id;
+        return last;
+      }
+      st.bag = fill();
+    }
+    const pool = st.bag;
+    const p = st.last !== void 0 && pool.length > 1 ? pool.indexOf(st.last) : -1;
+    let i = Math.floor(this.rng() * (p >= 0 ? pool.length - 1 : pool.length));
+    if (p >= 0 && i >= p) i++;
+    const id = pool[i];
+    pool.splice(i, 1);
+    st.last = id;
+    return eligible.find((c) => c.id === id);
+  }
+  /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
+  selectorState(group) {
+    const map = group.shared ? this.host.sharedSelectors : this.selectors;
+    let st = map.get(group.id);
+    if (!st) {
+      st = {};
+      map.set(group.id, st);
+    }
+    return st;
+  }
+  // -- Effects + expressions ------------------------------------------------
+  runEffects(effects) {
+    for (const e of effects ?? []) {
+      this.setProperty(e.target, this.evalExpr(e.value));
+    }
+  }
+  eligible(node) {
+    if (!node.condition) return true;
+    return truthy(this.evalExpr(node.condition));
+  }
+  evalExpr(expr) {
+    let ast = astCache.get(expr);
+    if (!ast) {
+      ast = (0, import_expr.deserialiseAst)(expr.ast);
+      astCache.set(expr, ast);
+    }
+    return (0, import_expr.evaluate)(ast, this.evalCtx, import_dialect.patterDialect);
+  }
+  /** Record an entry of a node (entered-only; spec §7): bumps the flow + world counts. */
+  enter(id) {
+    this.visitCounts.set(id, (this.visitCounts.get(id) ?? 0) + 1);
+    this.host.sharedVisits.set(id, (this.host.sharedVisits.get(id) ?? 0) + 1);
+  }
+  /** Next float in [0, 1): the shared custom PRNG, or this flow's serialisable mulberry32. */
+  rng = () => {
+    if (this.host.customRng) return this.host.customRng();
+    const a = this.rngState + 1831565813 | 0;
+    this.rngState = a;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+  // -- Strings / beats ------------------------------------------------------
+  beatResult(beat) {
+    const tags = this.host.tagIndex.get(beat.id);
+    const withTags = tags && tags.length ? { tags } : {};
+    switch (beat.kind) {
+      case "gameEvent":
+        return { type: "gameEvent", id: beat.id, gameData: beat.gameData, ...withTags };
+      case "text":
+        return { type: "text", id: beat.id, text: this.interpolate(this.resolveString(beat.id)), gameData: beat.gameData, ...withTags };
+      case "line": {
+        const raw = this.resolveString(beat.id);
+        const off = !this.host.captionsOn;
+        const captionChar = off && beat.character === this.host.captionCharacter;
+        const text = captionChar ? "" : this.captionLine(this.host.bundle.voiced ? raw : this.interpolate(raw));
+        const silent = off && text.length === 0;
+        return {
+          type: "line",
+          id: beat.id,
+          text,
+          character: silent ? void 0 : beat.character,
+          characterName: silent ? void 0 : this.resolveCharacterName(beat.character),
+          direction: silent ? void 0 : beat.direction,
+          gameData: beat.gameData,
+          ...withTags
+        };
+      }
+    }
+  }
+  /**
+   * 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) {
+    return (0, import_dialect.interpolate)(raw, (ref) => this.getProperty(ref));
+  }
+  /**
+   * 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) {
+    return (0, import_dialect.stripCaptions)(raw, this.host.captionOpen, this.host.captionClose);
+  }
+  /** 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. */
+  captionLine(text) {
+    return this.host.captionsOn ? text : this.stripCaptions(text);
+  }
+  /**
+   * 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.
+   */
+  promptFor(node) {
+    const beat = this.promptBeatOf(node);
+    if (!beat) return void 0;
+    const text = this.interpolate(this.resolveString(beat.id));
+    return beat.kind === "line" ? { kind: "line", text: this.captionLine(text), character: beat.character, characterName: this.resolveCharacterName(beat.character), direction: beat.direction } : { kind: "text", text };
+  }
+  /** The prompt BEAT of an option: the Option group's `prompt`, else (tolerance) its first content line. */
+  promptBeatOf(node) {
+    if (node.type === "group" && node.prompt) return node.prompt;
+    const snippet = node.type === "snippet" ? node : this.firstTextSnippetIn(node.children);
+    return (snippet?.beats ?? []).find((b) => b.kind === "line" || b.kind === "text");
+  }
+  /** The first snippet with a line/text beat within a child list, depth-first in authored order. */
+  firstTextSnippetIn(children) {
+    let found;
+    (0, import_model.walkNodes)(children, (n) => {
+      if (!found && n.type === "snippet" && (n.beats ?? []).some((b) => b.kind === "line" || b.kind === "text")) {
+        found = n;
+      }
+    });
+    return found;
+  }
+  resolveString(id) {
+    if (this.host.emitIds) return id;
+    const active = this.host.strings[id];
+    if (active !== void 0) return active;
+    const source = this.host.defaultStrings[id];
+    return source !== void 0 ? `<Untranslated: ${id}> ${source}` : id;
+  }
+  /** 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). */
+  resolveCharacterName(character) {
+    if (character === void 0) return void 0;
+    if (this.host.emitIds) return void 0;
+    const key = (0, import_model.castStringKey)(character);
+    return this.host.strings[key] ?? this.host.defaultStrings[key] ?? this.host.castDisplay.get(character);
+  }
+  /** Split a ref into scope + name. Tokens: `@scene`, foreign tokens, else `@patter` (incl. bare `@name`). */
+  splitRef(ref) {
+    let hit = this.host.refSplitCache.get(ref);
+    if (!hit) {
+      hit = (0, import_dialect.splitRef)(ref, (t) => t === "scene" || this.host.shared.has(t));
+      this.host.refSplitCache.set(ref, hit);
+    }
+    return hit;
+  }
+  /** The per-flow registry: the NOT-shared `@patter` globals (the shared ones live on the host). */
+  freshLocal() {
+    return new import_scoperegistry.ScopeRegistry().defineOwned("patter", this.host.patterLocalDecls);
+  }
+  /**
+   * 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.
+   */
+  seedScene(scene) {
+    const shared = this.host.sceneSharedNames.get(scene.id) ?? /* @__PURE__ */ new Set();
+    if (!this.sceneBags.has(scene.id)) {
+      const bag = {};
+      for (const decl of scene.sceneProps ?? []) {
+        const name = decl.name.toLowerCase();
+        if (!shared.has(name)) bag[name] = sceneDefault(decl);
+      }
+      this.sceneBags.set(scene.id, bag);
+    }
+    if (!this.host.stageBags.has(scene.id)) {
+      const bag = {};
+      for (const decl of scene.sceneProps ?? []) {
+        const name = decl.name.toLowerCase();
+        if (shared.has(name)) bag[name] = sceneDefault(decl);
+      }
+      this.host.stageBags.set(scene.id, bag);
+    }
+    for (const decl of scene.sceneProps ?? []) {
+      if (!decl.temporary) continue;
+      const name = decl.name.toLowerCase();
+      const bag = shared.has(name) ? this.host.stageBags.get(scene.id) : this.sceneBags.get(scene.id);
+      if (bag) bag[name] = sceneDefault(decl);
+    }
+  }
+};
+function serialiseSelectors(map) {
+  const out = {};
+  for (const [id, st] of map) {
+    const v = {};
+    if (st.seq !== void 0) v.seq = st.seq;
+    if (st.bag) v.bag = [...st.bag];
+    if (st.last !== void 0) v.last = st.last;
+    out[id] = v;
+  }
+  return out;
+}
+function deserialiseSelectors(rec) {
+  const map = /* @__PURE__ */ new Map();
+  for (const [id, v] of Object.entries(rec ?? {})) {
+    const st = {};
+    if (v.seq !== void 0) st.seq = v.seq;
+    if (v.bag) st.bag = [...v.bag];
+    if (v.last !== void 0) st.last = v.last;
+    map.set(id, st);
+  }
+  return map;
+}
+function toDecl(decl) {
+  return { name: decl.name, type: decl.type, values: decl.values, default: decl.default };
+}
+function declDefault(d) {
+  if (d.default !== void 0) return d.default;
+  switch (d.type) {
+    case "number":
+      return 0;
+    case "string":
+      return "";
+    case "flags":
+      return [];
+    case "enum":
+      return d.values?.[0] ?? "";
+    default:
+      return false;
+  }
+}
+function toForeignDecl(decl) {
+  return { name: decl.name, type: decl.type, values: decl.values, default: decl.default, writable: decl.writable };
+}
+function hostScopeDefault(decl) {
+  if (decl.default !== void 0) return decl.default;
+  switch (decl.type) {
+    case "boolean":
+      return false;
+    case "number":
+      return 0;
+    case "string":
+      return "";
+    case "flags":
+      return [];
+    case "enum":
+      return decl.values?.[0] ?? "";
+  }
+}
+function selfBackedResolver(decls) {
+  const bag = /* @__PURE__ */ new Map();
+  for (const d of decls) bag.set(d.name, hostScopeDefault(d));
+  return {
+    get: (name) => bag.get(name),
+    set: (name, value) => {
+      bag.set(name, value);
+    }
+  };
+}
+function sceneDefault(decl) {
+  if (decl.default !== void 0) return decl.default;
+  switch (decl.type) {
+    case "boolean":
+      return false;
+    case "number":
+      return 0;
+    case "string":
+      return "";
+    case "flags":
+      return [];
+    case "enum":
+      return decl.values?.[0] ?? "";
+  }
+}
+function truthy(v) {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v !== 0;
+  if (typeof v === "string") return v !== "";
+  return v.length > 0;
+}
+
+// src/gamedata.ts
+function gameDataFields(bundle, kind) {
+  return bundle.gameDataFields?.[kind] ?? [];
+}
+function gameDataValue(fields, node, name) {
+  if (node && Object.prototype.hasOwnProperty.call(node, name)) return node[name];
+  return fields.find((f) => f.name === name)?.default;
+}
+function effectiveGameData(fields, node) {
+  const out = {};
+  for (const f of fields) {
+    const v = gameDataValue(fields, node, f.name);
+    if (v !== void 0) out[f.name] = v;
+  }
+  for (const [k, v] of Object.entries(node ?? {})) if (!(k in out)) out[k] = v;
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Engine,
+  Flow,
+  buildTagIndex,
+  effectiveGameData,
+  gameDataFields,
+  gameDataValue
+});
+//# sourceMappingURL=index.cjs.map