@patterkit/runtime 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -33,6 +33,39 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-10-05
+
+### Fixed
+
+- **`openFlow` at an address that does not resolve changes nothing.** It threw, but only after closing
+  any flow already open under that name and putting a broken one in its place. It now throws before
+  anything changes. The block must be in the scene you named, as `goto` has always required: a block
+  from another scene used to open there, and now throws. Held across all four runtimes by the
+  conformance corpus, which now also pins a choice step whole (its `groupId` and each option's
+  `prompt`), as this runtime already gave it.
+
+## [0.16.0] - 2026-10-04
+
+### Added
+
+- **Checkpoints: try something, then undo it.** `engine.checkpoint()` opens a checkpoint; `engine.rollback(checkpoint)` puts the game back exactly
+  as it was then, and `engine.commit(checkpoint)` keeps everything. A rollback undoes every change the story made in between:
+  property values in every scope (a game's own `@world` store is written back through the game), visit
+  counts, shuffle and sequence positions, `@scene` bags made since, and every flow's position and random
+  state; a flow opened since is closed, and its name is free again. `engine.inCheckpoint` says whether one is open.
+  The use is asking "would this say anything?" without consequences: move a flow to an address, step
+  it, and roll back if it had nothing to give, so the scene's on-entry effects, the visits, and the
+  shuffle draws never happened. Each change records how to undo itself as it happens, so a checkpoint
+  costs what the steps inside it do, not what the game has built up, and the record is let go when it
+  closes. One is open at a time; while it is, the calls a rollback couldn't undo are refused
+  (`reset`, `loadGame`, `hotSwap`, `closeFlow`, `openFlow` over an open flow, and a flow's own `start`, `reset`, and `restore`). Held across all four runtimes by the conformance corpus.
+
+### Fixed
+
+- **`Flow.restore()` on a running flow keeps that flow's own property values.** It used to drop them back to
+  their defaults, since a snapshot holds a flow's position and memory, not its property values. Loading
+  a save is unchanged.
+
 ## [0.15.0] - 2026-10-03
 
 ### Added

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Checkpoint: () => Checkpoint,
   Engine: () => Engine,
   Flow: () => Flow,
   buildTagIndex: () => buildTagIndex,
@@ -87,6 +88,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;
@@ -204,6 +212,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,
@@ -267,6 +276,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);
@@ -322,13 +332,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;
@@ -375,6 +400,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;
@@ -584,9 +631,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);
   }
@@ -597,6 +699,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);
@@ -634,7 +737,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. */
@@ -721,6 +826,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 !== import_model2.SAVE_VERSION) throw new Error(`unsupported save version: ${String(version)}`);
     this.assertExternalScopes();
@@ -871,6 +977,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();
@@ -930,6 +1037,7 @@ var Flow = class {
    */
   goto(scene, block) {
     if (this.closed) return false;
+    this.touch();
     if (scene === "END") {
       this.started = true;
       this.pendingChoice = null;
@@ -983,6 +1091,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;
@@ -997,6 +1118,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;
@@ -1116,6 +1238,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;
@@ -1143,13 +1266,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) --------------------------------------
@@ -1176,8 +1313,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 = (0, import_expr.toUint32)(snap.rngState);
     this.visitCounts = new Map(Object.entries(snap.visits ?? {}));
     const c = snap.cursor;
@@ -1193,11 +1341,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);
@@ -1474,6 +1617,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 = {};
@@ -1509,8 +1670,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.
    *
@@ -1653,17 +1824,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 import_scoperegistry2.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 import_scoperegistry2.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);
+      });
     }
   }
   /**
@@ -1680,7 +1863,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, (0, import_scoperegistry2.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, (0, import_scoperegistry2.defaultFor)(decl));
     }
   }
 };
@@ -1880,6 +2066,7 @@ function effectiveGameData(fields, node) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Checkpoint,
   Engine,
   Flow,
   buildTagIndex,