@patterkit/runtime 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -33,6 +33,18 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-10-11
+
+### Added
+
+- **Flow capture and restore**: `engine.captureFlow(id)` takes one flow out as a `FlowState`, plain data in the
+  save's own spelling (its snapshot, a `version`, and its own values as a version 2 save's per-flow `scopes`
+  and `sceneBags`, without its id), and `engine.restoreFlow(id, state)` opens it again under any id, as
+  `loadGame` restores each flow. Shared state isn't in it, so a restore rewinds nothing else, and anything a
+  load left waiting under the id is dropped first, as when a flow starts. Refused over an open id, while a
+  checkpoint is open, and for a state with no cursor, changing nothing; capturing is allowed in a checkpoint.
+  The conformance corpus holds every runtime to it.
+
 ## [0.23.0] - 2026-10-10
 
 ### Added

package/README.md

@@ -110,6 +110,10 @@ value); `engine.loadGame(blob)` restores it. Saves from before property values m
 registry (version 2) still load. [@patterkit/play-helpers](../play-helpers) wraps these as
 `serializeState` / `deserializeState` with a tagged envelope.
 
+To set one flow aside instead, `engine.captureFlow(id)` returns its part of a save as plain data (its
+position, PRNG, visits, selectors, and its own property values, without its id); close it after capturing,
+and `engine.restoreFlow(newId, state)` opens it again later, under any id, without rewinding shared state.
+
 ## One registry per game
 
 A game has one `ScopeRegistry` holding every property from every engine, except values the game

package/dist/index.cjs

@@ -139,6 +139,7 @@ function tagsOf(host, id) {
 }
 var OWNER = "Patter";
 var esc = (id) => id.replace(/%/g, "%25").replace(/\//g, "%2F");
+var unesc = (key) => key.replace(/%2F/g, "/").replace(/%25/g, "%");
 var OWNS_REGISTRY = /* @__PURE__ */ Symbol("ownsRegistry");
 var keys = {
   /** A scene's SHARED `@scene` props (one bag per scene, every flow's). */
@@ -767,6 +768,45 @@ var Engine = class _Engine {
   refuseInCheckpoint(what) {
     if (this.host.journal) throw new Error(`${what} can't be undone, so it isn't allowed while a checkpoint is open`);
   }
+  /**
+   * Take flow `id` out of the engine as plain data, to be put back later with {@link restoreFlow}: its snapshot as
+   * `saveGame` writes it, and its own property values without its id (so it can come back under another). Shared
+   * state is never in it. Doesn't close the flow; close it with {@link closeFlow} AFTER capturing, since closing
+   * drops its values. Only reads, so it is allowed while a checkpoint is open.
+   */
+  captureFlow(id) {
+    const flow = this.flowsById.get(id);
+    if (!flow) throw new Error(`no open flow '${id}' to capture`);
+    return { version: import_model3.SAVE_VERSION, ...flow.snapshot(), ...flowValuesFrom(id, this.host.registry.save()) };
+  }
+  /**
+   * Open flow `id` from a {@link captureFlow} state, the per-flow half of `loadGame`: its values go into the
+   * registry as a load's do, and the flow is restored as a load restores each flow. `id` needn't be the id it was
+   * captured from. Against an edited bundle it re-finds its place by id, as a load does. Refused if a flow of
+   * that id is open, or while a checkpoint is.
+   */
+  restoreFlow(id, state) {
+    this.refuseInCheckpoint("restoreFlow");
+    const version = state.version;
+    if (version !== 2 && version !== import_model3.SAVE_VERSION) throw new Error(`unsupported flow state version: ${String(version)}`);
+    const cursor = state.cursor;
+    if (typeof cursor !== "object" || cursor === null) throw new Error("malformed flow state: no cursor");
+    if (this.flowsById.has(id)) throw new Error(`a flow '${id}' is already open; close it before restoring another under that id`);
+    this.assertExternalScopes();
+    const parked = keys.flow(id);
+    this.host.registry.discardParked(parked);
+    this.host.registry.load(flowSections(id, state), { keepParked: true });
+    const flow = new Flow(id, this.host, this.defaultSeed);
+    try {
+      flow.restore(state);
+    } catch (e) {
+      flow.close();
+      this.host.registry.discardParked(parked);
+      throw e;
+    }
+    this.flowsById.set(id, flow);
+    return flow;
+  }
   /** 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) {
@@ -2170,9 +2210,23 @@ function sectionsFromV2(save) {
   const out = {};
   if (save.shared?.patter) out["patter"] = save.shared.patter;
   for (const [s, v] of Object.entries(save.stageBags ?? {})) out[keys.stage(s)] = v;
-  for (const [id, f] of Object.entries(save.flows ?? {})) {
-    if (f.scopes?.patter) out[keys.flowGlobals(id)] = f.scopes.patter;
-    for (const [s, v] of Object.entries(f.sceneBags ?? {})) out[keys.flowScene(id, s)] = v;
+  for (const [id, f] of Object.entries(save.flows ?? {})) Object.assign(out, flowSections(id, f));
+  return out;
+}
+function flowSections(id, f) {
+  const out = {};
+  if (f.scopes?.patter) out[keys.flowGlobals(id)] = f.scopes.patter;
+  for (const [s, v] of Object.entries(f.sceneBags ?? {})) out[keys.flowScene(id, s)] = v;
+  return out;
+}
+function flowValuesFrom(id, saved) {
+  const out = { scopes: {}, sceneBags: {} };
+  const prefix = keys.flow(id);
+  for (const [key, values] of Object.entries(saved)) {
+    if (!key.startsWith(prefix)) continue;
+    const rest = key.slice(prefix.length);
+    if (rest === "patter") out.scopes.patter = values;
+    else if (rest.startsWith("scene/")) out.sceneBags[unesc(rest.slice("scene/".length))] = values;
   }
   return out;
 }