@patterkit/runtime 0.13.0 → 0.14.0

package/dist/index.cjs

@@ -72,7 +72,21 @@ function buildTagIndex(bundle) {
 }
 
 // src/engine.ts
+var import_model2 = require("@patterkit/model");
 var astCache = /* @__PURE__ */ new WeakMap();
+var OWNER = "Patter";
+var esc = (id) => id.replace(/%/g, "%25").replace(/\//g, "%2F");
+var OWNS_REGISTRY = /* @__PURE__ */ Symbol("ownsRegistry");
+var keys = {
+  /** A scene's SHARED `@scene` props (one bag per scene, every flow's). */
+  stage: (sceneId) => `patter/scene/${esc(sceneId)}`,
+  /** Everything one flow registers starts with this. */
+  flow: (flowId) => `patter/flow/${esc(flowId)}/`,
+  /** A flow's NOT-shared `@patter` globals. */
+  flowGlobals: (flowId) => `patter/flow/${esc(flowId)}/patter`,
+  /** A flow's NOT-shared `@scene` props for one scene. */
+  flowScene: (flowId, sceneId) => `patter/flow/${esc(flowId)}/scene/${esc(sceneId)}`
+};
 var Engine = class _Engine {
   host;
   defaultSeed;
@@ -132,18 +146,32 @@ var Engine = class _Engine {
     const patterSharedDecls = props.filter((p) => p.shared ?? true).map(toDecl);
     const patterLocalDecls = props.filter((p) => !(p.shared ?? true)).map(toDecl);
     const patterSharedNames = new Set(patterSharedDecls.map((d) => d.name.toLowerCase()));
-    const shared = new import_scoperegistry.ScopeRegistry().defineOwned("patter", patterSharedDecls, "@patter.");
-    const hostBound = /* @__PURE__ */ new Set();
-    if (options.world) {
-      const worldSpec = bundle.scopeRegistry?.scopes.find((s) => s.token === "world");
-      const decls = (worldSpec?.declarations ?? []).map(toForeignDecl);
-      shared.defineForeign("world", options.world, decls, worldSpec?.writable ?? true);
-      hostBound.add("world");
-    }
-    for (const spec of bundle.scopeRegistry?.scopes ?? []) {
-      if (hostBound.has(spec.token)) continue;
-      const decls = (spec.declarations ?? []).map(toForeignDecl);
-      shared.defineForeign(spec.token, selfBackedResolver(spec.declarations ?? []), decls, spec.writable ?? true);
+    const registry = options.registry ?? new import_scoperegistry.ScopeRegistry();
+    const ownsRegistry = !options.registry || options[OWNS_REGISTRY] === true;
+    const patterBag = new import_scoperegistry2.PropertyBag(patterSharedDecls, { pathPrefix: "@patter." });
+    const hostScopes = [];
+    const registered = [];
+    try {
+      registry.mountOwned("patter", patterBag, { owner: OWNER });
+      registered.push("patter");
+      const hostBound = /* @__PURE__ */ new Set();
+      if (options.world) {
+        const worldSpec = bundle.scopeRegistry?.scopes.find((s) => s.token === "world");
+        const decls = (worldSpec?.declarations ?? []).map(toForeignDecl);
+        registry.defineForeign("world", options.world, decls, { writable: worldSpec?.writable ?? true, owner: OWNER });
+        registered.push("world");
+        hostBound.add("world");
+      }
+      for (const spec of ownsRegistry ? bundle.scopeRegistry?.scopes ?? [] : []) {
+        if (hostBound.has(spec.token) || registry.has(spec.token)) continue;
+        const decls = (spec.declarations ?? []).map((d) => selfBackedDecl(d, spec.writable));
+        registry.defineOwned(spec.token, decls, { owner: OWNER });
+        registered.push(spec.token);
+        hostScopes.push(spec.token);
+      }
+    } catch (e) {
+      for (const k of registered) registry.remove(k, { keep: true });
+      throw e;
     }
     const sceneSharedNames = /* @__PURE__ */ new Map();
     for (const [sceneId, scene] of Object.entries(bundle.scenes)) {
@@ -165,7 +193,10 @@ var Engine = class _Engine {
       blockGameIdToId: this.blockGameIdToId,
       // same instances the engine resolves with
       tagIndex: buildTagIndex(bundle),
-      shared,
+      registry,
+      ownsRegistry,
+      patterBag,
+      hostScopes,
       patterSharedDecls,
       patterLocalDecls,
       patterSharedNames,
@@ -182,7 +213,8 @@ var Engine = class _Engine {
       captionClose: (bundle.closedCaptions ?? import_model.DEFAULT_CAPTION_DELIMITERS).close,
       captionCharacter: bundle.closedCaptions?.character || import_model.DEFAULT_CAPTION_CHARACTER,
       // absent/empty -> SFX
-      refSplitCache: /* @__PURE__ */ new Map()
+      refSplitCache: /* @__PURE__ */ new Map(),
+      refSplitRevision: registry.revision
     };
   }
   /** The active locale (string + character-name lookups resolve in it). */
@@ -227,10 +259,12 @@ var Engine = class _Engine {
    * content-drift policy (§9.8) resolves edits under the cursor: stack frames re-find their next
    * child by id, drifted options drop, a vanished snippet is skipped.
    *
-   * Returns the REPLACEMENT engine; this one is left untouched and should be discarded. Hosts
-   * re-bind their flow handles via `next.getFlow(id)`. If the restore throws (defensive - §9.8
-   * makes this unreachable for ordinary edits), the swap falls back to a cold engine with each
-   * saved flow restarted from the top of the scene it was in.
+   * Returns the REPLACEMENT engine, on the same registry. This one hands its bags over (each is
+   * removed from the registry with its values kept, and the replacement claims them as it
+   * registers), its flows are closed, and it should be discarded. Hosts re-bind their flow handles
+   * via `next.getFlow(id)`. If the restore throws (defensive - §9.8 makes this unreachable for
+   * ordinary edits), the swap falls back to a fresh engine with each saved flow restarted from the
+   * top of the scene it was in; the shared properties carry over.
    */
   hotSwap(bundle) {
     const snapshot = this.saveGame();
@@ -239,12 +273,19 @@ var Engine = class _Engine {
       next2.setClosedCaptions(this.host.captionsOn);
       return next2;
     };
-    const next = new _Engine(bundle, this.creationOptions);
+    const make = () => new _Engine(bundle, {
+      ...this.creationOptions,
+      registry: this.host.registry,
+      [OWNS_REGISTRY]: this.host.ownsRegistry
+    });
+    this.release(true);
+    const next = make();
     try {
       next.loadGame(snapshot);
       return carryOver(next);
     } catch {
-      const fresh = new _Engine(bundle, this.creationOptions);
+      next.release(true);
+      const fresh = make();
       for (const [id, f] of Object.entries(snapshot.flows)) {
         const sceneId = f.cursor.currentSceneId;
         try {
@@ -283,6 +324,7 @@ var Engine = class _Engine {
    * call to reach for when you want a speaker's variation state to carry on.
    */
   openFlow(id, opts = {}) {
+    this.assertExternalScopes();
     const sceneId = this.resolveSceneRef(opts.scene);
     const blockId = this.resolveBlockRef(sceneId, opts.block);
     this.flowsById.get(id)?.close();
@@ -322,6 +364,17 @@ var Engine = class _Engine {
     }
     return existing.advanceToStop().played;
   }
+  /** Content that names another engine's scope (`@story.act`) runs only where that engine is on this
+   *  registry: without it every read would answer false and every write fail, so the flow is refused as
+   *  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. */
+  assertExternalScopes() {
+    for (const token of this.host.bundle.externalScopes ?? []) {
+      if (!this.host.registry.has(token)) {
+        throw new Error(`this content names @${token}, which no engine on this registry registered: give every engine the game's one registry`);
+      }
+    }
+  }
   /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
   resolveSceneRef(ref) {
     if (ref == null) return void 0;
@@ -507,7 +560,7 @@ var Engine = class _Engine {
    * loadGame() replaces every bag, so re-enumerate after a load.
    */
   listBags() {
-    const mounts = [{ bag: this.host.shared.ownedBag("patter") }];
+    const mounts = [{ bag: this.host.patterBag }];
     for (const [sceneId, bag] of this.host.stageBags) mounts.push({ bag, pathPrefix: `@scene:${sceneId}.` });
     return mounts;
   }
@@ -526,15 +579,31 @@ var Engine = class _Engine {
   reset() {
     for (const flow of this.flowsById.values()) flow.close();
     this.flowsById.clear();
-    this.host.shared.reseedOwned("patter", this.host.patterSharedDecls);
+    this.host.patterBag.reseed(this.host.patterSharedDecls);
     this.host.sharedVisits.clear();
     this.host.sharedSelectors.clear();
+    for (const s of this.host.stageBags.keys()) this.host.registry.remove(keys.stage(s));
+    this.host.stageBags.clear();
+    this.host.registry.discardParked("patter/");
+  }
+  /** Remove every bag this engine registered, keeping the values parked when `keep` (a live reload
+   *  handing its state to a replacement), and close its flows. The engine is inert afterwards. */
+  release(keep) {
+    for (const flow of this.flowsById.values()) {
+      flow.releaseBags(keep);
+      flow.close();
+    }
+    this.flowsById.clear();
+    const reg = this.host.registry;
+    for (const s of this.host.stageBags.keys()) reg.remove(keys.stage(s), { keep });
     this.host.stageBags.clear();
+    for (const t of ["patter", ...this.host.hostScopes]) if (reg.has(t)) reg.remove(t, { keep });
+    if (this.creationOptions.world && reg.has("world")) reg.remove("world");
   }
   /** Read a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level). */
   getProperty(ref) {
     const { scope, name } = this.splitShared(ref);
-    return this.host.shared.get(scope, name);
+    return this.host.registry.get(scope, name);
   }
   /** Write a shared (`@patter` / foreign) property by ref. `@scene` refs are rejected (flow-level).
    *
@@ -545,7 +614,7 @@ var Engine = class _Engine {
    *  were each refused the one property they existed to move.) */
   setProperty(ref, value) {
     const { scope, name } = this.splitShared(ref);
-    this.host.shared.set(scope, name, value, { host: true });
+    this.host.registry.set(scope, name, value, { 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. */
@@ -592,54 +661,66 @@ var Engine = class _Engine {
   // @scene is scene-namespaced and needs a flow's current scene - silently
   // routing it into the shared bag (as a junk "scene.x" key) was a trap.
   splitShared(ref) {
-    let split = this.host.refSplitCache.get(ref);
-    if (!split) {
-      split = (0, import_dialect.splitRef)(ref, (t) => t === "scene" || this.host.shared.has(t));
-      this.host.refSplitCache.set(ref, split);
-    }
+    const split = splitHostRef(this.host, ref);
     if (split.scope === "scene") {
       throw new Error(`'${ref}': @scene properties are scene-scoped - read/write them on a Flow, not the Engine`);
     }
     return split;
   }
-  /** Snapshot shared `@patter` state only (for a unified cross-engine save blob, Phase D). */
+  /** The shared `@patter` values alone, as `{ patter: {...} }`.
+   *  @deprecated The registry holds every property now: a game saves `registry.save()` once, and a
+   *  standalone engine's `saveGame()` carries its registry's values. Removed at the next breaking release. */
   save() {
-    return this.host.shared.save();
+    return { patter: this.host.patterBag.save() };
   }
-  /** Restore shared `@patter` values (world properties untouched). */
+  /** Lay a `{ patter: {...} }` section over the shared `@patter` values; anything else is ignored.
+   *  @deprecated See `save`. Removed at the next breaking release. */
   load(blob) {
-    this.host.shared.load(blob);
+    if (blob.patter) this.host.patterBag.load(blob.patter);
   }
-  /** Snapshot the whole game: shared `@patter` + visit counts + every live flow. */
+  /** Snapshot the whole game's NON-property state: visit counts, shared selector cursors, and every
+   *  live flow's cursor and PRNG. The property values are the registry's: a standalone engine (one that
+   *  made its own registry) carries them here under `registry`; a game that passed a registry saves it
+   *  once itself, beside each engine's `saveGame()`. */
   saveGame() {
     const flows = {};
     for (const [id, flow] of this.flowsById) flows[id] = flow.snapshot();
     return {
-      version: 2,
-      shared: this.host.shared.save(),
+      version: import_model2.SAVE_VERSION,
+      ...this.host.ownsRegistry ? { registry: this.host.registry.save() } : {},
       sharedVisits: Object.fromEntries(this.host.sharedVisits),
       sharedSelectors: serialiseSelectors(this.host.sharedSelectors),
-      stageBags: Object.fromEntries([...this.host.stageBags].map(([s, bag]) => [s, bag.save()])),
       flows
     };
   }
-  /** Restore a `saveGame()`: shared globals + visit counts + shared scene bags + reconstruct every flow. */
+  /**
+   * Restore a `saveGame()`: visit counts, shared selector cursors, and every flow. Property values come
+   * from the registry. A save that carries them (a standalone engine's, or a version 2 save from before
+   * the registry held them) has them moved into the registry here; otherwise the game loads its
+   * registry itself, before or after this call. Either order works: this engine's bags are handed back
+   * to the registry (values kept) and the restored flows claim them as they register.
+   */
   loadGame(save) {
-    if (save.version !== 2) throw new Error(`unsupported save version: ${save.version}`);
-    this.host.shared.load(save.shared);
+    const version = save.version;
+    if (version !== 2 && version !== import_model2.SAVE_VERSION) throw new Error(`unsupported save version: ${String(version)}`);
+    this.assertExternalScopes();
+    const reg = this.host.registry;
+    for (const [id, flow] of this.flowsById) {
+      flow.releaseBags(id in save.flows);
+      flow.close();
+    }
+    this.flowsById.clear();
+    for (const s of this.host.stageBags.keys()) reg.remove(keys.stage(s), { keep: true });
+    this.host.stageBags.clear();
+    const values = save.version === 2 ? sectionsFromV2(save) : save.registry;
+    if (values) {
+      if (this.host.ownsRegistry) reg.load(values);
+      else reg.load(values, { keepParked: true });
+    }
     this.host.sharedVisits.clear();
     for (const [id, n] of Object.entries(save.sharedVisits ?? {})) this.host.sharedVisits.set(id, n);
     this.host.sharedSelectors.clear();
     for (const [id, st] of deserialiseSelectors(save.sharedSelectors)) this.host.sharedSelectors.set(id, st);
-    this.host.stageBags.clear();
-    for (const [s, values] of Object.entries(save.stageBags ?? {})) {
-      const shared = this.host.sceneSharedNames.get(s) ?? /* @__PURE__ */ new Set();
-      const decls = (this.host.bundle.scenes[s]?.sceneProps ?? []).filter((d) => shared.has(d.name.toLowerCase()));
-      const bag = new import_scoperegistry2.PropertyBag(decls);
-      bag.load(values);
-      this.host.stageBags.set(s, bag);
-    }
-    this.flowsById.clear();
     for (const [id, snap] of Object.entries(save.flows)) {
       const flow = new Flow(id, this.host, this.defaultSeed);
       flow.restore(snap);
@@ -651,7 +732,9 @@ var Flow = class {
   id;
   host;
   local;
-  // owns "patter" = the NOT-shared globals (this flow's copy)
+  // the NOT-shared `@patter` globals (this flow's copy), keys.flowGlobals
+  /** The registry keys this flow has registered (its globals and each scene bag). */
+  registered = /* @__PURE__ */ new Set();
   rngState;
   // Execution cursor. The `stack` is the continuation stack: each frame is a
   // position within a block's children (the top frame is the active block run;
@@ -676,40 +759,44 @@ var Flow = class {
   /** Per-node entry counts for this flow (node id -> times entered). */
   visitCounts = /* @__PURE__ */ new Map();
   // Per-flow halves of the two scopes. The NOT-shared `@patter` globals live in
-  // `local` (owned scope "patter"); the NOT-shared `@scene` props live in
-  // `sceneBags` (namespaced per scene; they PERSIST across re-entries, spec §7).
-  // The SHARED halves live on the host (`host.shared` / `host.stageBags`). Each
-  // resolver presents one merged scope, routing each property to its half by the
-  // declared `shared` flag.
+  // `local`; the NOT-shared `@scene` props live in `sceneBags` (namespaced per
+  // scene; they PERSIST across re-entries, spec §7). The SHARED halves live on the
+  // host (`host.patterBag` / `host.stageBags`). All of them are registered in the
+  // game's registry. Each resolver presents one merged scope, routing each property
+  // to its half by the declared `shared` flag: that split is why `@patter` and
+  // `@scene` are composed here rather than aliased to a single registry key.
   /** This flow's per-scene LOCAL scene props; see FlowHost.stageBags. */
   sceneBags = /* @__PURE__ */ new Map();
   patterResolver = {
-    get: (n) => this.host.patterSharedNames.has(n) ? this.host.shared.get("patter", n) : this.local.get("patter", n),
+    get: (n) => this.host.patterSharedNames.has(n) ? this.host.patterBag.get(n) : this.local.get(n),
     set: (n, v) => {
-      if (this.host.patterSharedNames.has(n)) this.host.shared.set("patter", n, v);
-      else this.local.set("patter", n, v);
+      if (this.host.patterSharedNames.has(n)) this.host.registry.set("patter", n, v);
+      else this.local.set(n, v);
     }
   };
   sceneResolver = {
     get: (n) => {
       const s = this.currentSceneId;
       if (s === null) return void 0;
-      const bag = this.host.sceneSharedNames.get(s)?.has(n) ? this.host.stageBags.get(s) : this.sceneBags.get(s);
-      return bag?.get(n);
+      return this.sceneBagFor(s, n)?.get(n);
     },
     set: (n, v) => {
       const s = this.currentSceneId;
       if (s === null) return;
-      const bag = this.host.sceneSharedNames.get(s)?.has(n) ? this.host.stageBags.get(s) : this.sceneBags.get(s);
+      const bag = this.sceneBagFor(s, n);
       if (bag) bag.set(n, v);
     }
   };
-  // The eval context is built ONCE: every constituent resolves live state at
-  // call time (shared bags mutate in place per scoperegistry's contract;
-  // patter/scene route through this flow's resolvers, which read the current
-  // `local`/`sceneBags`/`currentSceneId`; the host callbacks read current flow
-  // fields). Rebuilding it per evaluation was the engine's hottest allocation.
+  // The eval context is built once and REFRESHED only when the registry's set of
+  // scopes moves (its `revision`): every constituent resolves live state at call
+  // time (bags mutate in place per scoperegistry's contract; patter/scene route
+  // through this flow's resolvers, which read the current `local`/`sceneBags`/
+  // `currentSceneId`; the host callbacks read current flow fields), but another
+  // engine registering `@story` after this flow opened must still be readable.
+  // Rebuilding it per evaluation was the engine's hottest allocation.
   evalCtx;
+  ctxRevision = -1;
+  registryQualities;
   flowLog = [];
   /** Monotonic across the flow's life; survives clearLog so two reads agree on order. */
   flowSeq = 0;
@@ -717,12 +804,9 @@ var Flow = class {
     this.id = id;
     this.host = host;
     this.rngState = (0, import_expr.toUint32)(seed);
-    this.local = this.freshLocal();
-    const scopes = { ...host.shared.toEvalContext().scopes };
-    scopes["patter"] = this.patterResolver;
-    scopes["scene"] = this.sceneResolver;
+    this.local = this.newLocal();
     this.evalCtx = {
-      scopes,
+      scopes: {},
       host: {
         nextRandom: this.rng,
         visits: (id2) => this.visitCounts.get(id2) ?? 0,
@@ -735,6 +819,21 @@ var Flow = class {
       qualities: (scope, name) => this.stagesFor(scope, name)
     };
   }
+  /** The eval context, its scopes refreshed if the registry's set of scopes has moved since. */
+  context() {
+    const reg = this.host.registry;
+    if (reg.revision !== this.ctxRevision) {
+      const base = reg.toEvalContext();
+      const scopes = this.evalCtx.scopes;
+      for (const k of Object.keys(scopes)) delete scopes[k];
+      Object.assign(scopes, base.scopes);
+      scopes["patter"] = this.patterResolver;
+      scopes["scene"] = this.sceneResolver;
+      this.registryQualities = base.qualities;
+      this.ctxRevision = reg.revision;
+    }
+    return this.evalCtx;
+  }
   /** The stage ladder of `@scope.name` when it is a declared quality, else undefined. Names compare
    *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
   stagesFor(scope, name) {
@@ -747,13 +846,14 @@ var Flow = class {
       const scene = this.currentSceneId != null ? this.host.bundle.scenes[this.currentSceneId] : void 0;
       return fromDecls(scene?.sceneProps);
     }
-    return fromDecls(this.host.bundle.scopeRegistry?.scopes.find((s) => s.token === scope)?.declarations);
+    return this.registryQualities?.(scope, name) ?? fromDecls(this.host.bundle.scopeRegistry?.scopes.find((s) => s.token === scope)?.declarations);
   }
   // -- Host API -------------------------------------------------------------
   /** Begin this flow at a scene (and optionally a specific block within it). */
   start(sceneId, blockId) {
-    this.sceneBags.clear();
-    this.local = this.freshLocal();
+    this.releaseBags(false);
+    this.host.registry.discardParked(keys.flow(this.id));
+    this.mountLocal();
     this.selectors.clear();
     this.visitCounts.clear();
     this.stack = [];
@@ -853,6 +953,7 @@ var Flow = class {
    * cannot quietly mutate the world. Terminal: unlike ending, a close is never revived.
    */
   close() {
+    this.releaseBags(false);
     this.closed = true;
     this.flowEnded = true;
     this.stack = [];
@@ -962,7 +1063,7 @@ var Flow = class {
    * halves are the Engine's listBags.
    */
   listBags() {
-    const mounts = [{ bag: this.local.ownedBag("patter"), pathPrefix: `${this.id}/@patter.` }];
+    const mounts = [{ bag: this.local, pathPrefix: `${this.id}/@patter.` }];
     for (const [sceneId, bag] of this.sceneBags) mounts.push({ bag, pathPrefix: `${this.id}/@scene:${sceneId}.` });
     return mounts;
   }
@@ -1010,7 +1111,7 @@ var Flow = class {
     const { scope, name } = this.splitRef(ref);
     if (scope === "patter") return this.patterResolver.get(name);
     if (scope === "scene") return this.sceneResolver.get(name);
-    return this.host.shared.get(scope, name);
+    return this.host.registry.get(scope, name);
   }
   /** Write a property by ref (routed by scope, then by the property's `shared` flag). The GAME's
    *  surface: it writes with host authority, so a `writable: false` host declaration does not refuse
@@ -1028,16 +1129,13 @@ var Flow = class {
       if (this.currentSceneId === null) throw new Error(`'${ref}': the flow has not entered a scene yet`);
       this.sceneResolver.set(name, value);
     } else {
-      this.host.shared.set(scope, name, value, host ? { host: true } : void 0);
+      this.host.registry.set(scope, name, value, host ? { host: true } : void 0);
     }
   }
   // -- Save / restore (engine-driven) --------------------------------------
-  /** @internal Snapshot this flow's cursor + per-flow scopes (not-shared `@patter`/`@scene`) + PRNG. */
+  /** @internal Snapshot this flow's cursor + PRNG + visits. Its properties are the registry's. */
   snapshot() {
     return {
-      scopes: this.local.save(),
-      // owned scope "patter" = the NOT-shared globals (@scene saved separately)
-      sceneBags: Object.fromEntries([...this.sceneBags].map(([s, bag]) => [s, bag.save()])),
       rngState: this.rngState,
       visits: Object.fromEntries(this.visitCounts),
       cursor: {
@@ -1075,15 +1173,11 @@ var Flow = class {
       }
       return { ...frame };
     });
-    this.sceneBags = new Map(Object.entries(snap.sceneBags ?? {}).map(([s, values]) => {
-      const shared = this.host.sceneSharedNames.get(s) ?? /* @__PURE__ */ new Set();
-      const decls = (this.host.bundle.scenes[s]?.sceneProps ?? []).filter((d) => !shared.has(d.name.toLowerCase()));
-      const bag = new import_scoperegistry2.PropertyBag(decls);
-      bag.load(values);
-      return [s, bag];
-    }));
-    this.local = this.freshLocal();
-    this.local.load(snap.scopes);
+    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);
@@ -1354,7 +1448,7 @@ var Flow = class {
    * node (comparisons, scoped vars, literals, other calls) is an atom, evaluated whole.
    */
   matchedSpec(node, want) {
-    const evalTruthy = (n) => truthy((0, import_expr.evaluate)(n, this.evalCtx, import_dialect.patterDialect));
+    const evalTruthy = (n) => truthy((0, import_expr.evaluate)(n, this.context(), import_dialect.patterDialect));
     return (0, import_expr_specificity.matchedSpecificity)(node, evalTruthy, { want });
   }
   /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
@@ -1381,7 +1475,7 @@ var Flow = class {
     return truthy(this.evalExpr(node.condition));
   }
   evalExpr(expr) {
-    return (0, import_expr.evaluate)(this.conditionAst(expr), this.evalCtx, import_dialect.patterDialect);
+    return (0, import_expr.evaluate)(this.conditionAst(expr), this.context(), import_dialect.patterDialect);
   }
   /** The deserialised (in-memory) AST for an expression, cached per Expression. Shared by the
    *  evaluator and the Best-match specificity walker so both work off one parse. */
@@ -1506,18 +1600,51 @@ var Flow = class {
     const key = (0, import_model.castStringKey)(character);
     return this.host.strings[key] ?? this.host.defaultStrings[key] ?? this.host.castDisplay.get(character);
   }
-  /** Split a ref into scope + name. Tokens: `@scene`, foreign tokens, else `@patter` (incl. bare `@name`). */
+  /** Split a ref into scope + name. Tokens: `@scene`, registered tokens, else `@patter` (incl. bare `@name`). */
   splitRef(ref) {
-    let hit = this.host.refSplitCache.get(ref);
-    if (!hit) {
-      hit = (0, import_dialect.splitRef)(ref, (t) => t === "scene" || this.host.shared.has(t));
-      this.host.refSplitCache.set(ref, hit);
-    }
-    return hit;
+    return splitHostRef(this.host, ref);
+  }
+  /** A fresh, unregistered bag for the NOT-shared `@patter` globals (the shared ones live on the host). */
+  newLocal() {
+    return new import_scoperegistry2.PropertyBag(this.host.patterLocalDecls, { pathPrefix: "@patter." });
+  }
+  /** Register a fresh globals bag under this flow's key; it claims any values waiting there. */
+  mountLocal() {
+    this.local = this.newLocal();
+    const key = keys.flowGlobals(this.id);
+    this.host.registry.mountOwned(key, this.local, { owner: OWNER });
+    this.registered.add(key);
+  }
+  /** @internal Remove every bag this flow registered; with `keep`, their values wait in the registry for
+   *  the flow that replaces this one. Engine-driven (close, loadGame, hotSwap). */
+  releaseBags(keep) {
+    for (const key of this.registered) this.host.registry.remove(key, { keep });
+    this.registered.clear();
+    this.sceneBags.clear();
   }
-  /** The per-flow registry: the NOT-shared `@patter` globals (the shared ones live on the host). */
-  freshLocal() {
-    return new import_scoperegistry.ScopeRegistry().defineOwned("patter", this.host.patterLocalDecls, "@patter.");
+  /** The bag a `@scene` property of scene `s` lives in (stage or this flow's), made if missing. */
+  sceneBagFor(s, name) {
+    if (!this.host.bundle.scenes[s]) return void 0;
+    this.ensureSceneBags(s);
+    return this.host.sceneSharedNames.get(s)?.has(name.toLowerCase()) ? this.host.stageBags.get(s) : this.sceneBags.get(s);
+  }
+  /** Make (and register) scene `s`'s stage bag and this flow's bag for it, if not made yet. A bag made
+   *  here claims whatever values the registry holds for its key: that is how a loaded save reaches it. */
+  ensureSceneBags(s) {
+    const shared = this.host.sceneSharedNames.get(s) ?? /* @__PURE__ */ new Set();
+    const props = this.host.bundle.scenes[s]?.sceneProps ?? [];
+    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 (!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);
+    }
   }
   /**
    * Seed a scene's `@scene` props (spec §7). The not-shared props seed THIS flow's
@@ -1528,13 +1655,7 @@ var Flow = class {
    */
   seedScene(scene) {
     const shared = this.host.sceneSharedNames.get(scene.id) ?? /* @__PURE__ */ new Set();
-    const props = scene.sceneProps ?? [];
-    if (!this.sceneBags.has(scene.id)) {
-      this.sceneBags.set(scene.id, new import_scoperegistry2.PropertyBag(props.filter((d) => !shared.has(d.name.toLowerCase()))));
-    }
-    if (!this.host.stageBags.has(scene.id)) {
-      this.host.stageBags.set(scene.id, new import_scoperegistry2.PropertyBag(props.filter((d) => shared.has(d.name.toLowerCase()))));
-    }
+    this.ensureSceneBags(scene.id);
     for (const decl of scene.sceneProps ?? []) {
       if (!decl.temporary) continue;
       const name = decl.name.toLowerCase();
@@ -1580,16 +1701,32 @@ function toDecl(decl) {
 function toForeignDecl(decl) {
   return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default, writable: decl.writable };
 }
-function selfBackedResolver(decls) {
-  const key = (name) => name.toLowerCase();
-  const bag = /* @__PURE__ */ new Map();
-  for (const d of decls) bag.set(key(d.name), (0, import_scoperegistry2.defaultFor)(d));
-  return {
-    get: (name) => bag.get(key(name)),
-    set: (name, value) => {
-      bag.set(key(name), value);
-    }
-  };
+function selfBackedDecl(decl, scopeWritable) {
+  const d = toForeignDecl(decl);
+  const writable = decl.writable ?? scopeWritable;
+  return writable === void 0 ? d : { ...d, writable };
+}
+function splitHostRef(host, ref) {
+  if (host.refSplitRevision !== host.registry.revision) {
+    host.refSplitCache.clear();
+    host.refSplitRevision = host.registry.revision;
+  }
+  let hit = host.refSplitCache.get(ref);
+  if (!hit) {
+    hit = (0, import_dialect.splitRef)(ref, (t) => t === "scene" || host.registry.has(t) || (host.bundle.externalScopes?.includes(t) ?? false));
+    host.refSplitCache.set(ref, hit);
+  }
+  return hit;
+}
+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;
+  }
+  return out;
 }
 function truthy(v) {
   if (typeof v === "boolean") return v;
@@ -1599,7 +1736,7 @@ function truthy(v) {
 }
 
 // src/describe.ts
-var import_model2 = require("@patterkit/model");
+var import_model3 = require("@patterkit/model");
 var isShared = (d, scopeDefault) => d.shared ?? scopeDefault;
 function summariseProperty(d, scopeDefault) {
   return {
@@ -1652,11 +1789,11 @@ function describeBundle(bundle) {
   const sceneProps = [];
   for (const scene of Object.values(bundle.scenes)) {
     counts.scenes++;
-    const gameId = (0, import_model2.effectiveGameId)(scene);
+    const gameId = (0, import_model3.effectiveGameId)(scene);
     addresses.push({
       gameId,
       name: scene.name,
-      blocks: scene.blocks.map((b) => ({ gameId: (0, import_model2.effectiveGameId)(b), name: b.name }))
+      blocks: scene.blocks.map((b) => ({ gameId: (0, import_model3.effectiveGameId)(b), name: b.name }))
     });
     for (const block of scene.blocks) countBlock(block, counts);
     if (scene.sceneProps?.length) {