@patterkit/runtime 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, PropertyBag, ScopeDeclaration, LogMount, PropertyRow } from '@wildwinter/scoperegistry';
+import { ScopeRegistry, PropertyBag, ScopeDeclaration, LogMount, ScopeResolver, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
 import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, SaveGameV2, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
 export { Bundle, EngineSave, FlowCursor, FlowSnapshot, SaveEnvelope, SaveGame, SavedChoice, SavedChoiceOption, SavedChoicePrompt, SelectorSnapshot, StackFrame } from '@patterkit/model';
@@ -277,6 +277,25 @@ interface SelectorState {
     bag?: string[];
     last?: string;
 }
+/** What an open checkpoint records: how to undo each change, newest last. Each piece of state records
+ *  itself when it changes (a value, a count, a cursor), never a copy of everything, so a checkpoint costs
+ *  what the steps inside it do, however much history the game has built up. */
+interface Journal {
+    undo: Array<() => void>;
+    /** Flows already snapshotted (or opened inside the checkpoint, so closed on rollback). */
+    flows: Set<Flow>;
+    /** Flows opened inside the checkpoint. */
+    opened: Set<Flow>;
+    /** Selector cursors already copied: shared ones by group id, a flow's own in `flowSelectors`. */
+    selectors: Set<string>;
+    flowSelectors: Map<Flow, Set<string>>;
+}
+/** An open checkpoint, from {@link Engine.checkpoint}. Opaque: hand it back to `rollback` or `commit`. */
+declare class Checkpoint {
+    readonly journal: Journal;
+    /** @internal */
+    constructor(journal: Journal);
+}
 /** Shared, read-mostly context the engine hands to every flow it owns. */
 interface FlowHost {
     /** True when the run asked for a log; flows skip building entries otherwise. */
@@ -328,6 +347,8 @@ interface FlowHost {
     /** Per-scene SHARED scene props, each registered under `keys.stage(sceneId)`. Made the first time any
      *  flow needs the scene, so a bag loaded before then waits in the registry and is claimed here. */
     stageBags: Map<string, PropertyBag>;
+    /** The open checkpoint's undo journal, or null when none is open (see {@link Engine.checkpoint}). */
+    journal: Journal | null;
     customRng?: () => number;
     /** Play a chosen option's prompt as its first beat (spec §5); default false. */
     replayPromptOnChoose?: boolean;
@@ -438,6 +459,10 @@ declare class Engine {
      *
      * Contrast {@link runFlow}, which REUSES a flow of the same name instead of replacing it - that is the
      * call to reach for when you want a speaker's variation state to carry on.
+     *
+     * THROWS on an address that does not resolve (an unknown scene, or a block that is not in the named
+     * scene), before anything changes: nothing is opened, and a flow already open under `id` carries on
+     * exactly as it was.
      */
     openFlow(id: string, opts?: OpenFlowOptions): Flow;
     /**
@@ -469,6 +494,13 @@ declare class Engine {
      *  it opens (or the save as it loads), before anything changes. By then a game has built all of its
      *  engines, whatever order it built them in. The same message on every runtime. */
     private assertExternalScopes;
+    /**
+     * `openFlow`'s address as internal ids, or a throw when it does not resolve. With a scene, the block is
+     * scene-scoped exactly as {@link Flow.goto} resolves it (a gameId address in that scene, or the internal
+     * id of a block in that scene), so a block from another scene does not resolve. With no scene, the block
+     * 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. */
     private resolveSceneRef;
     /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
@@ -548,6 +580,34 @@ declare class Engine {
      * loadGame() replaces every bag, so re-enumerate after a load.
      */
     listBags(): LogMount[];
+    /**
+     * Open a checkpoint: from here until `rollback` or `commit`, the engine keeps what it needs to undo
+     * every change the story makes. `rollback` puts the game back exactly as it was at the checkpoint:
+     * property values (every scope, including a host's `@world`, which is written back through the
+     * game), visit counts, shuffle and sequence positions, `@scene` bags made since, every flow's cursor
+     * and PRNG, and any flow opened since (closed and forgotten). `commit` keeps everything and stops
+     * recording.
+     *
+     * The use is asking "would this say anything?" without consequences: move a flow to an address,
+     * advance it, and roll back if it had nothing to give, so its scene's `onEntry` effects, its visits,
+     * and its shuffle draws never happened.
+     *
+     * One checkpoint at a time. Inside one, the calls that replace or drop flows or their bags wholesale
+     * (`reset`, `loadGame`, `hotSwap`, `closeFlow`, `openFlow` on the name of an open flow, and a flow's own
+     * `start`, `reset`, and `restore`) throw. Not undone:
+     * trace and log events already emitted, and draws from a custom `rng` the game supplied.
+     */
+    checkpoint(): Checkpoint;
+    /** Undo everything since `checkpoint` (see there), and close it. */
+    rollback(checkpoint: Checkpoint): void;
+    /** Keep everything since `checkpoint`, and close it. */
+    commit(checkpoint: Checkpoint): void;
+    /** True while a checkpoint is open. */
+    get inCheckpoint(): boolean;
+    private endCheckpoint;
+    /** Let go of what a closed checkpoint recorded, so a handle the game keeps holds nothing. */
+    private static forget;
+    private refuseInCheckpoint;
     /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
      *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
     closeFlow(id: string): void;
@@ -686,6 +746,10 @@ declare class Flow {
      * cannot quietly mutate the world. Terminal: unlike ending, a close is never revived.
      */
     close(): void;
+    /** Inside a checkpoint, the first change to this flow records its cursor and PRNG, so a rollback can
+     *  put them back: a handful of fields and a copy of the call stack (a few frames), never its history.
+     *  Its visits, selector cursors, and property values are recorded change by change as they happen. */
+    private touch;
     /** True once the engine has closed this flow (closed, dropped by `reset()`, or replaced by name). */
     get isClosed(): boolean;
     /** The scene the cursor is currently in - set on entry and whenever a jump crosses scenes. Read
@@ -739,8 +803,11 @@ declare class Flow {
     private writeProperty;
     /** @internal Snapshot this flow's cursor + PRNG + visits. Its properties are the registry's. */
     snapshot(): FlowSnapshot;
-    /** @internal Restore this flow from a snapshot. */
+    /** @internal Restore this flow from a snapshot: its cursor, PRNG, visits, and selector cursors. Its
+     *  property values are the registry's and stay as they are (a load puts the saved ones there first). */
     restore(snap: FlowSnapshot): void;
+    /** The cursor half of `restore`, without touching the bags (a rollback has already put those back). */
+    private restoreCursor;
     /** Set the current scene, reset its scene-local props, run onEntry. */
     private enterSceneSetup;
     /**
@@ -1027,4 +1094,4 @@ declare function effectiveGameData(fields: GameDataField[], node: GameData | und
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, 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 PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, PropertyBag, ScopeDeclaration, LogMount, PropertyRow } from '@wildwinter/scoperegistry';
+import { ScopeRegistry, PropertyBag, ScopeDeclaration, LogMount, ScopeResolver, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
 import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, FlowSnapshot, EngineSave, SaveGame, SaveGameV2, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
 export { Bundle, EngineSave, FlowCursor, FlowSnapshot, SaveEnvelope, SaveGame, SavedChoice, SavedChoiceOption, SavedChoicePrompt, SelectorSnapshot, StackFrame } from '@patterkit/model';
@@ -277,6 +277,25 @@ interface SelectorState {
     bag?: string[];
     last?: string;
 }
+/** What an open checkpoint records: how to undo each change, newest last. Each piece of state records
+ *  itself when it changes (a value, a count, a cursor), never a copy of everything, so a checkpoint costs
+ *  what the steps inside it do, however much history the game has built up. */
+interface Journal {
+    undo: Array<() => void>;
+    /** Flows already snapshotted (or opened inside the checkpoint, so closed on rollback). */
+    flows: Set<Flow>;
+    /** Flows opened inside the checkpoint. */
+    opened: Set<Flow>;
+    /** Selector cursors already copied: shared ones by group id, a flow's own in `flowSelectors`. */
+    selectors: Set<string>;
+    flowSelectors: Map<Flow, Set<string>>;
+}
+/** An open checkpoint, from {@link Engine.checkpoint}. Opaque: hand it back to `rollback` or `commit`. */
+declare class Checkpoint {
+    readonly journal: Journal;
+    /** @internal */
+    constructor(journal: Journal);
+}
 /** Shared, read-mostly context the engine hands to every flow it owns. */
 interface FlowHost {
     /** True when the run asked for a log; flows skip building entries otherwise. */
@@ -328,6 +347,8 @@ interface FlowHost {
     /** Per-scene SHARED scene props, each registered under `keys.stage(sceneId)`. Made the first time any
      *  flow needs the scene, so a bag loaded before then waits in the registry and is claimed here. */
     stageBags: Map<string, PropertyBag>;
+    /** The open checkpoint's undo journal, or null when none is open (see {@link Engine.checkpoint}). */
+    journal: Journal | null;
     customRng?: () => number;
     /** Play a chosen option's prompt as its first beat (spec §5); default false. */
     replayPromptOnChoose?: boolean;
@@ -438,6 +459,10 @@ declare class Engine {
      *
      * Contrast {@link runFlow}, which REUSES a flow of the same name instead of replacing it - that is the
      * call to reach for when you want a speaker's variation state to carry on.
+     *
+     * THROWS on an address that does not resolve (an unknown scene, or a block that is not in the named
+     * scene), before anything changes: nothing is opened, and a flow already open under `id` carries on
+     * exactly as it was.
      */
     openFlow(id: string, opts?: OpenFlowOptions): Flow;
     /**
@@ -469,6 +494,13 @@ declare class Engine {
      *  it opens (or the save as it loads), before anything changes. By then a game has built all of its
      *  engines, whatever order it built them in. The same message on every runtime. */
     private assertExternalScopes;
+    /**
+     * `openFlow`'s address as internal ids, or a throw when it does not resolve. With a scene, the block is
+     * scene-scoped exactly as {@link Flow.goto} resolves it (a gameId address in that scene, or the internal
+     * id of a block in that scene), so a block from another scene does not resolve. With no scene, the block
+     * 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. */
     private resolveSceneRef;
     /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */
@@ -548,6 +580,34 @@ declare class Engine {
      * loadGame() replaces every bag, so re-enumerate after a load.
      */
     listBags(): LogMount[];
+    /**
+     * Open a checkpoint: from here until `rollback` or `commit`, the engine keeps what it needs to undo
+     * every change the story makes. `rollback` puts the game back exactly as it was at the checkpoint:
+     * property values (every scope, including a host's `@world`, which is written back through the
+     * game), visit counts, shuffle and sequence positions, `@scene` bags made since, every flow's cursor
+     * and PRNG, and any flow opened since (closed and forgotten). `commit` keeps everything and stops
+     * recording.
+     *
+     * The use is asking "would this say anything?" without consequences: move a flow to an address,
+     * advance it, and roll back if it had nothing to give, so its scene's `onEntry` effects, its visits,
+     * and its shuffle draws never happened.
+     *
+     * One checkpoint at a time. Inside one, the calls that replace or drop flows or their bags wholesale
+     * (`reset`, `loadGame`, `hotSwap`, `closeFlow`, `openFlow` on the name of an open flow, and a flow's own
+     * `start`, `reset`, and `restore`) throw. Not undone:
+     * trace and log events already emitted, and draws from a custom `rng` the game supplied.
+     */
+    checkpoint(): Checkpoint;
+    /** Undo everything since `checkpoint` (see there), and close it. */
+    rollback(checkpoint: Checkpoint): void;
+    /** Keep everything since `checkpoint`, and close it. */
+    commit(checkpoint: Checkpoint): void;
+    /** True while a checkpoint is open. */
+    get inCheckpoint(): boolean;
+    private endCheckpoint;
+    /** Let go of what a closed checkpoint recorded, so a handle the game keeps holds nothing. */
+    private static forget;
+    private refuseInCheckpoint;
     /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
      *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
     closeFlow(id: string): void;
@@ -686,6 +746,10 @@ declare class Flow {
      * cannot quietly mutate the world. Terminal: unlike ending, a close is never revived.
      */
     close(): void;
+    /** Inside a checkpoint, the first change to this flow records its cursor and PRNG, so a rollback can
+     *  put them back: a handful of fields and a copy of the call stack (a few frames), never its history.
+     *  Its visits, selector cursors, and property values are recorded change by change as they happen. */
+    private touch;
     /** True once the engine has closed this flow (closed, dropped by `reset()`, or replaced by name). */
     get isClosed(): boolean;
     /** The scene the cursor is currently in - set on entry and whenever a jump crosses scenes. Read
@@ -739,8 +803,11 @@ declare class Flow {
     private writeProperty;
     /** @internal Snapshot this flow's cursor + PRNG + visits. Its properties are the registry's. */
     snapshot(): FlowSnapshot;
-    /** @internal Restore this flow from a snapshot. */
+    /** @internal Restore this flow from a snapshot: its cursor, PRNG, visits, and selector cursors. Its
+     *  property values are the registry's and stay as they are (a load puts the saved ones there first). */
     restore(snap: FlowSnapshot): void;
+    /** The cursor half of `restore`, without touching the bags (a rollback has already put those back). */
+    private restoreCursor;
     /** Set the current scene, reset its scene-local props, run onEntry. */
     private enterSceneSetup;
     /**
@@ -1027,4 +1094,4 @@ declare function effectiveGameData(fields: GameDataField[], node: GameData | und
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, 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 PropertySummary, type StepResult, type TraceEvent, type TraceHandler, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };

package/dist/index.js

@@ -55,6 +55,13 @@ var keys = {
   /** A flow's NOT-shared `@scene` props for one scene. */
   flowScene: (flowId, sceneId) => `patter/flow/${esc(flowId)}/scene/${esc(sceneId)}`
 };
+var Checkpoint = class {
+  /** @internal */
+  constructor(journal) {
+    this.journal = journal;
+  }
+  journal;
+};
 var Engine = class _Engine {
   host;
   defaultSeed;
@@ -172,6 +179,7 @@ var Engine = class _Engine {
       sharedVisits: /* @__PURE__ */ new Map(),
       sharedSelectors: /* @__PURE__ */ new Map(),
       stageBags: /* @__PURE__ */ new Map(),
+      journal: null,
       customRng: options.rng,
       onDryChoice: options.onDryChoice,
       replayPromptOnChoose: options.replayPromptOnChoose ?? false,
@@ -235,6 +243,7 @@ var Engine = class _Engine {
    * top of the scene it was in; the shared properties carry over.
    */
   hotSwap(bundle) {
+    this.refuseInCheckpoint("hotSwap");
     const snapshot = this.saveGame();
     const carryOver = (next2) => {
       next2.setLocale(this.currentLocale);
@@ -290,13 +299,28 @@ var Engine = class _Engine {
    *
    * Contrast {@link runFlow}, which REUSES a flow of the same name instead of replacing it - that is the
    * call to reach for when you want a speaker's variation state to carry on.
+   *
+   * THROWS on an address that does not resolve (an unknown scene, or a block that is not in the named
+   * scene), before anything changes: nothing is opened, and a flow already open under `id` carries on
+   * exactly as it was.
    */
   openFlow(id, opts = {}) {
     this.assertExternalScopes();
-    const sceneId = this.resolveSceneRef(opts.scene);
-    const blockId = this.resolveBlockRef(sceneId, opts.block);
-    this.flowsById.get(id)?.close();
+    const { sceneId, blockId } = this.resolveOpenAddress(opts.scene, opts.block);
+    const prior = this.flowsById.get(id);
+    const journal = this.host.journal;
+    if (journal && prior && !prior.isClosed) throw new Error(`openFlow would replace the open flow '${id}', which can't be undone while a checkpoint is open`);
+    prior?.close();
     const flow = new Flow(id, this.host, opts.seed ?? this.defaultSeed);
+    if (journal) {
+      journal.flows.add(flow);
+      journal.opened.add(flow);
+      journal.undo.push(() => {
+        flow.close();
+        if (prior) this.flowsById.set(id, prior);
+        else this.flowsById.delete(id);
+      });
+    }
     this.flowsById.set(id, flow);
     flow.start(sceneId, blockId);
     return flow;
@@ -343,6 +367,28 @@ var Engine = class _Engine {
       }
     }
   }
+  /**
+   * `openFlow`'s address as internal ids, or a throw when it does not resolve. With a scene, the block is
+   * scene-scoped exactly as {@link Flow.goto} resolves it (a gameId address in that scene, or the internal
+   * id of a block in that scene), so a block from another scene does not resolve. With no scene, the block
+   * is an internal id from any scene. Neither: the bundle's first scene. The same rule on every runtime.
+   */
+  resolveOpenAddress(scene, block) {
+    if (scene !== void 0) {
+      const sceneId = this.resolveSceneRef(scene);
+      if (!this.host.bundle.scenes[sceneId]) 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);
+      if (blockId === void 0) throw new Error(`unknown block: ${block}`);
+      return { sceneId, blockId };
+    }
+    if (block !== void 0) {
+      if (!this.host.blockIndex.has(block)) throw new Error(`unknown block: ${block}`);
+      return { blockId: block };
+    }
+    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. */
   resolveSceneRef(ref) {
     if (ref == null) return void 0;
@@ -552,9 +598,64 @@ var Engine = class _Engine {
     for (const [sceneId, bag] of this.host.stageBags) mounts.push({ bag, pathPrefix: `@scene:${sceneId}.` });
     return mounts;
   }
+  /**
+   * Open a checkpoint: from here until `rollback` or `commit`, the engine keeps what it needs to undo
+   * every change the story makes. `rollback` puts the game back exactly as it was at the checkpoint:
+   * property values (every scope, including a host's `@world`, which is written back through the
+   * game), visit counts, shuffle and sequence positions, `@scene` bags made since, every flow's cursor
+   * and PRNG, and any flow opened since (closed and forgotten). `commit` keeps everything and stops
+   * recording.
+   *
+   * The use is asking "would this say anything?" without consequences: move a flow to an address,
+   * advance it, and roll back if it had nothing to give, so its scene's `onEntry` effects, its visits,
+   * and its shuffle draws never happened.
+   *
+   * One checkpoint at a time. Inside one, the calls that replace or drop flows or their bags wholesale
+   * (`reset`, `loadGame`, `hotSwap`, `closeFlow`, `openFlow` on the name of an open flow, and a flow's own
+   * `start`, `reset`, and `restore`) throw. Not undone:
+   * trace and log events already emitted, and draws from a custom `rng` the game supplied.
+   */
+  checkpoint() {
+    if (this.host.journal) throw new Error("a checkpoint is already open: roll it back or commit it first");
+    const journal = { undo: [], flows: /* @__PURE__ */ new Set(), opened: /* @__PURE__ */ new Set(), selectors: /* @__PURE__ */ new Set(), flowSelectors: /* @__PURE__ */ new Map() };
+    this.host.journal = journal;
+    return new Checkpoint(journal);
+  }
+  /** Undo everything since `checkpoint` (see there), and close it. */
+  rollback(checkpoint) {
+    this.endCheckpoint(checkpoint);
+    const undo = checkpoint.journal.undo;
+    for (let i = undo.length - 1; i >= 0; i--) undo[i]();
+    _Engine.forget(checkpoint.journal);
+  }
+  /** Keep everything since `checkpoint`, and close it. */
+  commit(checkpoint) {
+    this.endCheckpoint(checkpoint);
+    _Engine.forget(checkpoint.journal);
+  }
+  /** True while a checkpoint is open. */
+  get inCheckpoint() {
+    return this.host.journal !== null;
+  }
+  endCheckpoint(checkpoint) {
+    if (this.host.journal !== checkpoint.journal) throw new Error("that checkpoint is not the open one");
+    this.host.journal = null;
+  }
+  /** Let go of what a closed checkpoint recorded, so a handle the game keeps holds nothing. */
+  static forget(journal) {
+    journal.undo = [];
+    journal.flows.clear();
+    journal.opened.clear();
+    journal.selectors.clear();
+    journal.flowSelectors.clear();
+  }
+  refuseInCheckpoint(what) {
+    if (this.host.journal) throw new Error(`${what} can't be undone, so it isn't allowed while a checkpoint is open`);
+  }
   /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
    *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
   closeFlow(id) {
+    this.refuseInCheckpoint("closeFlow");
     this.flowsById.get(id)?.close();
     this.flowsById.delete(id);
   }
@@ -565,6 +666,7 @@ var Engine = class _Engine {
    * After reset, open fresh flows with `openFlow`.
    */
   reset() {
+    this.refuseInCheckpoint("reset");
     for (const flow of this.flowsById.values()) flow.close();
     this.flowsById.clear();
     this.host.patterBag.reseed(this.host.patterSharedDecls);
@@ -602,7 +704,9 @@ var Engine = class _Engine {
    *  were each refused the one property they existed to move.) */
   setProperty(ref, value) {
     const { scope, name } = this.splitShared(ref);
+    const prev = this.host.journal ? this.host.registry.get(scope, name) : void 0;
     this.host.registry.set(scope, name, value, { host: true });
+    if (this.host.journal && prev !== void 0) this.host.journal.undo.push(() => this.host.registry.set(scope, name, prev, { host: true }));
   }
   /** 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. */
@@ -689,6 +793,7 @@ var Engine = class _Engine {
    * to the registry (values kept) and the restored flows claim them as they register.
    */
   loadGame(save) {
+    this.refuseInCheckpoint("loadGame");
     const version = save.version;
     if (version !== 2 && version !== SAVE_VERSION) throw new Error(`unsupported save version: ${String(version)}`);
     this.assertExternalScopes();
@@ -839,6 +944,7 @@ var Flow = class {
   // -- Host API -------------------------------------------------------------
   /** Begin this flow at a scene (and optionally a specific block within it). */
   start(sceneId, blockId) {
+    if (this.host.journal && !this.host.journal.opened.has(this)) throw new Error("a flow can't be started or reset while a checkpoint is open");
     this.releaseBags(false);
     this.host.registry.discardParked(keys.flow(this.id));
     this.mountLocal();
@@ -898,6 +1004,7 @@ var Flow = class {
    */
   goto(scene, block) {
     if (this.closed) return false;
+    this.touch();
     if (scene === "END") {
       this.started = true;
       this.pendingChoice = null;
@@ -951,6 +1058,19 @@ var Flow = class {
     this.pendingPromptBeat = null;
     this.pendingPromptOwnerId = null;
   }
+  /** Inside a checkpoint, the first change to this flow records its cursor and PRNG, so a rollback can
+   *  put them back: a handful of fields and a copy of the call stack (a few frames), never its history.
+   *  Its visits, selector cursors, and property values are recorded change by change as they happen. */
+  touch() {
+    const journal = this.host.journal;
+    if (!journal || journal.flows.has(this)) return;
+    journal.flows.add(this);
+    const { rngState, started, flowEnded, currentSceneId, activeSnippet, beatIndex, pendingChoice, pendingPromptBeat, pendingPromptOwnerId } = this;
+    const stack = this.stack.map((f) => ({ ...f }));
+    journal.undo.push(() => {
+      Object.assign(this, { rngState, started, flowEnded, currentSceneId, activeSnippet, beatIndex, pendingChoice, pendingPromptBeat, pendingPromptOwnerId, stack });
+    });
+  }
   /** True once the engine has closed this flow (closed, dropped by `reset()`, or replaced by name). */
   get isClosed() {
     return this.closed;
@@ -965,6 +1085,7 @@ var Flow = class {
   advance() {
     if (this.closed) return { type: "end" };
     if (!this.started) throw new Error("flow has not been started");
+    this.touch();
     if (this.pendingPromptBeat) {
       const b = this.pendingPromptBeat;
       this.pendingPromptBeat = null;
@@ -1084,6 +1205,7 @@ var Flow = class {
     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}`);
+    this.touch();
     const node = choice.byId.get(id);
     this.emit({ type: "chose", group: choice.groupId, option: id });
     this.pendingChoice = null;
@@ -1111,13 +1233,27 @@ var Flow = class {
    *  about: the story is refused, the game is not. */
   writeProperty(ref, value, host) {
     const { scope, name } = this.splitRef(ref);
+    const journal = this.host.journal;
     if (scope === "patter") {
+      if (journal) {
+        const shared = this.host.patterSharedNames.has(name);
+        const prev = shared ? this.host.patterBag.get(name) : this.local.get(name);
+        const bag = this.local;
+        if (prev !== void 0) journal.undo.push(shared ? () => this.host.registry.set("patter", name, prev) : () => bag.set(name, prev));
+      }
       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`);
+      if (journal) {
+        const bag = this.sceneBagFor(this.currentSceneId, name);
+        const prev = bag?.get(name);
+        if (bag && prev !== void 0) journal.undo.push(() => bag.set(name, prev));
+      }
       this.sceneResolver.set(name, value);
     } else {
+      const prev = journal ? this.host.registry.get(scope, name) : void 0;
       this.host.registry.set(scope, name, value, host ? { host: true } : void 0);
+      if (journal && prev !== void 0) journal.undo.push(() => this.host.registry.set(scope, name, prev, { host: true }));
     }
   }
   // -- Save / restore (engine-driven) --------------------------------------
@@ -1144,8 +1280,19 @@ var Flow = class {
       }
     };
   }
-  /** @internal Restore this flow from a snapshot. */
+  /** @internal Restore this flow from a snapshot: its cursor, PRNG, visits, and selector cursors. Its
+   *  property values are the registry's and stay as they are (a load puts the saved ones there first). */
   restore(snap) {
+    if (this.host.journal) throw new Error("a flow can't be restored while a checkpoint is open");
+    this.restoreCursor(snap);
+    this.releaseBags(true);
+    this.mountLocal();
+    for (const s of /* @__PURE__ */ new Set([this.currentSceneId, ...this.stack.map((f) => f.sceneId)])) {
+      if (s !== null && this.host.bundle.scenes[s]) this.ensureSceneBags(s);
+    }
+  }
+  /** The cursor half of `restore`, without touching the bags (a rollback has already put those back). */
+  restoreCursor(snap) {
     this.rngState = toUint32(snap.rngState);
     this.visitCounts = new Map(Object.entries(snap.visits ?? {}));
     const c = snap.cursor;
@@ -1161,11 +1308,6 @@ var Flow = class {
       }
       return { ...frame };
     });
-    this.releaseBags(false);
-    this.mountLocal();
-    for (const s of /* @__PURE__ */ new Set([c.currentSceneId, ...this.stack.map((f) => f.sceneId)])) {
-      if (s !== null && this.host.bundle.scenes[s]) this.ensureSceneBags(s);
-    }
     this.activeSnippet = null;
     if (c.activeSnippetId !== null) {
       const node = this.host.nodeIndex.get(c.activeSnippetId);
@@ -1442,6 +1584,24 @@ var Flow = class {
   /** 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;
+    const journal = this.host.journal;
+    let seen;
+    if (journal) {
+      seen = group.shared ? journal.selectors : journal.flowSelectors.get(this);
+      if (!seen) {
+        seen = /* @__PURE__ */ new Set();
+        journal.flowSelectors.set(this, seen);
+      }
+    }
+    if (journal && seen && !seen.has(group.id)) {
+      seen.add(group.id);
+      const was = map.get(group.id);
+      const copy = was ? { ...was, ...was.bag ? { bag: [...was.bag] } : {} } : void 0;
+      journal.undo.push(() => {
+        if (copy) map.set(group.id, copy);
+        else map.delete(group.id);
+      });
+    }
     let st = map.get(group.id);
     if (!st) {
       st = {};
@@ -1477,8 +1637,18 @@ var Flow = class {
   }
   /** 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);
+    const own = this.visitCounts;
+    const ownBefore = own.get(id);
+    own.set(id, (ownBefore ?? 0) + 1);
+    const shared = this.host.sharedVisits;
+    const before = shared.get(id);
+    shared.set(id, (before ?? 0) + 1);
+    if (this.host.journal) this.host.journal.undo.push(() => {
+      if (ownBefore === void 0) own.delete(id);
+      else own.set(id, ownBefore);
+      if (before === void 0) shared.delete(id);
+      else shared.set(id, before);
+    });
   }
   /** Next float in [0, 1): the shared custom PRNG, or this flow's serialisable mulberry32.
    *
@@ -1621,17 +1791,29 @@ var Flow = class {
   ensureSceneBags(s) {
     const shared = this.host.sceneSharedNames.get(s) ?? /* @__PURE__ */ new Set();
     const props = this.host.bundle.scenes[s]?.sceneProps ?? [];
+    const journal = this.host.journal;
     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 });
       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.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 });
       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.stageBags.delete(s);
+      });
     }
   }
   /**
@@ -1648,7 +1830,10 @@ var Flow = class {
       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.set(name, defaultFor(decl));
+      if (!bag) continue;
+      const prev = this.host.journal ? bag.get(name) : void 0;
+      if (prev !== void 0) this.host.journal.undo.push(() => bag.set(name, prev));
+      bag.set(name, defaultFor(decl));
     }
   }
 };
@@ -1847,6 +2032,7 @@ function effectiveGameData(fields, node) {
   return out;
 }
 export {
+  Checkpoint,
   Engine,
   Flow,
   buildTagIndex,