@patterkit/play-helpers 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @patterkit/play-helpers
+
+Thin game-integration helpers around [@patterkit/runtime](../runtime)'s `Engine` -
+the **Patterplay JS** companion. None are required to play a bundle; they smooth
+the host wiring most games end up writing anyway.
+
+```sh
+npm install @patterkit/play-helpers
+```
+
+## Save / load
+
+Wrap the engine's whole-game snapshot in a tagged, versioned envelope - drop it into
+localStorage or a file, and a foreign blob throws instead of corrupting a run.
+
+```ts
+import { serializeState, deserializeState } from "@patterkit/play-helpers";
+
+localStorage.setItem("slot1", serializeState(engine));
+deserializeState(engine, localStorage.getItem("slot1")!);   // throws on a non-patter blob
+```
+
+`saveState` / `loadState` are the object-level variants (no JSON string).
+
+## Runtime properties
+
+Read / write `@patter` globals, `@scene` props, or a wired foreign scope at runtime -
+e.g. the game pushing inventory into the dialogue.
+
+```ts
+import { setProperty, setProperties, getProperty } from "@patterkit/play-helpers";
+
+setProperties(engine, { "@hp": 10, "@scene.locked": false });
+getProperty(engine, "@hp");   // 10
+```
+
+(Localisation needs no helper: an **Embedded** bundle carries its strings - construct with
+`{ locale }` or switch live via `engine.setLocale()`; an **IDs-only** bundle emits beat IDs
+your game localises itself, re-interpolated with `flow.interpolate()`. See the
+[Localisation guide](https://patterkit.dev/play/localisation/).)
+
+## State logger
+
+A debug companion that watches the mutable runtime state (`@patter` / `@scene` /
+visit counts, shared + per-flow) and reports what changed between captures. `logStep`
+traces each played step, including its `gameData` (the host-event channel).
+
+```ts
+import { createStateLogger } from "@patterkit/play-helpers";
+
+const log = createStateLogger(engine, { label: "main" });
+const step = flow.advance();
+log.logStep(step);   // [main] line WATCHMAN: "..." gameData={...}
+log.capture();       // [main] @patter.bell_tolls: 0 -> 1
+```
+
+`snapshotState(engine)` / `diffState(a, b)` are the underlying pure functions.
+
+## Live Link (Patterpad debug + hot reload)
+
+`createDebugLink` streams the running story's cursor to Patterpad over a localhost
+WebSocket, so the editor follows the game like a debugger - and receives **live bundle
+pushes** back when the author edits, for hot reload without restarting:
+
+```ts
+import { createDebugLink, applyLiveBundle } from "@patterkit/play-helpers";
+
+let engine = new Engine(bundle);
+const link = createDebugLink({
+  build: bundle.content.hash,
+  onBundle: (msg) => {
+    ({ engine, bundle } = applyLiveBundle(engine, bundle, msg.data));
+    link.setBuild(msg.build);   // re-hello under the new build id
+    rerender();
+  },
+});
+link.flowOpened("main");
+// after each step: link.observe(flowId, sceneId, beatId, step.type)
+```
+
+`applyLiveBundle` picks the cheapest tier itself: same `structureHash` -> in-place
+`replaceStrings` (`kind: "text"`, nothing lost); structural change -> `hotSwap` to a fresh
+engine restored from the old one (`kind: "structure"`). Wire it behind a dev flag - it is
+a development tool, not a shipping feature.
+
+## Property inspector
+
+`createPropertyInspector(engine)` builds a small DOM panel of the engine's `@patter`
+properties with type-aware editors (toggle / number / text / enum / flags) and
+reset-to-default - the JS equivalent of the Unity / Unreal / Godot runtime-state panels.
+`refresh()` re-reads values; `destroy()` unhooks; `pollMs` auto-refreshes.
+
+## Audio resolution
+
+`createAudioResolver(manifestJson, basePath)` reads a `patteraudio.json` manifest (the
+sidecar Patterpad's Build writes next to the audio root) and resolves a beat to its
+**winning take**:
+
+```ts
+import { createAudioResolver } from "@patterkit/play-helpers";
+
+const audio = createAudioResolver(await (await fetch("audio/patteraudio.json")).text(), "audio");
+const src = audio.resolve(step.id);   // "audio/scratch/beat42.wav" | null
+```
+
+It resolves; **you** play (an `<audio>` element, your engine's mixer, anything).

package/dist/index.cjs

@@ -0,0 +1,414 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SAVE_SCHEMA: () => SAVE_SCHEMA,
+  applyLiveBundle: () => applyLiveBundle,
+  createAudioResolver: () => createAudioResolver,
+  createDebugLink: () => createDebugLink,
+  createPropertyInspector: () => createPropertyInspector,
+  createStateLogger: () => createStateLogger,
+  deserializeState: () => deserializeState,
+  diffState: () => diffState,
+  getProperty: () => getProperty,
+  loadState: () => loadState,
+  saveState: () => saveState,
+  serializeState: () => serializeState,
+  setProperties: () => setProperties,
+  setProperty: () => setProperty,
+  snapshotState: () => snapshotState
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/save.ts
+var SAVE_SCHEMA = "patter/save@0";
+function saveState(engine) {
+  return { schema: 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`);
+  }
+  engine.loadGame(env.save);
+}
+function serializeState(engine) {
+  return JSON.stringify(saveState(engine));
+}
+function deserializeState(engine, json) {
+  loadState(engine, JSON.parse(json));
+}
+
+// src/properties.ts
+function getProperty(engine, ref) {
+  return engine.getProperty(ref);
+}
+function setProperty(engine, ref, value) {
+  engine.setProperty(ref, value);
+}
+function setProperties(engine, values) {
+  for (const [ref, value] of Object.entries(values)) engine.setProperty(ref, value);
+}
+
+// src/logger.ts
+var eq = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+function snapshotState(engine) {
+  const save = engine.saveGame();
+  const out = {};
+  for (const [name, v] of Object.entries(save.shared.patter ?? {})) out[`@patter.${name}`] = v;
+  for (const [scene, vals] of Object.entries(save.stageBags))
+    for (const [name, v] of Object.entries(vals)) out[`@scene:${scene}.${name}`] = v;
+  for (const [id, n] of Object.entries(save.sharedVisits)) out[`visit:${id}`] = n;
+  for (const [fid, snap] of Object.entries(save.flows)) {
+    for (const [name, v] of Object.entries(snap.scopes.patter ?? {})) out[`${fid}/@patter.${name}`] = v;
+    for (const [scene, vals] of Object.entries(snap.sceneBags))
+      for (const [name, v] of Object.entries(vals)) out[`${fid}/@scene:${scene}.${name}`] = v;
+    for (const [id, n] of Object.entries(snap.visits)) out[`${fid}/visit:${id}`] = n;
+  }
+  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":
+      return `line ${step.character ?? "?"}: ${JSON.stringify(step.text)}${gd(step.gameData)}`;
+    case "text":
+      return `text: ${JSON.stringify(step.text)}${gd(step.gameData)}`;
+    case "gameEvent":
+      return `game event ${step.id}${gd(step.gameData)}`;
+    case "choice":
+      return `choice (${step.options.length} option${step.options.length === 1 ? "" : "s"})`;
+    case "end":
+      return "end";
+  }
+}
+var gd = (data) => data ? ` gameData=${JSON.stringify(data)}` : "";
+function createStateLogger(engine, opts = {}) {
+  const sink = opts.sink ?? ((line) => console.log(line));
+  const tag = opts.label ? `[${opts.label}] ` : "";
+  let baseline = snapshotState(engine);
+  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;
+    },
+    logStep(step) {
+      sink(`${tag}${describeStep(step)}`);
+    }
+  };
+}
+
+// src/debug.ts
+var OPEN = 1;
+function createDebugLink(opts) {
+  const url = opts.url ?? "ws://127.0.0.1:4471";
+  const Ctor = opts.WebSocket ?? globalThis.WebSocket;
+  const flows = /* @__PURE__ */ new Set();
+  let queue = [];
+  let sock = null;
+  let closed = false;
+  let build = opts.build;
+  const flush = () => {
+    if (!sock || sock.readyState !== OPEN) return;
+    for (const m of queue) {
+      try {
+        sock.send(m);
+      } catch {
+      }
+    }
+    queue = [];
+  };
+  const post = (msg) => {
+    if (closed) return;
+    queue.push(JSON.stringify(msg));
+    flush();
+  };
+  if (!Ctor) {
+    return { flowOpened() {
+    }, observe() {
+    }, flowClosed() {
+    }, setBuild() {
+    }, close() {
+      closed = true;
+    } };
+  }
+  const sendHello = () => {
+    const hello = JSON.stringify({ t: "hello", v: 1, build, project: opts.project, flows: [...flows] });
+    try {
+      sock?.send(hello);
+    } catch {
+    }
+  };
+  try {
+    sock = new Ctor(url);
+    sock.addEventListener("open", () => {
+      sendHello();
+      flush();
+    });
+    sock.addEventListener("message", (ev) => {
+      if (!opts.onBundle || typeof ev.data !== "string") return;
+      try {
+        const msg = JSON.parse(ev.data);
+        if (msg.t === "bundle" && typeof msg.build === "string" && typeof msg.data === "string") {
+          opts.onBundle({ build: msg.build, data: msg.data });
+        }
+      } catch {
+      }
+    });
+    sock.addEventListener("error", () => {
+    });
+    sock.addEventListener("close", () => {
+      sock = null;
+    });
+  } catch {
+    sock = null;
+  }
+  return {
+    flowOpened(flowId) {
+      flows.add(flowId);
+      post({ t: "flowOpen", flow: flowId });
+    },
+    flowClosed(flowId) {
+      flows.delete(flowId);
+      post({ t: "flowClose", flow: flowId });
+    },
+    observe(flowId, sceneId, beatId, type, choiceId) {
+      post({ t: "frame", flow: flowId, sceneId, beatId, type, choiceId });
+    },
+    setBuild(next) {
+      if (closed || next === build) return;
+      build = next;
+      if (sock && sock.readyState === OPEN) sendHello();
+    },
+    close() {
+      closed = true;
+      queue = [];
+      try {
+        sock?.close();
+      } catch {
+      }
+      sock = null;
+    }
+  };
+}
+
+// src/refresh.ts
+var import_runtime = require("@patterkit/runtime");
+function applyLiveBundle(engine, current, data) {
+  const next = JSON.parse(data);
+  const sameStructure = current.content.structureHash !== void 0 && current.content.structureHash === next.content.structureHash;
+  if (sameStructure) {
+    engine.replaceStrings(next);
+    return { engine, bundle: next, kind: "text" };
+  }
+  return { engine: engine.hotSwap(next), bundle: next, kind: "structure" };
+}
+
+// src/inspector.ts
+var STYLE_ID = "pp-inspector-style";
+var CSS = `
+.pp-insp{font:13px/1.4 ui-sans-serif,system-ui,sans-serif;color:#15201e;background:#f4efe6;border:1px solid #cfc7b8;border-radius:10px;padding:.6rem .7rem;max-width:22rem;box-shadow:0 6px 20px rgba(21,32,30,.12)}
+.pp-insp h4{margin:0 0 .4rem;font:600 .72rem/1 ui-sans-serif,system-ui,sans-serif;letter-spacing:.08em;text-transform:uppercase;color:#5c6b62}
+.pp-insp-empty{color:#8a9691;font-style:italic}
+.pp-insp-row{display:flex;align-items:center;gap:.4rem;margin:.18rem 0}
+.pp-insp-ref{flex:0 0 8rem;font-family:ui-monospace,monospace;font-size:.78rem;color:#214f4b;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.pp-insp-ctl{flex:1;min-width:0;display:flex}
+.pp-insp-ctl input[type=text],.pp-insp-ctl input[type=number],.pp-insp-ctl select{width:100%;box-sizing:border-box;font:inherit;padding:.15rem .3rem;border:1px solid #cfc7b8;border-radius:6px;background:#fff;color:inherit}
+.pp-insp-reset{flex:0 0 auto;border:1px solid #cfc7b8;background:#fff;border-radius:6px;cursor:pointer;color:#5c6b62;width:1.6rem;height:1.6rem;line-height:1;padding:0}
+.pp-insp-reset:disabled{opacity:.35;cursor:default}
+`;
+function injectStyle(doc) {
+  if (doc.getElementById(STYLE_ID)) return;
+  const s = doc.createElement("style");
+  s.id = STYLE_ID;
+  s.textContent = CSS;
+  (doc.head ?? doc.documentElement).appendChild(s);
+}
+function sameValue(a, b) {
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((x, i) => x === b[i]);
+  return a === b;
+}
+function createPropertyInspector(engine, opts = {}) {
+  const doc = opts.container?.ownerDocument ?? document;
+  injectStyle(doc);
+  const el = doc.createElement("div");
+  el.className = "pp-insp";
+  const heading = doc.createElement("h4");
+  heading.textContent = opts.title ?? "Runtime state";
+  const list = doc.createElement("div");
+  el.append(heading, list);
+  const rowRefreshers = [];
+  const buildRow = (row) => {
+    const r = doc.createElement("div");
+    r.className = "pp-insp-row";
+    const label = doc.createElement("span");
+    label.className = "pp-insp-ref";
+    label.textContent = row.ref;
+    label.title = row.ref;
+    const ctl = doc.createElement("div");
+    ctl.className = "pp-insp-ctl";
+    const reset = doc.createElement("button");
+    reset.className = "pp-insp-reset";
+    reset.type = "button";
+    reset.textContent = "\u21BA";
+    reset.title = "Reset to default";
+    r.append(label, ctl, reset);
+    list.appendChild(r);
+    let read;
+    const commit = (v) => {
+      engine.setProperty(row.ref, v);
+      syncReset();
+    };
+    const focused = (node) => doc.activeElement === node;
+    function syncReset() {
+      reset.disabled = sameValue(engine.getProperty(row.ref), row.default);
+    }
+    reset.addEventListener("click", () => {
+      engine.setProperty(row.ref, row.default);
+      read();
+      syncReset();
+    });
+    if (row.type === "boolean") {
+      const cb = doc.createElement("input");
+      cb.type = "checkbox";
+      cb.addEventListener("change", () => commit(cb.checked));
+      ctl.appendChild(cb);
+      read = () => {
+        if (!focused(cb)) cb.checked = engine.getProperty(row.ref) === true;
+      };
+    } else if (row.type === "number") {
+      const inp = doc.createElement("input");
+      inp.type = "number";
+      inp.addEventListener("change", () => commit(Number(inp.value)));
+      ctl.appendChild(inp);
+      read = () => {
+        if (!focused(inp)) inp.value = String(engine.getProperty(row.ref) ?? "");
+      };
+    } else if (row.type === "enum") {
+      const sel = doc.createElement("select");
+      for (const v of row.values ?? []) {
+        const o = doc.createElement("option");
+        o.value = v;
+        o.textContent = v;
+        sel.appendChild(o);
+      }
+      sel.addEventListener("change", () => commit(sel.value));
+      ctl.appendChild(sel);
+      read = () => {
+        if (!focused(sel)) sel.value = String(engine.getProperty(row.ref) ?? "");
+      };
+    } else if (row.type === "flags") {
+      const inp = doc.createElement("input");
+      inp.type = "text";
+      inp.placeholder = "comma, separated, flags";
+      inp.addEventListener("change", () => commit(inp.value.split(",").map((s) => s.trim()).filter((s) => s.length > 0)));
+      ctl.appendChild(inp);
+      read = () => {
+        if (!focused(inp)) {
+          const v = engine.getProperty(row.ref);
+          inp.value = Array.isArray(v) ? v.join(", ") : "";
+        }
+      };
+    } else {
+      const inp = doc.createElement("input");
+      inp.type = "text";
+      inp.addEventListener("change", () => commit(inp.value));
+      ctl.appendChild(inp);
+      read = () => {
+        if (!focused(inp)) inp.value = String(engine.getProperty(row.ref) ?? "");
+      };
+    }
+    read();
+    syncReset();
+    rowRefreshers.push(() => {
+      read();
+      syncReset();
+    });
+  };
+  const props = engine.listProperties();
+  if (props.length === 0) {
+    const empty = doc.createElement("div");
+    empty.className = "pp-insp-empty";
+    empty.textContent = "No @patter properties.";
+    list.appendChild(empty);
+  } else {
+    for (const row of props) buildRow(row);
+  }
+  const refresh = () => {
+    for (const fn of rowRefreshers) fn();
+  };
+  opts.container?.appendChild(el);
+  const pollMs = opts.pollMs ?? 250;
+  let timer;
+  if (pollMs > 0) timer = setInterval(refresh, pollMs);
+  return {
+    el,
+    refresh,
+    destroy() {
+      if (timer !== void 0) clearInterval(timer);
+      el.remove();
+    }
+  };
+}
+
+// src/audio.ts
+function createAudioResolver(manifestJson, basePath) {
+  const manifest = JSON.parse(manifestJson);
+  const clips = manifest.clips ?? {};
+  const base = basePath.replace(/[/\\]+$/, "");
+  return {
+    resolve(beatId) {
+      const clip = clips[beatId];
+      if (!clip || !clip.file) return null;
+      return base ? `${base}/${clip.file}` : clip.file;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SAVE_SCHEMA,
+  applyLiveBundle,
+  createAudioResolver,
+  createDebugLink,
+  createPropertyInspector,
+  createStateLogger,
+  deserializeState,
+  diffState,
+  getProperty,
+  loadState,
+  saveState,
+  serializeState,
+  setProperties,
+  setProperty,
+  snapshotState
+});

package/dist/index.d.cts

@@ -0,0 +1,151 @@
+import { SaveGame, Engine, StepResult, Bundle } from '@patterkit/runtime';
+
+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. */
+declare function loadState(engine: Engine, env: SaveEnvelope): void;
+/** Serialise the whole game to a JSON string (envelope + save-game) - drop into localStorage or a file. */
+declare function serializeState(engine: Engine): string;
+/** Parse + restore a {@link serializeState} string. Throws on malformed JSON or a foreign envelope. */
+declare function deserializeState(engine: Engine, json: string): void;
+
+/** A property value the engine accepts (a Patter scalar: number / boolean / string / string[] flags). */
+type PropertyValue = Parameters<Engine["setProperty"]>[1];
+/** Read a runtime property (`@hp`, `@scene.locked`, a foreign `@world.x`). Undefined when unset. */
+declare function getProperty(engine: Engine, ref: string): PropertyValue | undefined;
+/** Set one runtime property. Mirrors `engine.setProperty`, exported here for discoverability + symmetry. */
+declare function setProperty(engine: Engine, ref: string, value: PropertyValue): void;
+/** 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). */
+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;
+    /** Prefix tag for every line, e.g. the flow / save-slot name. */
+    label?: string;
+}
+interface StateLogger {
+    /** The current flattened state (no logging). */
+    snapshot(): StateSnapshot;
+    /** Diff since the last capture, log each change, and re-baseline. Returns the changes. */
+    capture(): StateChange[];
+    /** Trace one played step (line / text / game-event / choice / end), including any `gameData`. */
+    logStep(step: StepResult): void;
+}
+/** Create a state logger over an engine. Call `capture()` after each `advance`/`choose` to log mutations. */
+declare function createStateLogger(engine: Engine, opts?: StateLoggerOptions): StateLogger;
+
+/** A minimal structural type for a WebSocket implementation (browsers + Node 21+ have a global one). */
+interface DebugSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: "open" | "close" | "error", listener: () => void): void;
+    /** Incoming editor messages (live bundle refresh). Optional so a bare-bones send-only socket still fits. */
+    addEventListener(type: "message", listener: (ev: {
+        data: unknown;
+    }) => void): void;
+}
+type DebugSocketCtor = new (url: string) => DebugSocketLike;
+interface DebugLinkOptions {
+    /** The running bundle's build identity - pass `bundle.content.hash`. Lets the editor detect a stale build. */
+    build: string;
+    /** Optional project name, shown in the editor's debug panel. */
+    project?: string;
+    /** Editor WebSocket URL. Default `ws://127.0.0.1:4471`. */
+    url?: string;
+    /** A WebSocket constructor to use instead of the global one (Node < 21, or tests with `ws`). */
+    WebSocket?: DebugSocketCtor;
+    /** Live bundle refresh: the editor pushed a freshly compiled bundle. `data` is the .patterc JSON;
+     *  hand it (with your current engine + bundle) to `applyLiveBundle`, re-bind your flow handles if it
+     *  hot-swapped, then call `link.setBuild(build)`. Never called with malformed payloads. */
+    onBundle?: (msg: {
+        build: string;
+        data: string;
+    }) => void;
+}
+interface DebugLink {
+    /** Tell the editor a flow opened (so it can list it in the follow selector). */
+    flowOpened(flowId: string): void;
+    /** Report the current position of a flow - call after each advance()/choose(). */
+    observe(flowId: string, sceneId: string | null, beatId: string | null, type: string, choiceId?: string): void;
+    /** Tell the editor a flow closed. */
+    flowClosed(flowId: string): void;
+    /** After applying a pushed bundle: report the build now running (re-hellos, so the editor's
+     *  match/stale pill updates and it stops re-pushing the same bundle). */
+    setBuild(build: string): void;
+    /** Close the link. */
+    close(): void;
+}
+/**
+ * Open a live debug link to Patterpad. Returns a handle whose calls are no-ops once the editor disconnects
+ * or if it was never listening - safe to leave wired into a shipping build behind a flag.
+ */
+declare function createDebugLink(opts: DebugLinkOptions): DebugLink;
+
+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;
+    /** Which tier applied: "text" (strings-only, nothing restarted) or "structure" (full hot swap). */
+    kind: "text" | "structure";
+}
+/**
+ * Apply a bundle the editor pushed over the debug link. `current` is the bundle `engine` is running
+ * (needed for the structure-hash comparison); `data` is the pushed .patterc JSON. Throws only on
+ * 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, data: string): LiveBundleResult;
+
+interface PropertyInspectorOptions {
+    /** Where to mount the panel. If omitted, append the returned `el` yourself. */
+    container?: HTMLElement;
+    /** Panel heading. Default "Runtime state". */
+    title?: string;
+    /** Live-refresh interval in ms; 0 disables polling (call `refresh()` yourself). Default 250. */
+    pollMs?: number;
+}
+interface PropertyInspector {
+    /** The panel root (already inside `container` if you passed one). */
+    readonly el: HTMLElement;
+    /** Re-read every property and update the editors, skipping the field you're editing. */
+    refresh(): void;
+    /** Stop polling and remove the panel from the DOM. */
+    destroy(): void;
+}
+declare function createPropertyInspector(engine: Engine, opts?: PropertyInspectorOptions): PropertyInspector;
+
+interface AudioResolver {
+    /** The full path/URL of a beat's winning audio take, or null when it has none. */
+    resolve(beatId: string): string | null;
+}
+/**
+ * Build an audio resolver from a `patteraudio.json` manifest string plus the base path/URL its files live
+ * under (wherever you deployed the audio folder). `resolve(beatId)` joins the base with the winning clip's
+ * relative path, or returns null when the beat has no recording. Never throws on a missing beat.
+ */
+declare function createAudioResolver(manifestJson: string, basePath: string): AudioResolver;
+
+export { type AudioResolver, 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, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, diffState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+import { SaveGame, Engine, StepResult, Bundle } from '@patterkit/runtime';
+
+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. */
+declare function loadState(engine: Engine, env: SaveEnvelope): void;
+/** Serialise the whole game to a JSON string (envelope + save-game) - drop into localStorage or a file. */
+declare function serializeState(engine: Engine): string;
+/** Parse + restore a {@link serializeState} string. Throws on malformed JSON or a foreign envelope. */
+declare function deserializeState(engine: Engine, json: string): void;
+
+/** A property value the engine accepts (a Patter scalar: number / boolean / string / string[] flags). */
+type PropertyValue = Parameters<Engine["setProperty"]>[1];
+/** Read a runtime property (`@hp`, `@scene.locked`, a foreign `@world.x`). Undefined when unset. */
+declare function getProperty(engine: Engine, ref: string): PropertyValue | undefined;
+/** Set one runtime property. Mirrors `engine.setProperty`, exported here for discoverability + symmetry. */
+declare function setProperty(engine: Engine, ref: string, value: PropertyValue): void;
+/** 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). */
+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;
+    /** Prefix tag for every line, e.g. the flow / save-slot name. */
+    label?: string;
+}
+interface StateLogger {
+    /** The current flattened state (no logging). */
+    snapshot(): StateSnapshot;
+    /** Diff since the last capture, log each change, and re-baseline. Returns the changes. */
+    capture(): StateChange[];
+    /** Trace one played step (line / text / game-event / choice / end), including any `gameData`. */
+    logStep(step: StepResult): void;
+}
+/** Create a state logger over an engine. Call `capture()` after each `advance`/`choose` to log mutations. */
+declare function createStateLogger(engine: Engine, opts?: StateLoggerOptions): StateLogger;
+
+/** A minimal structural type for a WebSocket implementation (browsers + Node 21+ have a global one). */
+interface DebugSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: "open" | "close" | "error", listener: () => void): void;
+    /** Incoming editor messages (live bundle refresh). Optional so a bare-bones send-only socket still fits. */
+    addEventListener(type: "message", listener: (ev: {
+        data: unknown;
+    }) => void): void;
+}
+type DebugSocketCtor = new (url: string) => DebugSocketLike;
+interface DebugLinkOptions {
+    /** The running bundle's build identity - pass `bundle.content.hash`. Lets the editor detect a stale build. */
+    build: string;
+    /** Optional project name, shown in the editor's debug panel. */
+    project?: string;
+    /** Editor WebSocket URL. Default `ws://127.0.0.1:4471`. */
+    url?: string;
+    /** A WebSocket constructor to use instead of the global one (Node < 21, or tests with `ws`). */
+    WebSocket?: DebugSocketCtor;
+    /** Live bundle refresh: the editor pushed a freshly compiled bundle. `data` is the .patterc JSON;
+     *  hand it (with your current engine + bundle) to `applyLiveBundle`, re-bind your flow handles if it
+     *  hot-swapped, then call `link.setBuild(build)`. Never called with malformed payloads. */
+    onBundle?: (msg: {
+        build: string;
+        data: string;
+    }) => void;
+}
+interface DebugLink {
+    /** Tell the editor a flow opened (so it can list it in the follow selector). */
+    flowOpened(flowId: string): void;
+    /** Report the current position of a flow - call after each advance()/choose(). */
+    observe(flowId: string, sceneId: string | null, beatId: string | null, type: string, choiceId?: string): void;
+    /** Tell the editor a flow closed. */
+    flowClosed(flowId: string): void;
+    /** After applying a pushed bundle: report the build now running (re-hellos, so the editor's
+     *  match/stale pill updates and it stops re-pushing the same bundle). */
+    setBuild(build: string): void;
+    /** Close the link. */
+    close(): void;
+}
+/**
+ * Open a live debug link to Patterpad. Returns a handle whose calls are no-ops once the editor disconnects
+ * or if it was never listening - safe to leave wired into a shipping build behind a flag.
+ */
+declare function createDebugLink(opts: DebugLinkOptions): DebugLink;
+
+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;
+    /** Which tier applied: "text" (strings-only, nothing restarted) or "structure" (full hot swap). */
+    kind: "text" | "structure";
+}
+/**
+ * Apply a bundle the editor pushed over the debug link. `current` is the bundle `engine` is running
+ * (needed for the structure-hash comparison); `data` is the pushed .patterc JSON. Throws only on
+ * 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, data: string): LiveBundleResult;
+
+interface PropertyInspectorOptions {
+    /** Where to mount the panel. If omitted, append the returned `el` yourself. */
+    container?: HTMLElement;
+    /** Panel heading. Default "Runtime state". */
+    title?: string;
+    /** Live-refresh interval in ms; 0 disables polling (call `refresh()` yourself). Default 250. */
+    pollMs?: number;
+}
+interface PropertyInspector {
+    /** The panel root (already inside `container` if you passed one). */
+    readonly el: HTMLElement;
+    /** Re-read every property and update the editors, skipping the field you're editing. */
+    refresh(): void;
+    /** Stop polling and remove the panel from the DOM. */
+    destroy(): void;
+}
+declare function createPropertyInspector(engine: Engine, opts?: PropertyInspectorOptions): PropertyInspector;
+
+interface AudioResolver {
+    /** The full path/URL of a beat's winning audio take, or null when it has none. */
+    resolve(beatId: string): string | null;
+}
+/**
+ * Build an audio resolver from a `patteraudio.json` manifest string plus the base path/URL its files live
+ * under (wherever you deployed the audio folder). `resolve(beatId)` joins the base with the winning clip's
+ * relative path, or returns null when the beat has no recording. Never throws on a missing beat.
+ */
+declare function createAudioResolver(manifestJson: string, basePath: string): AudioResolver;
+
+export { type AudioResolver, 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, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, diffState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };

package/dist/index.js

@@ -0,0 +1,373 @@
+// src/save.ts
+var SAVE_SCHEMA = "patter/save@0";
+function saveState(engine) {
+  return { schema: 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`);
+  }
+  engine.loadGame(env.save);
+}
+function serializeState(engine) {
+  return JSON.stringify(saveState(engine));
+}
+function deserializeState(engine, json) {
+  loadState(engine, JSON.parse(json));
+}
+
+// src/properties.ts
+function getProperty(engine, ref) {
+  return engine.getProperty(ref);
+}
+function setProperty(engine, ref, value) {
+  engine.setProperty(ref, value);
+}
+function setProperties(engine, values) {
+  for (const [ref, value] of Object.entries(values)) engine.setProperty(ref, value);
+}
+
+// src/logger.ts
+var eq = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+function snapshotState(engine) {
+  const save = engine.saveGame();
+  const out = {};
+  for (const [name, v] of Object.entries(save.shared.patter ?? {})) out[`@patter.${name}`] = v;
+  for (const [scene, vals] of Object.entries(save.stageBags))
+    for (const [name, v] of Object.entries(vals)) out[`@scene:${scene}.${name}`] = v;
+  for (const [id, n] of Object.entries(save.sharedVisits)) out[`visit:${id}`] = n;
+  for (const [fid, snap] of Object.entries(save.flows)) {
+    for (const [name, v] of Object.entries(snap.scopes.patter ?? {})) out[`${fid}/@patter.${name}`] = v;
+    for (const [scene, vals] of Object.entries(snap.sceneBags))
+      for (const [name, v] of Object.entries(vals)) out[`${fid}/@scene:${scene}.${name}`] = v;
+    for (const [id, n] of Object.entries(snap.visits)) out[`${fid}/visit:${id}`] = n;
+  }
+  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":
+      return `line ${step.character ?? "?"}: ${JSON.stringify(step.text)}${gd(step.gameData)}`;
+    case "text":
+      return `text: ${JSON.stringify(step.text)}${gd(step.gameData)}`;
+    case "gameEvent":
+      return `game event ${step.id}${gd(step.gameData)}`;
+    case "choice":
+      return `choice (${step.options.length} option${step.options.length === 1 ? "" : "s"})`;
+    case "end":
+      return "end";
+  }
+}
+var gd = (data) => data ? ` gameData=${JSON.stringify(data)}` : "";
+function createStateLogger(engine, opts = {}) {
+  const sink = opts.sink ?? ((line) => console.log(line));
+  const tag = opts.label ? `[${opts.label}] ` : "";
+  let baseline = snapshotState(engine);
+  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;
+    },
+    logStep(step) {
+      sink(`${tag}${describeStep(step)}`);
+    }
+  };
+}
+
+// src/debug.ts
+var OPEN = 1;
+function createDebugLink(opts) {
+  const url = opts.url ?? "ws://127.0.0.1:4471";
+  const Ctor = opts.WebSocket ?? globalThis.WebSocket;
+  const flows = /* @__PURE__ */ new Set();
+  let queue = [];
+  let sock = null;
+  let closed = false;
+  let build = opts.build;
+  const flush = () => {
+    if (!sock || sock.readyState !== OPEN) return;
+    for (const m of queue) {
+      try {
+        sock.send(m);
+      } catch {
+      }
+    }
+    queue = [];
+  };
+  const post = (msg) => {
+    if (closed) return;
+    queue.push(JSON.stringify(msg));
+    flush();
+  };
+  if (!Ctor) {
+    return { flowOpened() {
+    }, observe() {
+    }, flowClosed() {
+    }, setBuild() {
+    }, close() {
+      closed = true;
+    } };
+  }
+  const sendHello = () => {
+    const hello = JSON.stringify({ t: "hello", v: 1, build, project: opts.project, flows: [...flows] });
+    try {
+      sock?.send(hello);
+    } catch {
+    }
+  };
+  try {
+    sock = new Ctor(url);
+    sock.addEventListener("open", () => {
+      sendHello();
+      flush();
+    });
+    sock.addEventListener("message", (ev) => {
+      if (!opts.onBundle || typeof ev.data !== "string") return;
+      try {
+        const msg = JSON.parse(ev.data);
+        if (msg.t === "bundle" && typeof msg.build === "string" && typeof msg.data === "string") {
+          opts.onBundle({ build: msg.build, data: msg.data });
+        }
+      } catch {
+      }
+    });
+    sock.addEventListener("error", () => {
+    });
+    sock.addEventListener("close", () => {
+      sock = null;
+    });
+  } catch {
+    sock = null;
+  }
+  return {
+    flowOpened(flowId) {
+      flows.add(flowId);
+      post({ t: "flowOpen", flow: flowId });
+    },
+    flowClosed(flowId) {
+      flows.delete(flowId);
+      post({ t: "flowClose", flow: flowId });
+    },
+    observe(flowId, sceneId, beatId, type, choiceId) {
+      post({ t: "frame", flow: flowId, sceneId, beatId, type, choiceId });
+    },
+    setBuild(next) {
+      if (closed || next === build) return;
+      build = next;
+      if (sock && sock.readyState === OPEN) sendHello();
+    },
+    close() {
+      closed = true;
+      queue = [];
+      try {
+        sock?.close();
+      } catch {
+      }
+      sock = null;
+    }
+  };
+}
+
+// src/refresh.ts
+import "@patterkit/runtime";
+function applyLiveBundle(engine, current, data) {
+  const next = JSON.parse(data);
+  const sameStructure = current.content.structureHash !== void 0 && current.content.structureHash === next.content.structureHash;
+  if (sameStructure) {
+    engine.replaceStrings(next);
+    return { engine, bundle: next, kind: "text" };
+  }
+  return { engine: engine.hotSwap(next), bundle: next, kind: "structure" };
+}
+
+// src/inspector.ts
+var STYLE_ID = "pp-inspector-style";
+var CSS = `
+.pp-insp{font:13px/1.4 ui-sans-serif,system-ui,sans-serif;color:#15201e;background:#f4efe6;border:1px solid #cfc7b8;border-radius:10px;padding:.6rem .7rem;max-width:22rem;box-shadow:0 6px 20px rgba(21,32,30,.12)}
+.pp-insp h4{margin:0 0 .4rem;font:600 .72rem/1 ui-sans-serif,system-ui,sans-serif;letter-spacing:.08em;text-transform:uppercase;color:#5c6b62}
+.pp-insp-empty{color:#8a9691;font-style:italic}
+.pp-insp-row{display:flex;align-items:center;gap:.4rem;margin:.18rem 0}
+.pp-insp-ref{flex:0 0 8rem;font-family:ui-monospace,monospace;font-size:.78rem;color:#214f4b;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.pp-insp-ctl{flex:1;min-width:0;display:flex}
+.pp-insp-ctl input[type=text],.pp-insp-ctl input[type=number],.pp-insp-ctl select{width:100%;box-sizing:border-box;font:inherit;padding:.15rem .3rem;border:1px solid #cfc7b8;border-radius:6px;background:#fff;color:inherit}
+.pp-insp-reset{flex:0 0 auto;border:1px solid #cfc7b8;background:#fff;border-radius:6px;cursor:pointer;color:#5c6b62;width:1.6rem;height:1.6rem;line-height:1;padding:0}
+.pp-insp-reset:disabled{opacity:.35;cursor:default}
+`;
+function injectStyle(doc) {
+  if (doc.getElementById(STYLE_ID)) return;
+  const s = doc.createElement("style");
+  s.id = STYLE_ID;
+  s.textContent = CSS;
+  (doc.head ?? doc.documentElement).appendChild(s);
+}
+function sameValue(a, b) {
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((x, i) => x === b[i]);
+  return a === b;
+}
+function createPropertyInspector(engine, opts = {}) {
+  const doc = opts.container?.ownerDocument ?? document;
+  injectStyle(doc);
+  const el = doc.createElement("div");
+  el.className = "pp-insp";
+  const heading = doc.createElement("h4");
+  heading.textContent = opts.title ?? "Runtime state";
+  const list = doc.createElement("div");
+  el.append(heading, list);
+  const rowRefreshers = [];
+  const buildRow = (row) => {
+    const r = doc.createElement("div");
+    r.className = "pp-insp-row";
+    const label = doc.createElement("span");
+    label.className = "pp-insp-ref";
+    label.textContent = row.ref;
+    label.title = row.ref;
+    const ctl = doc.createElement("div");
+    ctl.className = "pp-insp-ctl";
+    const reset = doc.createElement("button");
+    reset.className = "pp-insp-reset";
+    reset.type = "button";
+    reset.textContent = "\u21BA";
+    reset.title = "Reset to default";
+    r.append(label, ctl, reset);
+    list.appendChild(r);
+    let read;
+    const commit = (v) => {
+      engine.setProperty(row.ref, v);
+      syncReset();
+    };
+    const focused = (node) => doc.activeElement === node;
+    function syncReset() {
+      reset.disabled = sameValue(engine.getProperty(row.ref), row.default);
+    }
+    reset.addEventListener("click", () => {
+      engine.setProperty(row.ref, row.default);
+      read();
+      syncReset();
+    });
+    if (row.type === "boolean") {
+      const cb = doc.createElement("input");
+      cb.type = "checkbox";
+      cb.addEventListener("change", () => commit(cb.checked));
+      ctl.appendChild(cb);
+      read = () => {
+        if (!focused(cb)) cb.checked = engine.getProperty(row.ref) === true;
+      };
+    } else if (row.type === "number") {
+      const inp = doc.createElement("input");
+      inp.type = "number";
+      inp.addEventListener("change", () => commit(Number(inp.value)));
+      ctl.appendChild(inp);
+      read = () => {
+        if (!focused(inp)) inp.value = String(engine.getProperty(row.ref) ?? "");
+      };
+    } else if (row.type === "enum") {
+      const sel = doc.createElement("select");
+      for (const v of row.values ?? []) {
+        const o = doc.createElement("option");
+        o.value = v;
+        o.textContent = v;
+        sel.appendChild(o);
+      }
+      sel.addEventListener("change", () => commit(sel.value));
+      ctl.appendChild(sel);
+      read = () => {
+        if (!focused(sel)) sel.value = String(engine.getProperty(row.ref) ?? "");
+      };
+    } else if (row.type === "flags") {
+      const inp = doc.createElement("input");
+      inp.type = "text";
+      inp.placeholder = "comma, separated, flags";
+      inp.addEventListener("change", () => commit(inp.value.split(",").map((s) => s.trim()).filter((s) => s.length > 0)));
+      ctl.appendChild(inp);
+      read = () => {
+        if (!focused(inp)) {
+          const v = engine.getProperty(row.ref);
+          inp.value = Array.isArray(v) ? v.join(", ") : "";
+        }
+      };
+    } else {
+      const inp = doc.createElement("input");
+      inp.type = "text";
+      inp.addEventListener("change", () => commit(inp.value));
+      ctl.appendChild(inp);
+      read = () => {
+        if (!focused(inp)) inp.value = String(engine.getProperty(row.ref) ?? "");
+      };
+    }
+    read();
+    syncReset();
+    rowRefreshers.push(() => {
+      read();
+      syncReset();
+    });
+  };
+  const props = engine.listProperties();
+  if (props.length === 0) {
+    const empty = doc.createElement("div");
+    empty.className = "pp-insp-empty";
+    empty.textContent = "No @patter properties.";
+    list.appendChild(empty);
+  } else {
+    for (const row of props) buildRow(row);
+  }
+  const refresh = () => {
+    for (const fn of rowRefreshers) fn();
+  };
+  opts.container?.appendChild(el);
+  const pollMs = opts.pollMs ?? 250;
+  let timer;
+  if (pollMs > 0) timer = setInterval(refresh, pollMs);
+  return {
+    el,
+    refresh,
+    destroy() {
+      if (timer !== void 0) clearInterval(timer);
+      el.remove();
+    }
+  };
+}
+
+// src/audio.ts
+function createAudioResolver(manifestJson, basePath) {
+  const manifest = JSON.parse(manifestJson);
+  const clips = manifest.clips ?? {};
+  const base = basePath.replace(/[/\\]+$/, "");
+  return {
+    resolve(beatId) {
+      const clip = clips[beatId];
+      if (!clip || !clip.file) return null;
+      return base ? `${base}/${clip.file}` : clip.file;
+    }
+  };
+}
+export {
+  SAVE_SCHEMA,
+  applyLiveBundle,
+  createAudioResolver,
+  createDebugLink,
+  createPropertyInspector,
+  createStateLogger,
+  deserializeState,
+  diffState,
+  getProperty,
+  loadState,
+  saveState,
+  serializeState,
+  setProperties,
+  setProperty,
+  snapshotState
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@patterkit/play-helpers",
+  "version": "0.1.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",
+  "author": "Ian Thomas",
+  "homepage": "https://patterkit.dev",
+  "repository": { "type": "git", "url": "git+https://github.com/patterkit/patter.git", "directory": "packages/play-helpers" },
+  "bugs": "https://github.com/patterkit/patter/issues",
+  "publishConfig": { "access": "public" },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean"
+  },
+  "dependencies": {
+    "@patterkit/runtime": "0.1.0"
+  }
+}