@patterkit/play-helpers 0.4.0 → 0.5.1

package/dist/index.cjs

@@ -20,7 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  SAVE_SCHEMA: () => SAVE_SCHEMA,
+  SAVE_SCHEMA: () => import_model.SAVE_SCHEMA,
   applyLiveBundle: () => applyLiveBundle,
   createAudioResolver: () => createAudioResolver,
   createBundleInspector: () => createBundleInspector,
@@ -28,7 +28,7 @@ __export(index_exports, {
   createPropertyInspector: () => createPropertyInspector,
   createStateLogger: () => createStateLogger,
   deserializeState: () => deserializeState,
-  diffState: () => diffState,
+  diffState: () => import_scoperegistry.diffState,
   getProperty: () => getProperty,
   loadState: () => loadState,
   saveState: () => saveState,
@@ -40,13 +40,13 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/save.ts
-var SAVE_SCHEMA = "patter/save@0";
+var import_model = require("@patterkit/model");
 function saveState(engine) {
-  return { schema: SAVE_SCHEMA, save: engine.saveGame() };
+  return { schema: import_model.SAVE_SCHEMA, save: engine.saveGame() };
 }
 function loadState(engine, env) {
-  if (!env || env.schema !== SAVE_SCHEMA || !env.save) {
-    throw new Error(`loadState: not a ${SAVE_SCHEMA} envelope`);
+  if (!env || env.schema !== import_model.SAVE_SCHEMA || !env.save) {
+    throw new Error(`loadState: not a ${import_model.SAVE_SCHEMA} envelope`);
   }
   engine.loadGame(env.save);
 }
@@ -69,7 +69,7 @@ function setProperties(engine, values) {
 }
 
 // src/logger.ts
-var eq = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+var import_scoperegistry = require("@wildwinter/scoperegistry");
 function snapshotState(engine) {
   const save = engine.saveGame();
   const out = {};
@@ -85,16 +85,6 @@ function snapshotState(engine) {
   }
   return out;
 }
-function diffState(prev, next) {
-  const changes = [];
-  const keys = [.../* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(next)])].sort();
-  for (const path of keys) {
-    const from = prev[path], to = next[path];
-    if (!eq(from, to)) changes.push({ path, ...from !== void 0 ? { from } : {}, ...to !== void 0 ? { to } : {} });
-  }
-  return changes;
-}
-var fmt = (v) => v === void 0 ? "<unset>" : JSON.stringify(v);
 function describeStep(step) {
   switch (step.type) {
     case "line":
@@ -110,21 +100,29 @@ function describeStep(step) {
   }
 }
 var gd = (data) => data ? ` gameData=${JSON.stringify(data)}` : "";
+function visitState(engine) {
+  const save = engine.saveGame();
+  const out = {};
+  for (const [id, n] of Object.entries(save.sharedVisits)) out[`visit:${id}`] = n;
+  for (const [fid, snap] of Object.entries(save.flows)) {
+    for (const [id, n] of Object.entries(snap.visits)) out[`${fid}/visit:${id}`] = n;
+  }
+  return out;
+}
 function createStateLogger(engine, opts = {}) {
-  const sink = opts.sink ?? ((line) => console.log(line));
   const tag = opts.label ? `[${opts.label}] ` : "";
-  let baseline = snapshotState(engine);
+  const kernel = (0, import_scoperegistry.createStateLogger)({
+    // Re-read on every capture: openFlow and loadGame both replace bags, and the kernel
+    // re-mounts whatever it is handed.
+    mounts: () => [...engine.listBags(), ...engine.flows().flatMap((f) => f.listBags())],
+    extra: () => visitState(engine)
+  }, { sink: opts.sink, label: tag });
   return {
     snapshot: () => snapshotState(engine),
-    capture() {
-      const next = snapshotState(engine);
-      const changes = diffState(baseline, next);
-      baseline = next;
-      for (const c of changes) sink(`${tag}${c.path}: ${fmt(c.from)} -> ${fmt(c.to)}`);
-      return changes;
-    },
+    capture: () => kernel.capture(),
+    dispose: () => kernel.dispose(),
     logStep(step) {
-      sink(`${tag}${describeStep(step)}`);
+      (opts.sink ?? ((l) => console.log(l)))(`${tag}${describeStep(step)}`);
     }
   };
 }

package/dist/index.d.cts

@@ -1,11 +1,9 @@
-import { SaveGame, Engine, StepResult, Bundle as Bundle$1, BundleDescription } from '@patterkit/runtime';
+import { Engine, StepResult, Bundle, BundleDescription } from '@patterkit/runtime';
+import { SaveEnvelope, Bundle as Bundle$1 } from '@patterkit/model';
+export { SAVE_SCHEMA, SaveEnvelope } from '@patterkit/model';
+import { StateSnapshot, StateChange, ScalarValue } from '@wildwinter/scoperegistry';
+export { StateChange, StateSnapshot, diffState } from '@wildwinter/scoperegistry';
 
-declare const SAVE_SCHEMA = "patter/save@0";
-interface SaveEnvelope {
-    schema: typeof SAVE_SCHEMA;
-    /** The engine save-game: shared `@patter`/`@scene` state, visit counts, and every live flow. */
-    save: SaveGame;
-}
 /** Capture the whole game as a tagged envelope (wraps `engine.saveGame()`). */
 declare function saveState(engine: Engine): SaveEnvelope;
 /** Restore a {@link saveState} envelope into an engine (fresh or live). Throws on a foreign/blank blob. */
@@ -24,20 +22,14 @@ declare function setProperty(engine: Engine, ref: string, value: PropertyValue):
 /** Set many at once, e.g. `setProperties(engine, { "@hp": 10, "@scene.locked": false })`. */
 declare function setProperties(engine: Engine, values: Record<string, PropertyValue>): void;
 
-/** A flattened runtime-state value (a Patter scalar: number / boolean / string / string[] flags). */
-type StateValue = NonNullable<ReturnType<Engine["getProperty"]>>;
-/** A flattened snapshot: dotted path -> value. Paths: `@patter.x`, `@scene:scene.x`, `visit:nodeId`,
- *  and `flow/...` for a flow's not-shared locals. */
-type StateSnapshot = Record<string, StateValue>;
-interface StateChange {
-    path: string;
-    from?: StateValue;
-    to?: StateValue;
-}
-/** Flatten the engine's whole-game state into a path -> value map (shared scopes + every live flow). */
+/** A flattened runtime-state value: a Patter scalar. The kernel calls this `ScalarValue`;
+ *  the alias stays because it is exported API and reads in Patter's own vocabulary. */
+type StateValue = ScalarValue;
+/** Flatten the engine's whole-game state into a path -> value map (shared scopes + every live
+ *  flow), off `saveGame()`. The logger no longer diffs this - it mounts the bags directly - but
+ *  it stays as the public "what is the state right now" call, and as the definition of the path
+ *  space the mounts compose. */
 declare function snapshotState(engine: Engine): StateSnapshot;
-/** The sorted set of paths that differ between two snapshots (added / removed / changed). */
-declare function diffState(prev: StateSnapshot, next: StateSnapshot): StateChange[];
 interface StateLoggerOptions {
     /** Where lines go; defaults to `console.log`. */
     sink?: (line: string) => void;
@@ -47,12 +39,16 @@ interface StateLoggerOptions {
 interface StateLogger {
     /** The current flattened state (no logging). */
     snapshot(): StateSnapshot;
-    /** Diff since the last capture, log each change, and re-baseline. Returns the changes. */
+    /** Everything since the last capture: the property writes already logged as they landed,
+     *  plus the visit counts, diffed and re-baselined. */
     capture(): StateChange[];
     /** Trace one played step (line / text / game-event / choice / end), including any `gameData`. */
     logStep(step: StepResult): void;
+    /** Unhook the bag auditors. The logger is inert afterwards. */
+    dispose(): void;
 }
-/** Create a state logger over an engine. Call `capture()` after each `advance`/`choose` to log mutations. */
+/** Create a state logger over an engine. Property writes log as they land; call `capture()`
+ *  after each `advance`/`choose` to pick up the visit counts and re-baseline. */
 declare function createStateLogger(engine: Engine, opts?: StateLoggerOptions): StateLogger;
 
 /** A minimal structural type for a WebSocket implementation (browsers + Node 21+ have a global one). */
@@ -107,7 +103,7 @@ interface LiveBundleResult {
     /** The engine to keep using: the same instance for a "text" swap, a replacement for "structure". */
     engine: Engine;
     /** The parsed pushed bundle - hold on to it for the next apply's comparison. */
-    bundle: Bundle$1;
+    bundle: Bundle;
     /** Which tier applied: "text" (strings-only, nothing restarted) or "structure" (full hot swap). */
     kind: "text" | "structure";
 }
@@ -117,7 +113,7 @@ interface LiveBundleResult {
  * unparseable JSON - a structural swap's edge cases are absorbed by the §9.8 drift policy inside
  * `hotSwap`, which never throws for ordinary edits.
  */
-declare function applyLiveBundle(engine: Engine, current: Bundle$1, data: string): LiveBundleResult;
+declare function applyLiveBundle(engine: Engine, current: Bundle, data: string): LiveBundleResult;
 
 interface PropertyInspectorOptions {
     /** Where to mount the panel. If omitted, append the returned `el` yourself. */
@@ -137,324 +133,6 @@ interface PropertyInspector {
 }
 declare function createPropertyInspector(engine: Engine, opts?: PropertyInspectorOptions): PropertyInspector;
 
-type BinaryOp = "==" | "!=" | ">" | ">=" | "<" | "<=" | "+" | "-" | "*" | "/" | "and" | "or";
-type UnaryOp = "not" | "neg";
-type AstNode = ["b", boolean] | ["n", number] | ["s", string] | ["sv", string, string] | ["u", UnaryOp, AstNode] | ["bin", BinaryOp, AstNode, AstNode] | ["call", string, ...AstNode[]] | ["fd", "+" | "-", string];
-
-type ScalarValue = boolean | number | string | string[];
-/** Developer-defined host metadata (spec §17). Opaque to Patter. */
-type GameData = Record<string, unknown>;
-/** A scene/block id, or the reserved "END". */
-type JumpTarget = string;
-interface Jump {
-    to: JumpTarget;
-    /** "jump" (one-way, default) or "call" (jump-and-return via the flow callstack). */
-    mode?: "jump" | "call";
-}
-interface LineBeat {
-    id: string;
-    kind: "line";
-    /** Speaker; must be a member of the project cast (validated). */
-    character?: string;
-    /** Performance direction, language-neutral (never localised). */
-    direction?: string;
-    gameData?: GameData;
-    /** Author-defined freeform tags (#215): a cross-cutting label layer that travels to the runtime.
-     *  At runtime a beat's tags are the UNION of its own and every ancestor's (scene → block → group(s) →
-     *  snippet → beat). Each tag is letters/digits/symbols with NO comma and NO whitespace; deduped. */
-    tags?: string[];
-}
-/**
- * Authorial voice / narration - speaker-less prose (spec §2). Never voiced; its
- * localised text always permits inline `{@name}` interpolation (spec §16). This
- * is the on-screen-text role (e.g. "A door slams!") - distinct from a game-event
- * beat, which is a pure engine instruction with no localised content.
- */
-interface TextBeat {
-    id: string;
-    kind: "text";
-    gameData?: GameData;
-    /** Author tags (#215). See LineBeat.tags. */
-    tags?: string[];
-}
-/**
- * A GAME EVENT (spec §2): a pure engine instruction with no player-facing text - just `gameData` the host
- * reads when the beat plays (comments / docs attach via the authoring file by id). Named "game event"
- * rather than "action" because a screenplay's "action" is prose, which is our text beat. Player-facing
- * words are a line or text beat instead.
- */
-interface GameEventBeat {
-    id: string;
-    kind: "gameEvent";
-    gameData?: GameData;
-    /** Author tags (#215). See LineBeat.tags. */
-    tags?: string[];
-}
-type Beat = LineBeat | TextBeat | GameEventBeat;
-type Selector = "run" | "branch" | "sequence" | "choice";
-/** How a `sequence` walks its children. `specificity` = **Best match**: pick the eligible
- *  child whose condition most specifically fits the current state (the most atomic constraints
- *  actively holding it true); equally-specific ties break by the seeded shuffle. A child with no
- *  condition scores zero, so it acts as the filler that wins only when nothing more specific is
- *  eligible. Composes with `exhaust`: `repeat` re-scores every visit (re-pickable, the Best-match
- *  default), `once` uses each pick up so the group slides down to the filler (graceful degradation). */
-type SelectorOrder = "sequential" | "shuffle" | "specificity";
-/** What a `sequence` does after one full pass through its children. */
-type SelectorExhaust = "once" | "repeat" | "stick";
-/**
- * `sequence` selector config (spec §4). One stateful picker with two orthogonal
- * axes subsumes Ink's stopping / cycle / once / shuffle and their combinations.
- * Defaults: `order: "sequential"`, `exhaust: "once"`. `shuffle` draws without
- * replacement and never repeats a line back-to-back (built in).
- */
-interface SequenceOptions {
-    order?: SelectorOrder;
-    exhaust?: SelectorExhaust;
-}
-/** An option's prompt beat (spec §5): a single line | text beat - the choice text. */
-type PromptBeat = LineBeat | TextBeat;
-type PropertyType = "boolean" | "number" | "string" | "flags" | "enum" | "quality";
-interface PropertyDecl {
-    name: string;
-    type: PropertyType;
-    default?: ScalarValue;
-    /**
-     * The orthogonal *sharing* axis (spec §7): is this property's value shared across
-     * all flows (one world value) or kept per-flow? It does NOT change the reference
-     * syntax - sharing is set here, on the declaration, not by a different scope token.
-     * The default depends on the scope it is declared in: a **global** property
-     * (project `properties` -> `@patter`) defaults to **shared**; a **scene-local**
-     * property (scene `sceneProps` -> `@scene`) defaults to **not shared** (per-flow).
-     */
-    shared?: boolean;
-    /**
-     * Persistence axis, for **scene-local (`@scene`) properties** (spec §7). Default
-     * `false`: the value PERSISTS across scene re-entries (like every other property).
-     * `true`: the value is **reseeded to its default on every scene entry** - "fresh
-     * each playthrough" (Ink's `temp`). Orthogonal to `shared`. Ignored on global
-     * (`@patter`) properties, which always persist for the life of the piece.
-     */
-    temporary?: boolean;
-    /** For enum / flags. */
-    values?: string[];
-    /** For quality: the ORDERED ladder of stage names (the shared engine's quality type, expr 0.4.0).
-     *  Ordering operators compare by position in this list and `advance()` steps along it, so the order
-     *  is the meaning - unlike `values`, whose order is presentation only. Default seeds to the first
-     *  stage when no `default` is declared. */
-    stages?: string[];
-    /** Free-text author note documenting what this property is for (authoring only; shown as a hint). */
-    purpose?: string;
-}
-/**
- * A property of a host / world scope (`@world`, `@game`, ...). The same shape the
- * `@wildwinter/scoperegistry` `scopeRegistrySpec` uses, declared structurally here
- * so the model stays free of a runtime dependency. `default` seeds the standalone
- * runtime's self-backed bag (see `HostScopeSpec`); `writable: false` makes the
- * property read-only to the story (validated at compile time).
- */
-interface HostScopeDecl {
-    name: string;
-    type: PropertyType;
-    values?: string[];
-    /** For quality: the ordered stage ladder (see `PropertyDecl.stages`). */
-    stages?: string[];
-    default?: ScalarValue;
-    writable?: boolean;
-    /** Free-text author note documenting the property (authoring only; shown as a hint). */
-    purpose?: string;
-}
-/** One scope (`token`) in a project's host-scope registry. */
-interface HostScopeSpec {
-    /** The scope token after `@` (e.g. `"world"`). Must not collide with Patter's own
-     *  `patter` / `scene` / `flow`. */
-    token: string;
-    /** Scope-level read/write default for its declarations (default true). */
-    writable?: boolean;
-    /** Property declarations; omit for an opaque scope (any name, unchecked). */
-    declarations?: HostScopeDecl[];
-}
-/**
- * A project's host-scope registry: the `scopeRegistrySpec` it OWNS (spec
- * design/scope-registry.md §6). Makes `@world` (and any host scope) first-class
- * in a standalone project: the compiler validates references into it, the runtime
- * self-backs it from declaration defaults when no host resolver claims the token,
- * and coverage drives its values. Structurally identical to scoperegistry's
- * `ScopeRegistrySpec` so it threads straight through the compiler.
- */
-interface HostScopeRegistry {
-    version: number;
-    scopes: HostScopeSpec[];
-}
-/** A character's grammatical gender, for localisation. Translators need it to inflect the speaker's own
- *  lines in gendered languages (adjectives, participles, pronouns), which the source text alone often
- *  cannot tell them. Absent means "not specified". Authoring-only: it never reaches the runtime bundle,
- *  but it IS carried into the localisation handoff formats as translator context (spec §14).
- *
- *  Free text, not a closed set: real languages need more than three genders (common/utrum, animate/
- *  inanimate, and so on) and translators name them differently. `COMMON_GENDERS` seeds the editor's
- *  auto-suggest so the everyday values stay spelled consistently; anything else is still valid. */
-type GrammaticalGender = string;
-interface CastMember {
-    /** Canonical speaker name (matched by a beat's `character`); language-neutral key. */
-    name: string;
-    /** Localised player-facing name - a localisation id (project-level strings). */
-    displayName?: string;
-    /** Grammatical gender for translators (see `GrammaticalGender`); absent = not specified. */
-    gender?: GrammaticalGender;
-    /** Free-text production notes about the character (casting, voice, intent) - authoring only. */
-    notes?: string;
-    /** The voice actor cast for this character, if known - surfaced in the VO script export (spec §16).
-     *  Authoring-only (not shipped in the runtime bundle). */
-    actor?: string;
-    gameData?: GameData;
-}
-/** The cast as it reaches a compiled bundle: the player-facing fields only. `notes`, `actor` and
- *  `gender` are authoring / production / translation context, and the compiler drops them, so a shipped
- *  game never carries a real person's name or a writer's private notes. The compiler copies the shipping
- *  fields across explicitly (an allow-list), which is what actually keeps a new authoring field out of
- *  the bundle; this type states the resulting contract for anyone reading a bundle. */
-type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender">;
-/** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
- *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`. */
-type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent";
-/** The value type of a gameData field - the property-type vocabulary plus a multiline-text variant.
- *  Drives the inspector's editor widget (text / textarea / number / toggle / enum dropdown). */
-type GameDataFieldType = "text" | "multiline" | "number" | "boolean" | "enum";
-/** One author-defined custom field on a node type (host-integration metadata, NOT expression state). */
-interface GameDataField {
-    /** Field key - also the key a node stores its value under in `gameData` (values are name-keyed). */
-    name: string;
-    type: GameDataFieldType;
-    /** The value used when a node sets nothing. Storage is SPARSE - nodes hold only their overrides, and
-     *  a reader falls back to this default (so changing it here propagates to every node that didn't set it). */
-    default?: ScalarValue;
-    /** Allowed values when `type` is "enum". */
-    values?: string[];
-    /** Free-text description of what the field is for - shown as a rollover hint in the inspector. */
-    purpose?: string;
-}
-/** Author-defined gameData fields, grouped by the node type they attach to (project-level schema). */
-type GameDataFields = Partial<Record<GameDataNodeKind, GameDataField[]>>;
-/** A compiled expression envelope: canonical source + pre-derived tagged-tuple AST. */
-interface Expression {
-    src: string;
-    ast: AstNode;
-}
-type CompiledEffect = {
-    kind: "set";
-    target: string;
-    value: Expression;
-};
-interface CompiledSnippet {
-    id: string;
-    type: "snippet";
-    condition?: Expression;
-    beats?: Beat[];
-    onEnter?: CompiledEffect[];
-    onExit?: CompiledEffect[];
-    gameData?: GameData;
-    tags?: string[];
-    jump?: Jump;
-    secretUntilEligible?: boolean;
-    /** Option-position: repeatable (spec §5). Default false = once-only. */
-    sticky?: boolean;
-    /** Option-position: the choice's fallback, auto-followed when last (spec §5). */
-    fallback?: boolean;
-}
-interface CompiledGroup {
-    id: string;
-    type: "group";
-    condition?: Expression;
-    /** Default (omitted) = `"run"`. */
-    selector?: Selector;
-    /** Selector cursor shared across flows (default false = per-flow). */
-    shared?: boolean;
-    options?: SequenceOptions;
-    children: Array<CompiledGroup | CompiledSnippet>;
-    gameData?: GameData;
-    tags?: string[];
-    /** Option-position fields (spec §5) - only when a direct child of a `choice`. */
-    prompt?: PromptBeat;
-    secretUntilEligible?: boolean;
-    /** Repeatable (spec §5). Default false = once-only. */
-    sticky?: boolean;
-    /** The choice's fallback, auto-followed when last (spec §5). */
-    fallback?: boolean;
-}
-interface CompiledBlock {
-    id: string;
-    type: "block";
-    name: string;
-    /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
-    gameId?: string;
-    children: Array<CompiledGroup | CompiledSnippet>;
-    gameData?: GameData;
-    tags?: string[];
-}
-interface CompiledScene {
-    id: string;
-    type: "scene";
-    name: string;
-    /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
-    gameId?: string;
-    gameData?: GameData;
-    tags?: string[];
-    onEntry?: CompiledEffect[];
-    sceneProps?: PropertyDecl[];
-    blocks: CompiledBlock[];
-}
-interface Bundle {
-    schema: string;
-    /** `hash` fingerprints the WHOLE bundle (binds saves, gates staleness); `structureHash` is the same
-     *  fingerprint with the string tables left out, so same structureHash + a different hash = a
-     *  text-only edit, safe to hot-swap in place (live bundle refresh). */
-    content: {
-        project: string;
-        version?: string;
-        hash?: string;
-        structureHash?: string;
-    };
-    voiced: boolean;
-    locales: {
-        default: string;
-        included: string[];
-    };
-    /** Player-facing cast only: the compiler strips notes / actor / gender (see `BundleCastMember`). */
-    cast?: BundleCastMember[];
-    properties?: PropertyDecl[];
-    /** Host / world scope declarations, baked from the project so the runtime can self-back a declared
-     *  scope (`@world`, ...) when no host resolver claims its token. Absent = no host scopes. */
-    scopeRegistry?: HostScopeRegistry;
-    gameDataFields?: GameDataFields;
-    scenes: Record<string, CompiledScene>;
-    /** locale -> (beatId -> text). In "embedded" localisation this carries every included locale; in "ids"
-     *  it is EMPTY (the runtime emits beat IDs), unless `localisation.sourceDebug` embedded the source locale
-     *  for debug playback. `content.hash` is computed over the FULL strings regardless, so the staleness gate
-     *  is unaffected. */
-    strings: Record<string, Record<string, string>>;
-    /** How strings ship + resolve (spec §11). Absent = "embedded" (back-compat default): the runtime resolves
-     *  `strings` per locale. "ids": the runtime emits beat IDs and the game localises them itself; `sourceDebug`
-     *  means the source locale is embedded purely for debug playback and the runtime should flag the build as
-     *  not shippable. */
-    localisation?: {
-        mode: "embedded" | "ids";
-        sourceDebug?: boolean;
-    };
-    /** Closed-caption delimiters baked from the project (#214). Absent = the default `(` / `)`; the
-     *  runtime strips spans between them from line text when a game disables captions. */
-    closedCaptions?: CaptionDelimiters;
-}
-/** Closed-caption configuration (#214). `open`/`close` wrap a caption cue inside a dialogue line (both
- *  non-empty; they MAY be the same token, e.g. `*…*`). `character` names a cast member whose lines are a
- *  pure caption: when captions are off, ALL of that character's dialogue (and its speaker label) is
- *  omitted - delimiters or not - leaving a silent line that still fires (so audio plays). Absent / empty
- *  `character` resolves to the default `SFX` (you "disable" it simply by never using that speaker). */
-interface CaptionDelimiters {
-    open: string;
-    close: string;
-    character?: string;
-}
-
 interface BundleInspectorOptions {
     /** Where to mount the panel. If omitted, append the returned `el` yourself. */
     container?: HTMLElement;
@@ -477,7 +155,7 @@ interface BundleInspector {
  * Build a read-only panel describing a compiled bundle: what it is, what game
  * code may call on it, and what the host must supply.
  */
-declare function createBundleInspector(bundle: Bundle, opts?: BundleInspectorOptions): BundleInspector;
+declare function createBundleInspector(bundle: Bundle$1, opts?: BundleInspectorOptions): BundleInspector;
 
 interface AudioResolver {
     /** The full path/URL of a beat's winning audio take, or null when it has none. */
@@ -490,4 +168,4 @@ interface AudioResolver {
  */
 declare function createAudioResolver(manifestJson: string, basePath: string): AudioResolver;
 
-export { type AudioResolver, type BundleInspector, type BundleInspectorOptions, type BundleSection, type DebugLink, type DebugLinkOptions, type DebugSocketLike, type LiveBundleResult, type PropertyInspector, type PropertyInspectorOptions, type PropertyValue, SAVE_SCHEMA, type SaveEnvelope, type StateChange, type StateLogger, type StateLoggerOptions, type StateSnapshot, type StateValue, applyLiveBundle, createAudioResolver, createBundleInspector, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, diffState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };
+export { type AudioResolver, type BundleInspector, type BundleInspectorOptions, type BundleSection, type DebugLink, type DebugLinkOptions, type DebugSocketLike, type LiveBundleResult, type PropertyInspector, type PropertyInspectorOptions, type PropertyValue, type StateLogger, type StateLoggerOptions, type StateValue, applyLiveBundle, createAudioResolver, createBundleInspector, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };

package/dist/index.d.ts

@@ -1,11 +1,9 @@
-import { SaveGame, Engine, StepResult, Bundle as Bundle$1, BundleDescription } from '@patterkit/runtime';
+import { Engine, StepResult, Bundle, BundleDescription } from '@patterkit/runtime';
+import { SaveEnvelope, Bundle as Bundle$1 } from '@patterkit/model';
+export { SAVE_SCHEMA, SaveEnvelope } from '@patterkit/model';
+import { StateSnapshot, StateChange, ScalarValue } from '@wildwinter/scoperegistry';
+export { StateChange, StateSnapshot, diffState } from '@wildwinter/scoperegistry';
 
-declare const SAVE_SCHEMA = "patter/save@0";
-interface SaveEnvelope {
-    schema: typeof SAVE_SCHEMA;
-    /** The engine save-game: shared `@patter`/`@scene` state, visit counts, and every live flow. */
-    save: SaveGame;
-}
 /** Capture the whole game as a tagged envelope (wraps `engine.saveGame()`). */
 declare function saveState(engine: Engine): SaveEnvelope;
 /** Restore a {@link saveState} envelope into an engine (fresh or live). Throws on a foreign/blank blob. */
@@ -24,20 +22,14 @@ declare function setProperty(engine: Engine, ref: string, value: PropertyValue):
 /** Set many at once, e.g. `setProperties(engine, { "@hp": 10, "@scene.locked": false })`. */
 declare function setProperties(engine: Engine, values: Record<string, PropertyValue>): void;
 
-/** A flattened runtime-state value (a Patter scalar: number / boolean / string / string[] flags). */
-type StateValue = NonNullable<ReturnType<Engine["getProperty"]>>;
-/** A flattened snapshot: dotted path -> value. Paths: `@patter.x`, `@scene:scene.x`, `visit:nodeId`,
- *  and `flow/...` for a flow's not-shared locals. */
-type StateSnapshot = Record<string, StateValue>;
-interface StateChange {
-    path: string;
-    from?: StateValue;
-    to?: StateValue;
-}
-/** Flatten the engine's whole-game state into a path -> value map (shared scopes + every live flow). */
+/** A flattened runtime-state value: a Patter scalar. The kernel calls this `ScalarValue`;
+ *  the alias stays because it is exported API and reads in Patter's own vocabulary. */
+type StateValue = ScalarValue;
+/** Flatten the engine's whole-game state into a path -> value map (shared scopes + every live
+ *  flow), off `saveGame()`. The logger no longer diffs this - it mounts the bags directly - but
+ *  it stays as the public "what is the state right now" call, and as the definition of the path
+ *  space the mounts compose. */
 declare function snapshotState(engine: Engine): StateSnapshot;
-/** The sorted set of paths that differ between two snapshots (added / removed / changed). */
-declare function diffState(prev: StateSnapshot, next: StateSnapshot): StateChange[];
 interface StateLoggerOptions {
     /** Where lines go; defaults to `console.log`. */
     sink?: (line: string) => void;
@@ -47,12 +39,16 @@ interface StateLoggerOptions {
 interface StateLogger {
     /** The current flattened state (no logging). */
     snapshot(): StateSnapshot;
-    /** Diff since the last capture, log each change, and re-baseline. Returns the changes. */
+    /** Everything since the last capture: the property writes already logged as they landed,
+     *  plus the visit counts, diffed and re-baselined. */
     capture(): StateChange[];
     /** Trace one played step (line / text / game-event / choice / end), including any `gameData`. */
     logStep(step: StepResult): void;
+    /** Unhook the bag auditors. The logger is inert afterwards. */
+    dispose(): void;
 }
-/** Create a state logger over an engine. Call `capture()` after each `advance`/`choose` to log mutations. */
+/** Create a state logger over an engine. Property writes log as they land; call `capture()`
+ *  after each `advance`/`choose` to pick up the visit counts and re-baseline. */
 declare function createStateLogger(engine: Engine, opts?: StateLoggerOptions): StateLogger;
 
 /** A minimal structural type for a WebSocket implementation (browsers + Node 21+ have a global one). */
@@ -107,7 +103,7 @@ interface LiveBundleResult {
     /** The engine to keep using: the same instance for a "text" swap, a replacement for "structure". */
     engine: Engine;
     /** The parsed pushed bundle - hold on to it for the next apply's comparison. */
-    bundle: Bundle$1;
+    bundle: Bundle;
     /** Which tier applied: "text" (strings-only, nothing restarted) or "structure" (full hot swap). */
     kind: "text" | "structure";
 }
@@ -117,7 +113,7 @@ interface LiveBundleResult {
  * unparseable JSON - a structural swap's edge cases are absorbed by the §9.8 drift policy inside
  * `hotSwap`, which never throws for ordinary edits.
  */
-declare function applyLiveBundle(engine: Engine, current: Bundle$1, data: string): LiveBundleResult;
+declare function applyLiveBundle(engine: Engine, current: Bundle, data: string): LiveBundleResult;
 
 interface PropertyInspectorOptions {
     /** Where to mount the panel. If omitted, append the returned `el` yourself. */
@@ -137,324 +133,6 @@ interface PropertyInspector {
 }
 declare function createPropertyInspector(engine: Engine, opts?: PropertyInspectorOptions): PropertyInspector;
 
-type BinaryOp = "==" | "!=" | ">" | ">=" | "<" | "<=" | "+" | "-" | "*" | "/" | "and" | "or";
-type UnaryOp = "not" | "neg";
-type AstNode = ["b", boolean] | ["n", number] | ["s", string] | ["sv", string, string] | ["u", UnaryOp, AstNode] | ["bin", BinaryOp, AstNode, AstNode] | ["call", string, ...AstNode[]] | ["fd", "+" | "-", string];
-
-type ScalarValue = boolean | number | string | string[];
-/** Developer-defined host metadata (spec §17). Opaque to Patter. */
-type GameData = Record<string, unknown>;
-/** A scene/block id, or the reserved "END". */
-type JumpTarget = string;
-interface Jump {
-    to: JumpTarget;
-    /** "jump" (one-way, default) or "call" (jump-and-return via the flow callstack). */
-    mode?: "jump" | "call";
-}
-interface LineBeat {
-    id: string;
-    kind: "line";
-    /** Speaker; must be a member of the project cast (validated). */
-    character?: string;
-    /** Performance direction, language-neutral (never localised). */
-    direction?: string;
-    gameData?: GameData;
-    /** Author-defined freeform tags (#215): a cross-cutting label layer that travels to the runtime.
-     *  At runtime a beat's tags are the UNION of its own and every ancestor's (scene → block → group(s) →
-     *  snippet → beat). Each tag is letters/digits/symbols with NO comma and NO whitespace; deduped. */
-    tags?: string[];
-}
-/**
- * Authorial voice / narration - speaker-less prose (spec §2). Never voiced; its
- * localised text always permits inline `{@name}` interpolation (spec §16). This
- * is the on-screen-text role (e.g. "A door slams!") - distinct from a game-event
- * beat, which is a pure engine instruction with no localised content.
- */
-interface TextBeat {
-    id: string;
-    kind: "text";
-    gameData?: GameData;
-    /** Author tags (#215). See LineBeat.tags. */
-    tags?: string[];
-}
-/**
- * A GAME EVENT (spec §2): a pure engine instruction with no player-facing text - just `gameData` the host
- * reads when the beat plays (comments / docs attach via the authoring file by id). Named "game event"
- * rather than "action" because a screenplay's "action" is prose, which is our text beat. Player-facing
- * words are a line or text beat instead.
- */
-interface GameEventBeat {
-    id: string;
-    kind: "gameEvent";
-    gameData?: GameData;
-    /** Author tags (#215). See LineBeat.tags. */
-    tags?: string[];
-}
-type Beat = LineBeat | TextBeat | GameEventBeat;
-type Selector = "run" | "branch" | "sequence" | "choice";
-/** How a `sequence` walks its children. `specificity` = **Best match**: pick the eligible
- *  child whose condition most specifically fits the current state (the most atomic constraints
- *  actively holding it true); equally-specific ties break by the seeded shuffle. A child with no
- *  condition scores zero, so it acts as the filler that wins only when nothing more specific is
- *  eligible. Composes with `exhaust`: `repeat` re-scores every visit (re-pickable, the Best-match
- *  default), `once` uses each pick up so the group slides down to the filler (graceful degradation). */
-type SelectorOrder = "sequential" | "shuffle" | "specificity";
-/** What a `sequence` does after one full pass through its children. */
-type SelectorExhaust = "once" | "repeat" | "stick";
-/**
- * `sequence` selector config (spec §4). One stateful picker with two orthogonal
- * axes subsumes Ink's stopping / cycle / once / shuffle and their combinations.
- * Defaults: `order: "sequential"`, `exhaust: "once"`. `shuffle` draws without
- * replacement and never repeats a line back-to-back (built in).
- */
-interface SequenceOptions {
-    order?: SelectorOrder;
-    exhaust?: SelectorExhaust;
-}
-/** An option's prompt beat (spec §5): a single line | text beat - the choice text. */
-type PromptBeat = LineBeat | TextBeat;
-type PropertyType = "boolean" | "number" | "string" | "flags" | "enum" | "quality";
-interface PropertyDecl {
-    name: string;
-    type: PropertyType;
-    default?: ScalarValue;
-    /**
-     * The orthogonal *sharing* axis (spec §7): is this property's value shared across
-     * all flows (one world value) or kept per-flow? It does NOT change the reference
-     * syntax - sharing is set here, on the declaration, not by a different scope token.
-     * The default depends on the scope it is declared in: a **global** property
-     * (project `properties` -> `@patter`) defaults to **shared**; a **scene-local**
-     * property (scene `sceneProps` -> `@scene`) defaults to **not shared** (per-flow).
-     */
-    shared?: boolean;
-    /**
-     * Persistence axis, for **scene-local (`@scene`) properties** (spec §7). Default
-     * `false`: the value PERSISTS across scene re-entries (like every other property).
-     * `true`: the value is **reseeded to its default on every scene entry** - "fresh
-     * each playthrough" (Ink's `temp`). Orthogonal to `shared`. Ignored on global
-     * (`@patter`) properties, which always persist for the life of the piece.
-     */
-    temporary?: boolean;
-    /** For enum / flags. */
-    values?: string[];
-    /** For quality: the ORDERED ladder of stage names (the shared engine's quality type, expr 0.4.0).
-     *  Ordering operators compare by position in this list and `advance()` steps along it, so the order
-     *  is the meaning - unlike `values`, whose order is presentation only. Default seeds to the first
-     *  stage when no `default` is declared. */
-    stages?: string[];
-    /** Free-text author note documenting what this property is for (authoring only; shown as a hint). */
-    purpose?: string;
-}
-/**
- * A property of a host / world scope (`@world`, `@game`, ...). The same shape the
- * `@wildwinter/scoperegistry` `scopeRegistrySpec` uses, declared structurally here
- * so the model stays free of a runtime dependency. `default` seeds the standalone
- * runtime's self-backed bag (see `HostScopeSpec`); `writable: false` makes the
- * property read-only to the story (validated at compile time).
- */
-interface HostScopeDecl {
-    name: string;
-    type: PropertyType;
-    values?: string[];
-    /** For quality: the ordered stage ladder (see `PropertyDecl.stages`). */
-    stages?: string[];
-    default?: ScalarValue;
-    writable?: boolean;
-    /** Free-text author note documenting the property (authoring only; shown as a hint). */
-    purpose?: string;
-}
-/** One scope (`token`) in a project's host-scope registry. */
-interface HostScopeSpec {
-    /** The scope token after `@` (e.g. `"world"`). Must not collide with Patter's own
-     *  `patter` / `scene` / `flow`. */
-    token: string;
-    /** Scope-level read/write default for its declarations (default true). */
-    writable?: boolean;
-    /** Property declarations; omit for an opaque scope (any name, unchecked). */
-    declarations?: HostScopeDecl[];
-}
-/**
- * A project's host-scope registry: the `scopeRegistrySpec` it OWNS (spec
- * design/scope-registry.md §6). Makes `@world` (and any host scope) first-class
- * in a standalone project: the compiler validates references into it, the runtime
- * self-backs it from declaration defaults when no host resolver claims the token,
- * and coverage drives its values. Structurally identical to scoperegistry's
- * `ScopeRegistrySpec` so it threads straight through the compiler.
- */
-interface HostScopeRegistry {
-    version: number;
-    scopes: HostScopeSpec[];
-}
-/** A character's grammatical gender, for localisation. Translators need it to inflect the speaker's own
- *  lines in gendered languages (adjectives, participles, pronouns), which the source text alone often
- *  cannot tell them. Absent means "not specified". Authoring-only: it never reaches the runtime bundle,
- *  but it IS carried into the localisation handoff formats as translator context (spec §14).
- *
- *  Free text, not a closed set: real languages need more than three genders (common/utrum, animate/
- *  inanimate, and so on) and translators name them differently. `COMMON_GENDERS` seeds the editor's
- *  auto-suggest so the everyday values stay spelled consistently; anything else is still valid. */
-type GrammaticalGender = string;
-interface CastMember {
-    /** Canonical speaker name (matched by a beat's `character`); language-neutral key. */
-    name: string;
-    /** Localised player-facing name - a localisation id (project-level strings). */
-    displayName?: string;
-    /** Grammatical gender for translators (see `GrammaticalGender`); absent = not specified. */
-    gender?: GrammaticalGender;
-    /** Free-text production notes about the character (casting, voice, intent) - authoring only. */
-    notes?: string;
-    /** The voice actor cast for this character, if known - surfaced in the VO script export (spec §16).
-     *  Authoring-only (not shipped in the runtime bundle). */
-    actor?: string;
-    gameData?: GameData;
-}
-/** The cast as it reaches a compiled bundle: the player-facing fields only. `notes`, `actor` and
- *  `gender` are authoring / production / translation context, and the compiler drops them, so a shipped
- *  game never carries a real person's name or a writer's private notes. The compiler copies the shipping
- *  fields across explicitly (an allow-list), which is what actually keeps a new authoring field out of
- *  the bundle; this type states the resulting contract for anyone reading a bundle. */
-type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender">;
-/** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
- *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`. */
-type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent";
-/** The value type of a gameData field - the property-type vocabulary plus a multiline-text variant.
- *  Drives the inspector's editor widget (text / textarea / number / toggle / enum dropdown). */
-type GameDataFieldType = "text" | "multiline" | "number" | "boolean" | "enum";
-/** One author-defined custom field on a node type (host-integration metadata, NOT expression state). */
-interface GameDataField {
-    /** Field key - also the key a node stores its value under in `gameData` (values are name-keyed). */
-    name: string;
-    type: GameDataFieldType;
-    /** The value used when a node sets nothing. Storage is SPARSE - nodes hold only their overrides, and
-     *  a reader falls back to this default (so changing it here propagates to every node that didn't set it). */
-    default?: ScalarValue;
-    /** Allowed values when `type` is "enum". */
-    values?: string[];
-    /** Free-text description of what the field is for - shown as a rollover hint in the inspector. */
-    purpose?: string;
-}
-/** Author-defined gameData fields, grouped by the node type they attach to (project-level schema). */
-type GameDataFields = Partial<Record<GameDataNodeKind, GameDataField[]>>;
-/** A compiled expression envelope: canonical source + pre-derived tagged-tuple AST. */
-interface Expression {
-    src: string;
-    ast: AstNode;
-}
-type CompiledEffect = {
-    kind: "set";
-    target: string;
-    value: Expression;
-};
-interface CompiledSnippet {
-    id: string;
-    type: "snippet";
-    condition?: Expression;
-    beats?: Beat[];
-    onEnter?: CompiledEffect[];
-    onExit?: CompiledEffect[];
-    gameData?: GameData;
-    tags?: string[];
-    jump?: Jump;
-    secretUntilEligible?: boolean;
-    /** Option-position: repeatable (spec §5). Default false = once-only. */
-    sticky?: boolean;
-    /** Option-position: the choice's fallback, auto-followed when last (spec §5). */
-    fallback?: boolean;
-}
-interface CompiledGroup {
-    id: string;
-    type: "group";
-    condition?: Expression;
-    /** Default (omitted) = `"run"`. */
-    selector?: Selector;
-    /** Selector cursor shared across flows (default false = per-flow). */
-    shared?: boolean;
-    options?: SequenceOptions;
-    children: Array<CompiledGroup | CompiledSnippet>;
-    gameData?: GameData;
-    tags?: string[];
-    /** Option-position fields (spec §5) - only when a direct child of a `choice`. */
-    prompt?: PromptBeat;
-    secretUntilEligible?: boolean;
-    /** Repeatable (spec §5). Default false = once-only. */
-    sticky?: boolean;
-    /** The choice's fallback, auto-followed when last (spec §5). */
-    fallback?: boolean;
-}
-interface CompiledBlock {
-    id: string;
-    type: "block";
-    name: string;
-    /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
-    gameId?: string;
-    children: Array<CompiledGroup | CompiledSnippet>;
-    gameData?: GameData;
-    tags?: string[];
-}
-interface CompiledScene {
-    id: string;
-    type: "scene";
-    name: string;
-    /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
-    gameId?: string;
-    gameData?: GameData;
-    tags?: string[];
-    onEntry?: CompiledEffect[];
-    sceneProps?: PropertyDecl[];
-    blocks: CompiledBlock[];
-}
-interface Bundle {
-    schema: string;
-    /** `hash` fingerprints the WHOLE bundle (binds saves, gates staleness); `structureHash` is the same
-     *  fingerprint with the string tables left out, so same structureHash + a different hash = a
-     *  text-only edit, safe to hot-swap in place (live bundle refresh). */
-    content: {
-        project: string;
-        version?: string;
-        hash?: string;
-        structureHash?: string;
-    };
-    voiced: boolean;
-    locales: {
-        default: string;
-        included: string[];
-    };
-    /** Player-facing cast only: the compiler strips notes / actor / gender (see `BundleCastMember`). */
-    cast?: BundleCastMember[];
-    properties?: PropertyDecl[];
-    /** Host / world scope declarations, baked from the project so the runtime can self-back a declared
-     *  scope (`@world`, ...) when no host resolver claims its token. Absent = no host scopes. */
-    scopeRegistry?: HostScopeRegistry;
-    gameDataFields?: GameDataFields;
-    scenes: Record<string, CompiledScene>;
-    /** locale -> (beatId -> text). In "embedded" localisation this carries every included locale; in "ids"
-     *  it is EMPTY (the runtime emits beat IDs), unless `localisation.sourceDebug` embedded the source locale
-     *  for debug playback. `content.hash` is computed over the FULL strings regardless, so the staleness gate
-     *  is unaffected. */
-    strings: Record<string, Record<string, string>>;
-    /** How strings ship + resolve (spec §11). Absent = "embedded" (back-compat default): the runtime resolves
-     *  `strings` per locale. "ids": the runtime emits beat IDs and the game localises them itself; `sourceDebug`
-     *  means the source locale is embedded purely for debug playback and the runtime should flag the build as
-     *  not shippable. */
-    localisation?: {
-        mode: "embedded" | "ids";
-        sourceDebug?: boolean;
-    };
-    /** Closed-caption delimiters baked from the project (#214). Absent = the default `(` / `)`; the
-     *  runtime strips spans between them from line text when a game disables captions. */
-    closedCaptions?: CaptionDelimiters;
-}
-/** Closed-caption configuration (#214). `open`/`close` wrap a caption cue inside a dialogue line (both
- *  non-empty; they MAY be the same token, e.g. `*…*`). `character` names a cast member whose lines are a
- *  pure caption: when captions are off, ALL of that character's dialogue (and its speaker label) is
- *  omitted - delimiters or not - leaving a silent line that still fires (so audio plays). Absent / empty
- *  `character` resolves to the default `SFX` (you "disable" it simply by never using that speaker). */
-interface CaptionDelimiters {
-    open: string;
-    close: string;
-    character?: string;
-}
-
 interface BundleInspectorOptions {
     /** Where to mount the panel. If omitted, append the returned `el` yourself. */
     container?: HTMLElement;
@@ -477,7 +155,7 @@ interface BundleInspector {
  * Build a read-only panel describing a compiled bundle: what it is, what game
  * code may call on it, and what the host must supply.
  */
-declare function createBundleInspector(bundle: Bundle, opts?: BundleInspectorOptions): BundleInspector;
+declare function createBundleInspector(bundle: Bundle$1, opts?: BundleInspectorOptions): BundleInspector;
 
 interface AudioResolver {
     /** The full path/URL of a beat's winning audio take, or null when it has none. */
@@ -490,4 +168,4 @@ interface AudioResolver {
  */
 declare function createAudioResolver(manifestJson: string, basePath: string): AudioResolver;
 
-export { type AudioResolver, type BundleInspector, type BundleInspectorOptions, type BundleSection, type DebugLink, type DebugLinkOptions, type DebugSocketLike, type LiveBundleResult, type PropertyInspector, type PropertyInspectorOptions, type PropertyValue, SAVE_SCHEMA, type SaveEnvelope, type StateChange, type StateLogger, type StateLoggerOptions, type StateSnapshot, type StateValue, applyLiveBundle, createAudioResolver, createBundleInspector, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, diffState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };
+export { type AudioResolver, type BundleInspector, type BundleInspectorOptions, type BundleSection, type DebugLink, type DebugLinkOptions, type DebugSocketLike, type LiveBundleResult, type PropertyInspector, type PropertyInspectorOptions, type PropertyValue, type StateLogger, type StateLoggerOptions, type StateValue, applyLiveBundle, createAudioResolver, createBundleInspector, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/save.ts
-var SAVE_SCHEMA = "patter/save@0";
+import { SAVE_SCHEMA } from "@patterkit/model";
 function saveState(engine) {
   return { schema: SAVE_SCHEMA, save: engine.saveGame() };
 }
@@ -28,7 +28,7 @@ function setProperties(engine, values) {
 }
 
 // src/logger.ts
-var eq = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+import { createStateLogger as createKernelStateLogger, diffState } from "@wildwinter/scoperegistry";
 function snapshotState(engine) {
   const save = engine.saveGame();
   const out = {};
@@ -44,16 +44,6 @@ function snapshotState(engine) {
   }
   return out;
 }
-function diffState(prev, next) {
-  const changes = [];
-  const keys = [.../* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(next)])].sort();
-  for (const path of keys) {
-    const from = prev[path], to = next[path];
-    if (!eq(from, to)) changes.push({ path, ...from !== void 0 ? { from } : {}, ...to !== void 0 ? { to } : {} });
-  }
-  return changes;
-}
-var fmt = (v) => v === void 0 ? "<unset>" : JSON.stringify(v);
 function describeStep(step) {
   switch (step.type) {
     case "line":
@@ -69,21 +59,29 @@ function describeStep(step) {
   }
 }
 var gd = (data) => data ? ` gameData=${JSON.stringify(data)}` : "";
+function visitState(engine) {
+  const save = engine.saveGame();
+  const out = {};
+  for (const [id, n] of Object.entries(save.sharedVisits)) out[`visit:${id}`] = n;
+  for (const [fid, snap] of Object.entries(save.flows)) {
+    for (const [id, n] of Object.entries(snap.visits)) out[`${fid}/visit:${id}`] = n;
+  }
+  return out;
+}
 function createStateLogger(engine, opts = {}) {
-  const sink = opts.sink ?? ((line) => console.log(line));
   const tag = opts.label ? `[${opts.label}] ` : "";
-  let baseline = snapshotState(engine);
+  const kernel = createKernelStateLogger({
+    // Re-read on every capture: openFlow and loadGame both replace bags, and the kernel
+    // re-mounts whatever it is handed.
+    mounts: () => [...engine.listBags(), ...engine.flows().flatMap((f) => f.listBags())],
+    extra: () => visitState(engine)
+  }, { sink: opts.sink, label: tag });
   return {
     snapshot: () => snapshotState(engine),
-    capture() {
-      const next = snapshotState(engine);
-      const changes = diffState(baseline, next);
-      baseline = next;
-      for (const c of changes) sink(`${tag}${c.path}: ${fmt(c.from)} -> ${fmt(c.to)}`);
-      return changes;
-    },
+    capture: () => kernel.capture(),
+    dispose: () => kernel.dispose(),
     logStep(step) {
-      sink(`${tag}${describeStep(step)}`);
+      (opts.sink ?? ((l) => console.log(l)))(`${tag}${describeStep(step)}`);
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/play-helpers",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Thin game-integration helpers around @patterkit/runtime: save/load serialisation, runtime property setters, a state logger, the Patterpad Live Link client + hot reload, a property inspector, and audio resolution. The Patterplay JS companion.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,8 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean"
   },
   "dependencies": {
-    "@patterkit/runtime": "0.9.0"
+    "@patterkit/model": "^0.5.0",
+    "@patterkit/runtime": "0.11.0",
+    "@wildwinter/scoperegistry": "^0.5.0"
   }
 }