@patterkit/runtime 0.18.0 → 0.19.0

package/dist/index.d.cts

@@ -194,12 +194,34 @@ type TraceEvent = {
     value: ScalarValue;
     prev?: ScalarValue;
 }
-/** An expression that would not evaluate: never a silent pass, always visible. */
+/** Content the engine could not evaluate and played through (see {@link PlayError}): a condition
+ *  counted as false, an effect skipped, or a Best-match part scored as false. */
  | {
     type: "diagnostic";
-    where: string;
+    kind: PlayError["kind"];
+    node: string;
+    source?: string;
     message: string;
 };
+/**
+ * A content error the engine played through. Content can fail at run time in ways the compiler cannot
+ * see: a division by zero, a host value of the wrong type, a story write to a read-only `@world` value.
+ * The story never stops for one. A condition that fails counts as false; an effect that fails is skipped
+ * and the rest of its list still runs; a part of a Best-match condition that fails scores as false. Each
+ * is reported, through `EngineOptions.onError` and as a `diagnostic` entry in the decision log. The same
+ * rule holds on all four runtimes, including the two whose languages cannot throw.
+ */
+interface PlayError {
+    /** The flow it happened in. */
+    flow: string;
+    /** What failed: a condition, an effect, or a part of a condition being scored for Best match. */
+    kind: "condition" | "effect" | "best-match";
+    /** The snippet, group, or option whose condition failed, or that owns the effect (a scene, for its onEntry). */
+    node: string;
+    /** The expression's source text, when the bundle carries it. */
+    source?: string;
+    message: string;
+}
 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;
@@ -256,6 +278,10 @@ interface EngineOptions {
      *  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;
+    /** Called with each content error the engine played through (see {@link PlayError}): a condition
+     *  that failed and counted as false, an effect that failed and was skipped. Unset, each is written
+     *  to `console.warn`, so a content bug is never silent. */
+    onError?: (error: PlayError) => void;
     /** Retain a trace of the engine's DECISIONS (what it chose and why), readable through
      *  `engine.log()` and `flow.log()`. Off by default: a shipped game pays nothing for a
      *  debugging surface it never reads. `onDryChoice` above is unaffected and stays useful
@@ -365,6 +391,8 @@ interface FlowHost {
      *  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;
+    /** Where a content error the engine played through is reported (see PlayError). */
+    onError: (error: PlayError) => void;
     /** Memoised `splitRef` results (ref string -> {scope,name}). The split depends only on the registry's
      *  scope set, so the cache is dropped whenever that moves (`refSplitRevision`). */
     refSplitCache: Map<string, {
@@ -396,6 +424,8 @@ declare class Engine {
     /** The run's ordered stream: every flow's events, each naming its flow. Empty and
      *  unwritten unless `options.log` asked for it. */
     private readonly engineLog;
+    /** The next engine-log `seq`: its own counter, since the log's length restarts after a clear. */
+    private engineSeq;
     private readonly engineTraceHandlers;
     constructor(bundle: Bundle, options?: EngineOptions);
     /** The active locale (string + character-name lookups resolve in it). */
@@ -501,9 +531,12 @@ declare class Engine {
      * is an internal id from any scene. Neither: the bundle's first scene. The same rule on every runtime.
      */
     private resolveOpenAddress;
-    /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
+    /** Resolve a scene reference to its internal id by the one address rule (see resolveScene); an
+     *  unknown one passes through, for the caller to find nothing. */
     private resolveSceneRef;
-    /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
+    /** Resolve a block reference to its internal id by the one address rule (see resolveBlock): within its
+     *  scene, so a block of another scene resolves to nothing. With no scene, only an internal id resolves,
+     *  since a block's gameId is only unique within its scene. */
     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. */
@@ -870,8 +903,12 @@ declare class Flow {
     private matchedSpec;
     /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
     private selectorState;
+    /** Run an effect list. `owner` is the snippet or scene it belongs to, for an error report. */
     private runEffects;
+    /** Whether a node's condition holds. A condition that fails to evaluate counts as false (see PlayError). */
     private eligible;
+    /** Report a content error the engine is playing through: to the host's onError, and to the log. */
+    private reportError;
     private evalExpr;
     /** The deserialised (in-memory) AST for an expression, cached per Expression. Shared by the
      *  evaluator and the Best-match specificity walker so both work off one parse. */
@@ -1095,11 +1132,11 @@ declare function gameDataValue(fields: GameDataField[], node: GameData | undefin
 declare function effectiveGameData(fields: GameDataField[], node: GameData | undefined): GameData;
 
 /**
- * Map every node id (scene / block / group / snippet / beat) to its accumulated
+ * Map every node id (scene / block / group / snippet / beat, prompt beats included) 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 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 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 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

@@ -194,12 +194,34 @@ type TraceEvent = {
     value: ScalarValue;
     prev?: ScalarValue;
 }
-/** An expression that would not evaluate: never a silent pass, always visible. */
+/** Content the engine could not evaluate and played through (see {@link PlayError}): a condition
+ *  counted as false, an effect skipped, or a Best-match part scored as false. */
  | {
     type: "diagnostic";
-    where: string;
+    kind: PlayError["kind"];
+    node: string;
+    source?: string;
     message: string;
 };
+/**
+ * A content error the engine played through. Content can fail at run time in ways the compiler cannot
+ * see: a division by zero, a host value of the wrong type, a story write to a read-only `@world` value.
+ * The story never stops for one. A condition that fails counts as false; an effect that fails is skipped
+ * and the rest of its list still runs; a part of a Best-match condition that fails scores as false. Each
+ * is reported, through `EngineOptions.onError` and as a `diagnostic` entry in the decision log. The same
+ * rule holds on all four runtimes, including the two whose languages cannot throw.
+ */
+interface PlayError {
+    /** The flow it happened in. */
+    flow: string;
+    /** What failed: a condition, an effect, or a part of a condition being scored for Best match. */
+    kind: "condition" | "effect" | "best-match";
+    /** The snippet, group, or option whose condition failed, or that owns the effect (a scene, for its onEntry). */
+    node: string;
+    /** The expression's source text, when the bundle carries it. */
+    source?: string;
+    message: string;
+}
 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;
@@ -256,6 +278,10 @@ interface EngineOptions {
      *  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;
+    /** Called with each content error the engine played through (see {@link PlayError}): a condition
+     *  that failed and counted as false, an effect that failed and was skipped. Unset, each is written
+     *  to `console.warn`, so a content bug is never silent. */
+    onError?: (error: PlayError) => void;
     /** Retain a trace of the engine's DECISIONS (what it chose and why), readable through
      *  `engine.log()` and `flow.log()`. Off by default: a shipped game pays nothing for a
      *  debugging surface it never reads. `onDryChoice` above is unaffected and stays useful
@@ -365,6 +391,8 @@ interface FlowHost {
      *  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;
+    /** Where a content error the engine played through is reported (see PlayError). */
+    onError: (error: PlayError) => void;
     /** Memoised `splitRef` results (ref string -> {scope,name}). The split depends only on the registry's
      *  scope set, so the cache is dropped whenever that moves (`refSplitRevision`). */
     refSplitCache: Map<string, {
@@ -396,6 +424,8 @@ declare class Engine {
     /** The run's ordered stream: every flow's events, each naming its flow. Empty and
      *  unwritten unless `options.log` asked for it. */
     private readonly engineLog;
+    /** The next engine-log `seq`: its own counter, since the log's length restarts after a clear. */
+    private engineSeq;
     private readonly engineTraceHandlers;
     constructor(bundle: Bundle, options?: EngineOptions);
     /** The active locale (string + character-name lookups resolve in it). */
@@ -501,9 +531,12 @@ declare class Engine {
      * is an internal id from any scene. Neither: the bundle's first scene. The same rule on every runtime.
      */
     private resolveOpenAddress;
-    /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
+    /** Resolve a scene reference to its internal id by the one address rule (see resolveScene); an
+     *  unknown one passes through, for the caller to find nothing. */
     private resolveSceneRef;
-    /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
+    /** Resolve a block reference to its internal id by the one address rule (see resolveBlock): within its
+     *  scene, so a block of another scene resolves to nothing. With no scene, only an internal id resolves,
+     *  since a block's gameId is only unique within its scene. */
     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. */
@@ -870,8 +903,12 @@ declare class Flow {
     private matchedSpec;
     /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
     private selectorState;
+    /** Run an effect list. `owner` is the snippet or scene it belongs to, for an error report. */
     private runEffects;
+    /** Whether a node's condition holds. A condition that fails to evaluate counts as false (see PlayError). */
     private eligible;
+    /** Report a content error the engine is playing through: to the host's onError, and to the log. */
+    private reportError;
     private evalExpr;
     /** The deserialised (in-memory) AST for an expression, cached per Expression. Shared by the
      *  evaluator and the Best-match specificity walker so both work off one parse. */
@@ -1095,11 +1132,11 @@ declare function gameDataValue(fields: GameDataField[], node: GameData | undefin
 declare function effectiveGameData(fields: GameDataField[], node: GameData | undefined): GameData;
 
 /**
- * Map every node id (scene / block / group / snippet / beat) to its accumulated
+ * Map every node id (scene / block / group / snippet / beat, prompt beats included) 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 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 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 HostScopeSummary, type LogEntry, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PlayError, type PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };

package/dist/index.js

@@ -21,6 +21,7 @@ function buildTagIndex(bundle) {
   const visit = (node, inherited) => {
     const acc = dedupe([...inherited, ...node.tags ?? []]);
     index.set(node.id, acc);
+    if (node.type === "group" && node.prompt) index.set(node.prompt.id, dedupe([...acc, ...node.prompt.tags ?? []]));
     if (node.type === "group") {
       for (const child of node.children) visit(child, acc);
     } else {
@@ -85,6 +86,8 @@ var Engine = class _Engine {
   /** The run's ordered stream: every flow's events, each naming its flow. Empty and
    *  unwritten unless `options.log` asked for it. */
   engineLog = [];
+  /** The next engine-log `seq`: its own counter, since the log's length restarts after a clear. */
+  engineSeq = 0;
   engineTraceHandlers = /* @__PURE__ */ new Set();
   constructor(bundle, options = {}) {
     this.creationOptions = options;
@@ -182,6 +185,7 @@ var Engine = class _Engine {
       journal: null,
       customRng: options.rng,
       onDryChoice: options.onDryChoice,
+      onError: options.onError ?? ((e) => console.warn(`Patterplay: ${e.kind} on ${e.node} in flow '${e.flow}' failed, played through: ${e.message}`)),
       replayPromptOnChoose: options.replayPromptOnChoose ?? false,
       captionsOn: options.closedCaptions ?? true,
       // captions shown by default (full text)
@@ -375,10 +379,10 @@ var Engine = class _Engine {
    */
   resolveOpenAddress(scene, block) {
     if (scene !== void 0) {
-      const sceneId = this.resolveSceneRef(scene);
-      if (!this.host.bundle.scenes[sceneId]) throw new Error(`unknown scene: ${scene}`);
+      const sceneId = resolveScene(this.host, scene);
+      if (sceneId === void 0) throw new Error(`unknown scene: ${scene}`);
       if (block === void 0) return { sceneId };
-      const blockId = this.blockGameIdToId.get(sceneId)?.get(block) ?? (this.host.blockIndex.get(block)?.sceneId === sceneId ? block : void 0);
+      const blockId = resolveBlock(this.host, sceneId, block);
       if (blockId === void 0) throw new Error(`unknown block: ${block}`);
       return { sceneId, blockId };
     }
@@ -389,21 +393,19 @@ var Engine = class _Engine {
     if (Object.keys(this.host.bundle.scenes).length === 0) throw new Error("no scenes in bundle");
     return {};
   }
-  /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
+  /** Resolve a scene reference to its internal id by the one address rule (see resolveScene); an
+   *  unknown one passes through, for the caller to find nothing. */
   resolveSceneRef(ref) {
     if (ref == null) return void 0;
-    if (this.host.bundle.scenes[ref]) return ref;
-    return this.sceneGameIdToId.get(ref) ?? ref;
+    return resolveScene(this.host, ref) ?? ref;
   }
-  /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
+  /** Resolve a block reference to its internal id by the one address rule (see resolveBlock): within its
+   *  scene, so a block of another scene resolves to nothing. With no scene, only an internal id resolves,
+   *  since a block's gameId is only unique within its scene. */
   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;
+    if (sceneId == null) return ref;
+    return resolveBlock(this.host, sceneId, 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. */
@@ -730,7 +732,7 @@ var Engine = class _Engine {
   emitEngine(flow, event, scene) {
     for (const h of this.engineTraceHandlers) h(flow, event);
     if (!this.host.logEnabled) return;
-    this.engineLog.push({ ...event, flow, seq: this.engineLog.length, ...scene ? { scene } : {} });
+    this.engineLog.push({ ...event, flow, seq: this.engineSeq++, ...scene ? { scene } : {} });
   }
   listProperties() {
     return this.host.patterSharedDecls.map((d) => ({
@@ -796,6 +798,8 @@ var Engine = class _Engine {
     this.refuseInCheckpoint("loadGame");
     const version = save.version;
     if (version !== 2 && version !== SAVE_VERSION) throw new Error(`unsupported save version: ${String(version)}`);
+    const flows = save.flows;
+    if (typeof flows !== "object" || flows === null || Array.isArray(flows)) throw new Error("malformed save: no flows");
     this.assertExternalScopes();
     const reg = this.host.registry;
     for (const [id, flow] of this.flowsById) {
@@ -1019,11 +1023,11 @@ var Flow = class {
       this.stack = [];
       return true;
     }
-    const sceneId = this.host.sceneGameIdToId.get(scene) ?? (this.host.bundle.scenes[scene] ? scene : void 0);
+    const sceneId = resolveScene(this.host, scene);
     if (sceneId === void 0) return false;
     let blockId;
     if (block !== void 0) {
-      blockId = this.host.blockGameIdToId.get(sceneId)?.get(block) ?? (this.host.blockIndex.get(block)?.sceneId === sceneId ? block : void 0);
+      blockId = resolveBlock(this.host, sceneId, block);
       if (blockId === void 0) return false;
     }
     if (!this.started) {
@@ -1133,7 +1137,7 @@ var Flow = class {
       if (this.flowEnded || this.pendingChoice) return;
       if (this.activeSnippet) {
         if (this.beatIndex < (this.activeSnippet.beats?.length ?? 0)) return;
-        this.runEffects(this.activeSnippet.onExit);
+        this.runEffects(this.activeSnippet.onExit, this.activeSnippet.id);
         const jump = this.activeSnippet.jump;
         this.activeSnippet = null;
         this.beatIndex = 0;
@@ -1349,7 +1353,7 @@ var Flow = class {
     this.currentSceneId = sceneId;
     this.enter(sceneId);
     this.seedScene(scene);
-    this.runEffects(scene.onEntry);
+    this.runEffects(scene.onEntry, scene.id);
   }
   /**
    * Play one child of the active run. A snippet begins delivering. A group is
@@ -1385,7 +1389,7 @@ var Flow = class {
     return void 0;
   }
   beginSnippet(snippet) {
-    this.runEffects(snippet.onEnter);
+    this.runEffects(snippet.onEnter, snippet.id);
     this.activeSnippet = snippet;
     this.beatIndex = 0;
   }
@@ -1405,7 +1409,7 @@ var Flow = class {
       options.push({ id: child.id, prompt: this.promptFor(child), eligible, gameData: child.gameData });
       byId.set(child.id, child);
     }
-    if (options.length > 0) {
+    if (options.some((o) => o.eligible)) {
       this.emit({ type: "choice", group: group.id, options: options.map((o) => ({ id: o.id, eligible: o.eligible })) });
       this.pendingChoice = { groupId: group.id, options, byId };
       return;
@@ -1463,7 +1467,7 @@ var Flow = class {
   // -- Selectors ------------------------------------------------------------
   selectChild(group) {
     const verdicts = group.children.map((c) => ({ id: c.id, eligible: this.eligible(c) }));
-    const eligible = group.children.filter((c) => this.eligible(c));
+    const eligible = group.children.filter((_, i) => verdicts[i].eligible);
     const order = group.options?.order ?? "sequential";
     const exhaust = group.options?.exhaust ?? "once";
     const trace = (picked) => {
@@ -1510,8 +1514,9 @@ var Flow = class {
     const len = eligible.length;
     const stick = exhaust === "stick";
     const fill = () => (stick ? eligible.slice(0, len - 1) : eligible).map((c) => c.id);
+    const eligibleIds = new Set(eligible.map((c) => c.id));
     if (st.bag === void 0) st.bag = fill();
-    if (st.bag.length === 0) {
+    if (!st.bag.some((id2) => eligibleIds.has(id2))) {
       if (exhaust === "once") return null;
       if (stick) {
         const last = eligible[len - 1];
@@ -1519,13 +1524,14 @@ var Flow = class {
         return last;
       }
       st.bag = fill();
+      if (st.bag.length === 0) return null;
     }
-    const pool = st.bag;
+    const pool = st.bag.filter((id2) => eligibleIds.has(id2));
     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.bag.splice(st.bag.indexOf(id), 1);
     st.last = id;
     return eligible.find((c) => c.id === id);
   }
@@ -1574,7 +1580,7 @@ var Flow = class {
   /** A child's Best-match score against the current state: 0 when it has no condition (the filler
    *  tier), else the specificity of its (already-passing) condition. */
   specScore(node) {
-    return node.condition ? this.matchedSpec(this.conditionAst(node.condition), true) : 0;
+    return node.condition ? this.matchedSpec(this.conditionAst(node.condition), true, node) : 0;
   }
   /**
    * The **matched-specificity** metric (parity contract): how many atomic constraints are actively
@@ -1584,8 +1590,15 @@ var Flow = class {
    * to hold?" (true at the root). Only `and`/`or`/`not`/`check_flags` are structural; every other
    * node (comparisons, scoped vars, literals, other calls) is an atom, evaluated whole.
    */
-  matchedSpec(node, want) {
-    const evalTruthy = (n) => truthy(evaluate(n, this.context(), patterDialect));
+  matchedSpec(node, want, owner) {
+    const evalTruthy = (n) => {
+      try {
+        return truthy(evaluate(n, this.context(), patterDialect));
+      } catch (err) {
+        this.reportError("best-match", owner.id, owner.condition, err);
+        return false;
+      }
+    };
     return scoreSpecificity(node, evalTruthy, { want });
   }
   /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
@@ -1617,17 +1630,36 @@ var Flow = class {
     return st;
   }
   // -- Effects + expressions ------------------------------------------------
-  runEffects(effects) {
+  /** Run an effect list. `owner` is the snippet or scene it belongs to, for an error report. */
+  runEffects(effects, owner) {
     for (const e of effects ?? []) {
-      const value = this.evalExpr(e.value);
-      const prev = this.host.logEnabled ? this.getProperty(e.target) : void 0;
-      this.writeProperty(e.target, value, false);
-      this.emit({ type: "write", target: e.target, value, ...prev !== void 0 ? { prev } : {} });
+      let value;
+      try {
+        value = this.evalExpr(e.value);
+        const prev = this.host.logEnabled ? this.getProperty(e.target) : void 0;
+        this.writeProperty(e.target, value, false);
+        this.emit({ type: "write", target: e.target, value, ...prev !== void 0 ? { prev } : {} });
+      } catch (err) {
+        this.reportError("effect", owner, e.value, err);
+      }
     }
   }
+  /** Whether a node's condition holds. A condition that fails to evaluate counts as false (see PlayError). */
   eligible(node) {
     if (!node.condition) return true;
-    return truthy(this.evalExpr(node.condition));
+    try {
+      return truthy(this.evalExpr(node.condition));
+    } catch (err) {
+      this.reportError("condition", node.id, node.condition, err);
+      return false;
+    }
+  }
+  /** Report a content error the engine is playing through: to the host's onError, and to the log. */
+  reportError(kind, node, expr, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const source = expr?.src;
+    this.host.onError({ flow: this.id, kind, node, ...source ? { source } : {}, message });
+    this.emit({ type: "diagnostic", kind, node, ...source ? { source } : {}, message });
   }
   evalExpr(expr) {
     return evaluate(this.conditionAst(expr), this.context(), patterDialect);
@@ -1823,23 +1855,23 @@ var Flow = class {
     if (!this.sceneBags.has(s)) {
       const bag = new PropertyBag(props.filter((d) => !shared.has(d.name.toLowerCase())), { pathPrefix: "@scene." });
       const key = keys.flowScene(this.id, s);
-      this.host.registry.mountOwned(key, bag, { owner: OWNER });
+      const claimed = mountClaims(this.host.registry, key, bag, journal !== null);
       this.registered.add(key);
       this.sceneBags.set(s, bag);
       if (journal) journal.undo.push(() => {
         if (this.sceneBags.get(s) !== bag) return;
-        this.host.registry.remove(key);
+        this.host.registry.remove(key, claimed ? { keep: true } : void 0);
         this.registered.delete(key);
         this.sceneBags.delete(s);
       });
     }
     if (!this.host.stageBags.has(s)) {
       const bag = new PropertyBag(props.filter((d) => shared.has(d.name.toLowerCase())), { pathPrefix: "@scene." });
-      this.host.registry.mountOwned(keys.stage(s), bag, { owner: OWNER });
+      const claimed = mountClaims(this.host.registry, keys.stage(s), bag, journal !== null);
       this.host.stageBags.set(s, bag);
       if (journal) journal.undo.push(() => {
         if (this.host.stageBags.get(s) !== bag) return;
-        this.host.registry.remove(keys.stage(s));
+        this.host.registry.remove(keys.stage(s), claimed ? { keep: true } : void 0);
         this.host.stageBags.delete(s);
       });
     }
@@ -1906,6 +1938,11 @@ function deserialiseSelectors(rec) {
   }
   return map;
 }
+function mountClaims(registry, key, bag, ask) {
+  const before = ask ? JSON.stringify(bag.save()) : "";
+  registry.mountOwned(key, bag, { owner: OWNER });
+  return ask && JSON.stringify(bag.save()) !== before;
+}
 function toDecl(decl) {
   return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default };
 }
@@ -1917,6 +1954,12 @@ function selfBackedDecl(decl, scopeWritable) {
   const writable = decl.writable ?? scopeWritable;
   return writable === void 0 ? d : { ...d, writable };
 }
+function resolveScene(host, ref) {
+  return host.sceneGameIdToId.get(ref) ?? (host.bundle.scenes[ref] ? ref : void 0);
+}
+function resolveBlock(host, sceneId, ref) {
+  return host.blockGameIdToId.get(sceneId)?.get(ref) ?? (host.blockIndex.get(ref)?.sceneId === sceneId ? ref : void 0);
+}
 function splitHostRef(host, ref) {
   if (host.refSplitRevision !== host.registry.revision) {
     host.refSplitCache.clear();