@patterkit/play-helpers 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -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,
@@ -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,4 +1,6 @@
 import { SaveGame, Engine, StepResult, Bundle as Bundle$1, BundleDescription } from '@patterkit/runtime';
+import { StateSnapshot, StateChange, ScalarValue as ScalarValue$1 } from '@wildwinter/scoperegistry';
+export { StateChange, StateSnapshot, diffState } from '@wildwinter/scoperegistry';
 
 declare const SAVE_SCHEMA = "patter/save@0";
 interface SaveEnvelope {
@@ -24,20 +26,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$1;
+/** 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 +43,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). */
@@ -490,4 +490,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, SAVE_SCHEMA, type SaveEnvelope, 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,4 +1,6 @@
 import { SaveGame, Engine, StepResult, Bundle as Bundle$1, BundleDescription } from '@patterkit/runtime';
+import { StateSnapshot, StateChange, ScalarValue as ScalarValue$1 } from '@wildwinter/scoperegistry';
+export { StateChange, StateSnapshot, diffState } from '@wildwinter/scoperegistry';
 
 declare const SAVE_SCHEMA = "patter/save@0";
 interface SaveEnvelope {
@@ -24,20 +26,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$1;
+/** 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 +43,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). */
@@ -490,4 +490,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, SAVE_SCHEMA, type SaveEnvelope, type StateLogger, type StateLoggerOptions, type StateValue, applyLiveBundle, createAudioResolver, createBundleInspector, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };

package/dist/index.js

@@ -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.0",
   "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,7 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean"
   },
   "dependencies": {
-    "@patterkit/runtime": "0.9.0"
+    "@patterkit/runtime": "0.10.0",
+    "@wildwinter/scoperegistry": "^0.5.0"
   }
 }