@patterkit/runtime 0.14.3 → 0.16.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';
@@ -69,6 +69,8 @@ interface OutlineBlock {
     id: string;
     gameId?: string;
     name: string;
+    /** The block's own author gameData overrides (raw, not merged with defaults). Omitted when empty. */
+    gameData?: GameData;
     tags?: string[];
     children: OutlineNode[];
 }
@@ -77,6 +79,8 @@ interface OutlineScene {
     id: string;
     gameId?: string;
     name: string;
+    /** The scene's own author gameData overrides (raw, not merged with defaults). Omitted when empty. */
+    gameData?: GameData;
     tags?: string[];
     blocks: OutlineBlock[];
 }
@@ -273,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. */
@@ -324,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;
@@ -483,6 +508,16 @@ declare class Engine {
     tagsForScene(sceneRef: string): string[];
     /** A block's accumulated tags (scene + block), by scene + block ref (id or gameId). Empty when none / unknown. */
     tagsForBlock(sceneRef: string, blockRef: string): string[];
+    /**
+     * A scene's own author gameData (by internal id or gameId address): the RAW sparse overrides, exactly
+     * as a beat's step carries its own, not merged with the project's declared field defaults (resolve
+     * those with `effectiveGameData(gameDataFields(bundle, "scene"), ...)`). Not inherited by its blocks.
+     * A fresh object each call; empty when the scene sets none or the ref is unknown.
+     */
+    gameDataForScene(sceneRef: string): GameData;
+    /** A block's own author gameData, by scene + block ref (id or gameId). Raw overrides, like
+     *  {@link gameDataForScene}; the scene's gameData is not folded in. Empty when none / unknown. */
+    gameDataForBlock(sceneRef: string, blockRef: string): GameData;
     /**
      * Every cast member the PROJECT declares, in authored order - the same list `describeBundle` counts.
      * A superset of any scene's cast: the validator holds a beat's `character` to a declared member, so
@@ -534,6 +569,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;
@@ -672,6 +735,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
@@ -725,8 +792,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;
     /**
@@ -1013,4 +1083,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';
@@ -69,6 +69,8 @@ interface OutlineBlock {
     id: string;
     gameId?: string;
     name: string;
+    /** The block's own author gameData overrides (raw, not merged with defaults). Omitted when empty. */
+    gameData?: GameData;
     tags?: string[];
     children: OutlineNode[];
 }
@@ -77,6 +79,8 @@ interface OutlineScene {
     id: string;
     gameId?: string;
     name: string;
+    /** The scene's own author gameData overrides (raw, not merged with defaults). Omitted when empty. */
+    gameData?: GameData;
     tags?: string[];
     blocks: OutlineBlock[];
 }
@@ -273,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. */
@@ -324,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;
@@ -483,6 +508,16 @@ declare class Engine {
     tagsForScene(sceneRef: string): string[];
     /** A block's accumulated tags (scene + block), by scene + block ref (id or gameId). Empty when none / unknown. */
     tagsForBlock(sceneRef: string, blockRef: string): string[];
+    /**
+     * A scene's own author gameData (by internal id or gameId address): the RAW sparse overrides, exactly
+     * as a beat's step carries its own, not merged with the project's declared field defaults (resolve
+     * those with `effectiveGameData(gameDataFields(bundle, "scene"), ...)`). Not inherited by its blocks.
+     * A fresh object each call; empty when the scene sets none or the ref is unknown.
+     */
+    gameDataForScene(sceneRef: string): GameData;
+    /** A block's own author gameData, by scene + block ref (id or gameId). Raw overrides, like
+     *  {@link gameDataForScene}; the scene's gameData is not folded in. Empty when none / unknown. */
+    gameDataForBlock(sceneRef: string, blockRef: string): GameData;
     /**
      * Every cast member the PROJECT declares, in authored order - the same list `describeBundle` counts.
      * A superset of any scene's cast: the validator holds a beat's `character` to a declared member, so
@@ -534,6 +569,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;
@@ -672,6 +735,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
@@ -725,8 +792,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;
     /**
@@ -1013,4 +1083,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);
@@ -295,8 +304,20 @@ var Engine = class _Engine {
     this.assertExternalScopes();
     const sceneId = this.resolveSceneRef(opts.scene);
     const blockId = this.resolveBlockRef(sceneId, opts.block);
-    this.flowsById.get(id)?.close();
+    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;
@@ -388,6 +409,24 @@ var Engine = class _Engine {
     const id = this.resolveBlockRef(sceneId, blockRef);
     return (id != null ? this.host.tagIndex.get(id) : void 0) ?? [];
   }
+  /**
+   * A scene's own author gameData (by internal id or gameId address): the RAW sparse overrides, exactly
+   * as a beat's step carries its own, not merged with the project's declared field defaults (resolve
+   * those with `effectiveGameData(gameDataFields(bundle, "scene"), ...)`). Not inherited by its blocks.
+   * A fresh object each call; empty when the scene sets none or the ref is unknown.
+   */
+  gameDataForScene(sceneRef) {
+    const id = this.resolveSceneRef(sceneRef);
+    const scene = id != null ? this.host.bundle.scenes[id] : void 0;
+    return { ...scene?.gameData };
+  }
+  /** A block's own author gameData, by scene + block ref (id or gameId). Raw overrides, like
+   *  {@link gameDataForScene}; the scene's gameData is not folded in. Empty when none / unknown. */
+  gameDataForBlock(sceneRef, blockRef) {
+    const id = this.resolveBlockRef(this.resolveSceneRef(sceneRef), blockRef);
+    const block = id != null ? this.host.blockById.get(id) : void 0;
+    return { ...block?.gameData };
+  }
   /**
    * Every cast member the PROJECT declares, in authored order - the same list `describeBundle` counts.
    * A superset of any scene's cast: the validator holds a beat's `character` to a declared member, so
@@ -434,11 +473,13 @@ var Engine = class _Engine {
       id: scene.id,
       ...effectiveGameId(scene) ? { gameId: effectiveGameId(scene) } : {},
       name: scene.name,
+      ...gameDataField(scene.gameData),
       ...this.tagsField(scene.id),
       blocks: scene.blocks.map((block) => ({
         id: block.id,
         ...effectiveGameId(block) ? { gameId: effectiveGameId(block) } : {},
         name: block.name,
+        ...gameDataField(block.gameData),
         ...this.tagsField(block.id),
         children: block.children.map((n) => this.outlineNode(n))
       }))
@@ -532,9 +573,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);
   }
@@ -545,6 +641,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);
@@ -582,7 +679,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. */
@@ -669,6 +768,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();
@@ -819,6 +919,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();
@@ -878,6 +979,7 @@ var Flow = class {
    */
   goto(scene, block) {
     if (this.closed) return false;
+    this.touch();
     if (scene === "END") {
       this.started = true;
       this.pendingChoice = null;
@@ -931,6 +1033,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;
@@ -945,6 +1060,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;
@@ -1064,6 +1180,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;
@@ -1091,13 +1208,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) --------------------------------------
@@ -1124,8 +1255,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;
@@ -1141,11 +1283,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);
@@ -1422,6 +1559,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 = {};
@@ -1457,8 +1612,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.
    *
@@ -1601,17 +1766,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);
+      });
     }
   }
   /**
@@ -1628,7 +1805,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));
     }
   }
 };
@@ -1641,6 +1821,9 @@ function collectCast(nodes, out) {
     for (const beat of n.beats ?? []) if (beat.kind === "line" && beat.character) out.add(beat.character);
   });
 }
+function gameDataField(gameData) {
+  return gameData && Object.keys(gameData).length ? { gameData } : {};
+}
 function serialiseSelectors(map) {
   const out = {};
   for (const [id, st] of map) {
@@ -1824,6 +2007,7 @@ function effectiveGameData(fields, node) {
   return out;
 }
 export {
+  Checkpoint,
   Engine,
   Flow,
   buildTagIndex,