@storylet-studio/play-helpers 0.4.0

package/dist/index.js

@@ -0,0 +1,999 @@
+// ../../../expr/packages/scoperegistry/src/state-logger.ts
+function diffState(prev, next) {
+  const changes = [];
+  const paths = /* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(next)]);
+  for (const path of [...paths].sort()) {
+    const from = prev[path], to = next[path];
+    if (JSON.stringify(from) !== JSON.stringify(to)) changes.push({ path, from, to });
+  }
+  return changes;
+}
+var show = (v) => v === void 0 ? "<unset>" : JSON.stringify(v);
+var prefixOf = (m) => m.pathPrefix ?? m.bag.pathPrefix;
+function createStateLogger(adapter, opts = {}) {
+  const sink = opts.sink ?? ((line2) => console.log(line2));
+  const label = opts.label ?? "";
+  const emit = (c) => {
+    sink(`${label}${c.path}: ${show(c.from)} -> ${show(c.to)}`);
+  };
+  const full = () => {
+    const out = {};
+    for (const m of adapter.mounts()) {
+      const prefix = prefixOf(m);
+      for (const [name, value] of Object.entries(m.bag.values)) out[prefix + name] = value;
+    }
+    Object.assign(out, adapter.extra?.() ?? {});
+    return structuredClone(out);
+  };
+  let baseline = full();
+  let pushed = [];
+  let mounted = [];
+  const hook = (prefix, bag) => bag.onAudit((change) => {
+    const c = structuredClone({ path: prefix + change.name, from: change.prev, to: change.next });
+    emit(c);
+    pushed.push(c);
+    baseline[c.path] = structuredClone(change.next);
+  });
+  const mount = () => {
+    const mounts = adapter.mounts();
+    const same = mounted.length === mounts.length && mounts.every((m, i) => mounted[i].bag === m.bag);
+    if (same) return;
+    for (const m of mounted) m.off();
+    mounted = mounts.map((m) => ({ bag: m.bag, off: hook(prefixOf(m), m.bag) }));
+  };
+  mount();
+  return {
+    snapshot: full,
+    capture() {
+      const next = full();
+      const diffed = diffState(baseline, next);
+      for (const c of diffed) emit(c);
+      const changes = [...pushed, ...diffed];
+      pushed = [];
+      baseline = next;
+      mount();
+      return changes;
+    },
+    dispose() {
+      for (const m of mounted) m.off();
+      mounted = [];
+      pushed = [];
+    }
+  };
+}
+
+// ../../../expr/packages/scoperegistry/src/index.ts
+var PropertyBag = class _PropertyBag {
+  /** The live values record (stable identity across reseed, so an
+   *  EvalContext built over it stays valid). Read-path for evaluation;
+   *  writes go through `set` so the firing rule applies. */
+  values = {};
+  decls = /* @__PURE__ */ new Map();
+  subscribers = /* @__PURE__ */ new Set();
+  auditors = /* @__PURE__ */ new Set();
+  /** Name normalisation policy: lowercase by default (the registry's
+   *  long-standing contract); a product whose names are case-significant
+   *  passes identity. */
+  norm;
+  /** The address prefix this bag's rows carry, separator included (`@`,
+   *  `@scene.`, `world.`, `deck.<id>.`). Empty means a row's path is its name. */
+  pathPrefix;
+  constructor(declarations = [], opts) {
+    this.norm = opts?.normalise ?? ((n) => n.toLowerCase());
+    this.pathPrefix = opts?.pathPrefix ?? "";
+    this.seed(declarations);
+  }
+  seed(declarations) {
+    for (const d of declarations) {
+      const name = this.norm(d.name);
+      this.decls.set(name, d);
+      this.values[name] = structuredClone(d.default ?? defaultFor(d));
+    }
+  }
+  get(name) {
+    return this.values[this.norm(name)];
+  }
+  /** Write a property. Engine writes (the default) notify subscribers;
+   *  pass `silent: true` for a host write, which reaches only the audit
+   *  hook. Throws on a read-only property. Returns the change. */
+  set(name, value, opts) {
+    const n = this.norm(name);
+    if (this.decls.get(n)?.writable === false) throw new Error(`'${name}' is read-only`);
+    const change = {
+      name: n,
+      prev: this.values[n],
+      next: value,
+      silent: opts?.silent ?? false,
+      reason: opts?.reason
+    };
+    this.values[n] = value;
+    for (const audit of this.auditors) audit(change);
+    if (!change.silent) for (const fn of this.subscribers) fn(change);
+    return change;
+  }
+  /** Notified of engine (non-silent) writes. Returns the unsubscribe. */
+  subscribe(fn) {
+    this.subscribers.add(fn);
+    return () => this.subscribers.delete(fn);
+  }
+  /** Notified of EVERY write, silent or not. Returns the unsubscribe. */
+  onAudit(fn) {
+    this.auditors.add(fn);
+    return () => this.auditors.delete(fn);
+  }
+  /** Examiner rows: the declared surface only (stray values are storage,
+   *  not surface). */
+  rows() {
+    return [...this.decls.entries()].map(([name, d]) => rowFor(d, this.get(name), void 0, name, this.pathPrefix));
+  }
+  declarations() {
+    return [...this.decls.values()];
+  }
+  /** The one sanctioned copy door: values deep-copied, declarations
+   *  duplicated, the normalisation policy carried, subscriptions NOT
+   *  carried. */
+  clone() {
+    const c = new _PropertyBag([], { normalise: this.norm, pathPrefix: this.pathPrefix });
+    c.decls = new Map(this.decls);
+    Object.assign(c.values, structuredClone(this.values));
+    return c;
+  }
+  /** Clear and re-seed from new declarations, in place (the values record
+   *  keeps its identity, so contexts built over it stay valid). */
+  reseed(declarations) {
+    for (const k of Object.keys(this.values)) delete this.values[k];
+    this.decls.clear();
+    this.seed(declarations);
+  }
+  /** Bare values, ready to embed in a product's save. */
+  save() {
+    return structuredClone(this.values);
+  }
+  /** Lay saved values over the current ones (call after a fresh seed:
+   *  orphans land as strays, new declarations keep their defaults; the
+   *  product decides whether to prune). Does not fire events. */
+  load(values) {
+    for (const [k, v] of Object.entries(values)) this.values[this.norm(k)] = v;
+  }
+};
+function rowFor(d, value, writable, name, pathPrefix = "") {
+  const rowName = name ?? d.name.toLowerCase();
+  return {
+    name: rowName,
+    path: pathPrefix + rowName,
+    type: d.type,
+    value,
+    default: d.default ?? defaultFor(d),
+    ...d.values !== void 0 ? { values: d.values } : {},
+    // `stages` was added to the row so an examiner could offer a quality's ladder
+    // instead of a free-text box, and then never populated here: every quality row
+    // this function built came out without one. Fixed 2026-09-02.
+    ...d.stages !== void 0 ? { stages: d.stages } : {},
+    writable: writable ?? d.writable ?? true
+  };
+}
+function defaultFor(d) {
+  if (d.default !== void 0) return d.default;
+  switch (d.type) {
+    case "boolean":
+      return false;
+    case "number":
+      return 0;
+    case "string":
+      return "";
+    case "enum":
+      return d.values?.[0] ?? "";
+    case "flags":
+      return [];
+    // A quality starts at the first rung of its ladder.
+    case "quality":
+      return d.stages?.[0] ?? "";
+    // Unreachable for a well-typed declaration, and deliberately present anyway: a bundle
+    // is DATA, and a hand-edited or newer-than-this-build one can carry a type string the
+    // union does not have. Falling off the switch would seed `undefined`, which is not a
+    // ScalarValue and travels a long way before it fails. Patterplay's copy of this had the
+    // guard and this one did not, which is the drift you only find by removing a duplicate.
+    default:
+      return false;
+  }
+}
+
+// src/logger.ts
+function snapshotState(engine, flow) {
+  const env = engine.saveGame();
+  const flowSave = env.flows[flow.id];
+  const out = {};
+  const bag = (prefix, values) => {
+    for (const [name, value] of Object.entries(values ?? {})) out[`${prefix}.${name}`] = value;
+  };
+  bag("story", env.shared.props.story);
+  bag("story", flowSave?.props.story);
+  for (const kind of ["box", "deck", "hand", "value"]) {
+    for (const [id, values] of Object.entries(env.shared.props[kind])) bag(`${kind}.${id}`, values);
+    for (const [id, values] of Object.entries(flowSave?.props[kind] ?? {})) bag(`${kind}.${id}`, values);
+  }
+  Object.assign(out, extraState(env.flows[flow.id]));
+  return out;
+}
+function extraState(saved) {
+  const out = {};
+  if (saved === void 0) return out;
+  for (const [boxId, turn] of Object.entries(saved.turns)) out[`turn:${boxId}`] = turn;
+  for (const [cardId, at] of Object.entries(saved.cooldowns)) out[`cooldown:${cardId}`] = at;
+  for (const [handId, cards] of Object.entries(saved.board)) out[`board:${handId}`] = [...cards];
+  return out;
+}
+function createStateLogger2(engine, flow, opts = {}) {
+  const id = flow.id;
+  const live = () => engine.getFlow(id);
+  return createStateLogger({
+    // A BagMount's `prefix` ("story", "deck.<id>") is the engine's label for the mount;
+    // the kernel composes paths from the BAG's own pathPrefix ("story.", "deck.<id>.")
+    // and needs none passed. Same strings, one owner.
+    mounts: () => [...engine.listBags(), ...live()?.listBags() ?? []].map(({ bag }) => ({ bag })),
+    extra: () => extraState(engine.saveGame().flows[id])
+  }, opts);
+}
+
+// ../model/src/index.ts
+var SAVE_SCHEMA = "storylets/save@1";
+var SAVEFILE_SCHEMA = "storylets/savefile@1";
+
+// src/save.ts
+function serializeState(engine, world) {
+  return JSON.stringify(saveState(engine, world), null, 2);
+}
+function saveState(engine, world) {
+  return {
+    schema: SAVEFILE_SCHEMA,
+    engine: engine.saveGame(),
+    ...world !== void 0 ? { world } : {}
+  };
+}
+function loadState(engine, file) {
+  if (!file || typeof file !== "object" || file.schema !== SAVEFILE_SCHEMA || file.engine?.schema !== SAVE_SCHEMA) {
+    throw new Error(`not a storylets save (expected schema "${SAVEFILE_SCHEMA}")`);
+  }
+  engine.loadGame(file.engine);
+  return file.world;
+}
+function deserializeState(engine, json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw new Error("not valid JSON");
+  }
+  return loadState(engine, parsed);
+}
+
+// src/inspector.ts
+var STYLE_ID = "sl-inspector-style";
+var CSS = `
+.sl-insp { font: 12px system-ui, sans-serif; color: var(--ink, #222); background: var(--surface, #fafafa);
+  border: 1px solid var(--line, #ccc); border-radius: 8px; padding: 10px 12px; max-width: 26rem; }
+.sl-insp h3 { margin: 0 0 8px; font-size: 12px; text-transform: uppercase; letter-spacing: 0.06em;
+  color: var(--muted, #666); }
+.sl-insp .sl-head { display: flex; align-items: baseline; gap: 6px; }
+.sl-insp .sl-head h3 { flex: 1; }
+.sl-insp .sl-save, .sl-insp .sl-load { font: inherit; font-size: 11px; padding: 1px 6px; cursor: pointer; }
+.sl-insp .sl-filter { display: block; width: 100%; box-sizing: border-box; margin: 0 0 6px; }
+.sl-insp .sl-group { margin: 8px 0 2px; font-weight: 600; font-size: 11px; color: var(--muted, #666); }
+.sl-insp .sl-section { margin: 10px 0 2px; font-weight: 600; font-size: 11px; text-transform: uppercase;
+  letter-spacing: 0.06em; color: var(--muted, #666); }
+.sl-insp .sl-line { padding: 1px 0; }
+.sl-insp .sl-row { display: flex; align-items: center; gap: 6px; padding: 2px 0; }
+.sl-insp .sl-name { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.sl-insp input[type="text"], .sl-insp input[type="number"], .sl-insp select {
+  font: inherit; width: 9rem; padding: 1px 4px; }
+.sl-insp .sl-reset { border: 0; background: none; cursor: pointer; color: var(--muted, #666); }
+.sl-insp .sl-reset:disabled { opacity: 0.3; cursor: default; }
+.sl-insp .sl-logbar { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 2px 0; }
+.sl-insp .sl-logbar label { display: inline-flex; align-items: center; gap: 2px; }
+.sl-insp .sl-logbar button { font: inherit; font-size: 11px; padding: 1px 6px; cursor: pointer; }
+.sl-insp .sl-log { font-family: ui-monospace, monospace; font-size: 11px; max-height: 12rem;
+  overflow: auto; white-space: pre; border: 1px solid var(--line, #ccc); padding: 4px 6px; }
+.sl-insp details.sl-fold > summary { cursor: pointer; margin: 10px 0 2px; font-weight: 600;
+  font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted, #666); }
+.sl-insp .sl-ident { font-family: ui-monospace, monospace; font-size: 11px; }
+.sl-insp .sl-ident b { font-weight: 600; }
+.sl-insp .sl-note { color: var(--muted, #666); }
+`;
+function ensureInspectorStyle() {
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = CSS;
+  document.head.append(style);
+}
+var eq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+var LOG_KINDS = ["deal", "play", "write", "evict", "turns", "diagnostic"];
+var LOG_KIND_LABELS = {
+  deal: "Deal",
+  play: "Play",
+  write: "Write",
+  evict: "Evict",
+  turns: "Turns",
+  diagnostic: "Diag"
+};
+var logKindOf = (e) => e.type === "peek" ? "deal" : e.type;
+var showVal = (v) => v === void 0 ? "<unset>" : JSON.stringify(v);
+function formatLogEntry(e) {
+  return formatLogBody(e, "flow" in e && e.flow ? `${e.flow} ` : "");
+}
+function formatLogBody(e, flow) {
+  const stamp = (e.turn !== void 0 ? `[${e.turn}] ` : "[-] ") + flow;
+  switch (e.type) {
+    case "deal": {
+      const dealt = e.cards.filter((c) => c.verdict === "dealt").map((c) => c.id);
+      return `${stamp}deal ${e.hand}: ${dealt.length > 0 ? dealt.join(", ") : "(none)"} (${e.cards.length} considered)`;
+    }
+    case "peek": {
+      const crit = Object.entries(e.criteria).map(([g, t]) => `${g}=${t}`).join(", ");
+      const listed = e.cards.filter((c) => c.verdict === "dealt").map((c) => c.id);
+      return `${stamp}peek ${e.box}${crit ? ` [${crit}]` : ""}: ${listed.length > 0 ? listed.join(", ") : "(none)"} (${e.cards.length} considered)`;
+    }
+    case "evict":
+      return `${stamp}evict ${e.card} from ${e.hand} (${e.reason})`;
+    case "play":
+      return `${stamp}play ${e.card} -> ${e.outcome}`;
+    case "write":
+      return `${stamp}write ${e.path}: ${showVal(e.prev)} -> ${showVal(e.value)}`;
+    case "turns":
+      return `${stamp}turns ${e.box} -> ${e.turn}`;
+    default:
+      return `${stamp}diagnostic ${e.where}: ${e.message}`;
+  }
+}
+var groupOf = (path) => {
+  const parts = path.split(".");
+  return parts.length === 3 ? `${parts[0]} ${parts[1]}` : parts[0];
+};
+function createPropertyInspector(engine, flow, opts = {}) {
+  ensureInspectorStyle();
+  let liveFlow = flow;
+  const live = () => liveFlow;
+  const el = document.createElement("div");
+  el.className = "sl-insp";
+  const head = document.createElement("div");
+  head.className = "sl-head";
+  const h = document.createElement("h3");
+  h.textContent = opts.title ?? "Runtime state";
+  head.append(h);
+  const saveBtn = document.createElement("button");
+  saveBtn.type = "button";
+  saveBtn.className = "sl-save";
+  saveBtn.textContent = "Save state";
+  saveBtn.addEventListener("click", () => {
+    const blob = new Blob([serializeState(engine)], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = "save.storyletsave";
+    a.click();
+    URL.revokeObjectURL(url);
+  });
+  head.append(saveBtn);
+  const filePicker = document.createElement("input");
+  filePicker.type = "file";
+  filePicker.accept = ".storyletsave,application/json";
+  filePicker.hidden = true;
+  filePicker.addEventListener("change", () => {
+    const file = filePicker.files?.[0];
+    if (!file) return;
+    const reader = new FileReader();
+    reader.onload = () => {
+      try {
+        deserializeState(engine, String(reader.result));
+        liveFlow = engine.getFlow(flow.id) ?? engine.openFlow(flow.id);
+        refresh();
+      } catch (e) {
+        console.error("storylets inspector: load failed:", e instanceof Error ? e.message : e);
+      }
+      filePicker.value = "";
+    };
+    reader.readAsText(file);
+  });
+  const loadBtn = document.createElement("button");
+  loadBtn.type = "button";
+  loadBtn.className = "sl-load";
+  loadBtn.textContent = "Load state";
+  loadBtn.addEventListener("click", () => filePicker.click());
+  head.append(loadBtn, filePicker);
+  el.append(head);
+  const filter = document.createElement("input");
+  filter.type = "text";
+  filter.className = "sl-filter";
+  filter.placeholder = "Filter properties";
+  el.append(filter);
+  const editors = [];
+  const groups = [];
+  let lastGroup = "";
+  for (const row of live().listProperties()) {
+    const group = groupOf(row.path);
+    if (group !== lastGroup) {
+      const g = document.createElement("div");
+      g.className = "sl-group";
+      g.textContent = group;
+      el.append(g);
+      groups.push({ el: g, rows: [] });
+      lastGroup = group;
+    }
+    const rowEl = buildRow(live, row, editors);
+    groups[groups.length - 1].rows.push({ el: rowEl, text: `${row.name} ${row.path}`.toLowerCase() });
+    el.append(rowEl);
+  }
+  filter.addEventListener("input", () => {
+    const q = filter.value.trim().toLowerCase();
+    for (const group of groups) {
+      let any = false;
+      for (const row of group.rows) {
+        const show2 = q === "" || row.text.includes(q);
+        row.el.style.display = show2 ? "" : "none";
+        any = any || show2;
+      }
+      group.el.style.display = any ? "" : "none";
+    }
+  });
+  const turnsHead = document.createElement("div");
+  turnsHead.className = "sl-section";
+  turnsHead.textContent = "Turns (per box)";
+  const turnsBody = document.createElement("div");
+  turnsBody.className = "sl-turns";
+  const boardHead = document.createElement("div");
+  boardHead.className = "sl-section";
+  boardHead.textContent = "Board";
+  const boardBody = document.createElement("div");
+  boardBody.className = "sl-board";
+  el.append(turnsHead, turnsBody, boardHead, boardBody);
+  const check = (text, onChange, cls) => {
+    const label = document.createElement("label");
+    label.className = cls;
+    const box = document.createElement("input");
+    box.type = "checkbox";
+    box.checked = true;
+    box.addEventListener("change", () => onChange(box.checked));
+    label.append(box, text);
+    return label;
+  };
+  const buildLogPanel = (which, caption, entriesOf, clear, empty) => {
+    const head2 = document.createElement("div");
+    head2.className = `sl-section sl-${which}`;
+    head2.textContent = caption;
+    const bar = document.createElement("div");
+    bar.className = `sl-logbar sl-${which}`;
+    const body = document.createElement("div");
+    body.className = `sl-log sl-${which}`;
+    const kindOn = /* @__PURE__ */ new Map();
+    const visibleLines = () => entriesOf().filter((e) => kindOn.get(logKindOf(e)) !== false).map(formatLogEntry);
+    let autoscroll = true;
+    let stampSeen = "";
+    const render = (force = false) => {
+      const entries = entriesOf();
+      const stamp = `${entries.length}:${entries.length > 0 ? entries[entries.length - 1].seq : -1}`;
+      if (!force && stamp === stampSeen) return;
+      stampSeen = stamp;
+      const lines = visibleLines();
+      body.textContent = lines.length > 0 ? lines.join("\n") : empty;
+      if (autoscroll) body.scrollTop = body.scrollHeight;
+    };
+    for (const kind of LOG_KINDS) {
+      kindOn.set(kind, true);
+      bar.append(check(LOG_KIND_LABELS[kind], (on) => {
+        kindOn.set(kind, on);
+        render(true);
+      }, "sl-logkind"));
+    }
+    bar.append(check("Autoscroll", (on) => {
+      autoscroll = on;
+    }, "sl-logscroll"));
+    const copyBtn = document.createElement("button");
+    copyBtn.type = "button";
+    copyBtn.className = "sl-logcopy";
+    copyBtn.textContent = "Copy";
+    copyBtn.title = "Copy the visible (filtered) log to the clipboard";
+    copyBtn.addEventListener("click", () => {
+      void navigator.clipboard?.writeText(visibleLines().join("\n"));
+    });
+    const clearBtn = document.createElement("button");
+    clearBtn.type = "button";
+    clearBtn.className = "sl-logclear";
+    clearBtn.textContent = "Clear";
+    clearBtn.title = "Drop the retained log entries (cosmetic - no game state changes)";
+    clearBtn.addEventListener("click", () => {
+      clear();
+      render(true);
+    });
+    bar.append(copyBtn, clearBtn);
+    el.append(head2, bar, body);
+    return { render };
+  };
+  const flowLog = buildLogPanel(
+    "flow",
+    "Log",
+    () => live().log(),
+    () => live().clearLog(),
+    "(empty - new Engine(bundle, { log: true }) retains the flow log)"
+  );
+  const runLog = buildLogPanel(
+    "run",
+    "Run log (every flow)",
+    () => engine.log(),
+    () => engine.clearLog(),
+    "(empty - new Engine(bundle, { log: true }) retains the run log)"
+  );
+  const renderLog = (force = false) => {
+    runLog.render(force);
+    flowLog.render(force);
+  };
+  const line2 = (parent, text) => {
+    const div = document.createElement("div");
+    div.className = "sl-line";
+    div.textContent = text;
+    parent.append(div);
+  };
+  const readLive = () => {
+    turnsBody.textContent = "";
+    for (const box of live().listBoxes()) {
+      line2(turnsBody, `${box.title ?? box.gameId}: turn ${box.turn}`);
+    }
+    boardBody.textContent = "";
+    for (const [hand, cards] of Object.entries(live().board())) {
+      const names = cards.map((c) => c.title ?? c.gameId);
+      line2(boardBody, `${hand}: ${names.length > 0 ? names.join(", ") : "(empty)"}`);
+    }
+  };
+  const refresh = () => {
+    for (const e of editors) e.read();
+    readLive();
+    renderLog();
+  };
+  readLive();
+  renderLog(true);
+  let timer;
+  const pollMs = opts.pollMs ?? 250;
+  if (pollMs > 0) timer = setInterval(refresh, pollMs);
+  (opts.container ?? document.body).append(el);
+  return {
+    el,
+    refresh,
+    destroy() {
+      if (timer !== void 0) clearInterval(timer);
+      el.remove();
+    }
+  };
+}
+function buildRow(live, row, editors) {
+  const div = document.createElement("div");
+  div.className = "sl-row";
+  const name = document.createElement("span");
+  name.className = "sl-name";
+  name.textContent = row.name;
+  name.title = row.path;
+  const current = () => {
+    try {
+      return live().getProperty(row.path);
+    } catch {
+      return void 0;
+    }
+  };
+  let sync = () => {
+  };
+  const commit = (value) => {
+    live().setProperty(row.path, value);
+    sync();
+  };
+  const reset = document.createElement("button");
+  reset.type = "button";
+  reset.className = "sl-reset";
+  reset.textContent = "\u21BA";
+  reset.title = "Reset to default";
+  reset.addEventListener("click", () => commit(row.default));
+  let widget;
+  let read;
+  const focused = (w) => document.activeElement === w;
+  switch (row.type) {
+    case "boolean": {
+      const input = document.createElement("input");
+      input.type = "checkbox";
+      input.addEventListener("change", () => commit(input.checked));
+      widget = input;
+      read = () => {
+        if (!focused(input)) input.checked = current() === true;
+      };
+      break;
+    }
+    case "number": {
+      const input = document.createElement("input");
+      input.type = "number";
+      input.addEventListener("change", () => commit(Number(input.value)));
+      widget = input;
+      read = () => {
+        if (!focused(input)) input.value = String(current() ?? 0);
+      };
+      break;
+    }
+    case "enum":
+    case "quality": {
+      const select = document.createElement("select");
+      for (const v of (row.type === "quality" ? row.stages : row.values) ?? []) {
+        const o = document.createElement("option");
+        o.value = v;
+        o.textContent = v;
+        select.append(o);
+      }
+      select.addEventListener("change", () => commit(select.value));
+      widget = select;
+      read = () => {
+        if (!focused(select)) select.value = String(current() ?? "");
+      };
+      break;
+    }
+    case "flags": {
+      const input = document.createElement("input");
+      input.type = "text";
+      input.placeholder = "comma, separated, flags";
+      input.addEventListener("change", () => commit(input.value.split(",").map((s) => s.trim()).filter((s) => s.length > 0)));
+      widget = input;
+      read = () => {
+        if (!focused(input)) input.value = (current() ?? []).join(", ");
+      };
+      break;
+    }
+    default: {
+      const input = document.createElement("input");
+      input.type = "text";
+      input.addEventListener("change", () => commit(input.value));
+      widget = input;
+      read = () => {
+        if (!focused(input)) input.value = String(current() ?? "");
+      };
+    }
+  }
+  const readAll = () => {
+    read();
+    reset.disabled = eq(current(), row.default);
+  };
+  sync = readAll;
+  readAll();
+  editors.push({ row, read: readAll });
+  div.append(name, widget, reset);
+  return div;
+}
+
+// src/bundle-inspector.ts
+import { describeBundle } from "@storylet-studio/runtime";
+var showVal2 = (v) => v === void 0 ? "<unset>" : JSON.stringify(v);
+function formatPropertySummary(p) {
+  const options = p.values !== void 0 && p.values.length > 0 ? ` [${p.values.join(", ")}]` : "";
+  return `${p.name}: ${p.type} = ${showVal2(p.default)}${options}`;
+}
+function formatScopeLabel(scope) {
+  if (scope.scope === "world" || scope.scope === "story") return scope.scope;
+  const group = scope.group !== void 0 ? ` (${scope.group})` : "";
+  return `${scope.scope} ${scope.owner}${group}`;
+}
+var line = (parent, text, cls = "sl-line") => {
+  const div = document.createElement("div");
+  div.className = cls;
+  div.textContent = text;
+  parent.append(div);
+  return div;
+};
+var fold = (parent, label, open) => {
+  const details = document.createElement("details");
+  details.className = "sl-fold";
+  details.open = open;
+  const summary = document.createElement("summary");
+  summary.textContent = label;
+  details.append(summary);
+  const body = document.createElement("div");
+  details.append(body);
+  parent.append(details);
+  return body;
+};
+function createBundleInspector(bundle, opts = {}) {
+  ensureInspectorStyle();
+  const description = describeBundle(bundle);
+  const open = opts.open ?? true;
+  const el = document.createElement("div");
+  el.className = "sl-insp";
+  const head = document.createElement("div");
+  head.className = "sl-head";
+  const h = document.createElement("h3");
+  h.textContent = opts.title ?? "Bundle";
+  head.append(h);
+  el.append(head);
+  const { identity, totals } = description;
+  const ident = document.createElement("div");
+  ident.className = "sl-ident";
+  el.append(ident);
+  line(ident, `${identity.project} ${identity.version}`, "sl-line");
+  line(ident, `schema ${identity.schema}`, "sl-line sl-note");
+  line(
+    ident,
+    `hash ${identity.hash === "" ? "(none)" : identity.hash} - metadata ${identity.metadata}`,
+    "sl-line sl-note"
+  );
+  const handsBody = fold(el, "Hands (deal)", open);
+  handsBody.className = "sl-hands";
+  if (description.hands.length === 0) {
+    line(handsBody, "(no hands - this bundle is peek-only)", "sl-line sl-note");
+  }
+  for (const hand of description.hands) {
+    const template = hand.template !== void 0 ? `, template ${hand.template}` : "";
+    line(handsBody, `${hand.gameId}: box ${hand.box}, slots ${hand.slots}${template}` + (hand.title !== void 0 ? ` - ${hand.title}` : ""));
+  }
+  const tagsBody = fold(el, "Tags by box (peek criteria)", open);
+  tagsBody.className = "sl-tags";
+  for (const box of description.boxes) {
+    line(tagsBody, `${box.title ?? box.gameId}`, "sl-group");
+    if (box.tagGroups.length === 0) {
+      line(tagsBody, "  (no tag groups)", "sl-line sl-note");
+    }
+    for (const group of box.tagGroups) {
+      line(tagsBody, `  ${group.gameId}: ${group.tags.length > 0 ? group.tags.join(", ") : "(no tags)"}`);
+    }
+  }
+  const propsBody = fold(el, "Properties (declared)", open);
+  propsBody.className = "sl-props";
+  for (const scope of description.properties) {
+    line(propsBody, formatScopeLabel(scope), "sl-group");
+    if (scope.properties.length === 0) {
+      line(propsBody, "  (none declared)", "sl-line sl-note");
+    }
+    for (const p of scope.properties) {
+      line(propsBody, `  ${formatPropertySummary(p)}`);
+    }
+  }
+  if (description.maps.length > 0) {
+    const mapsBody = fold(el, "Maps (carried, not read)", open);
+    mapsBody.className = "sl-maps";
+    line(mapsBody, "Geometry the build was asked to carry. The engine ignores it.", "sl-line sl-note");
+    for (const map of description.maps) {
+      line(mapsBody, `${map.box} - ${map.group}: zones ${map.zones}, pictures ${map.backgrounds}`);
+    }
+  }
+  const countsBody = fold(el, "Counts", open);
+  countsBody.className = "sl-counts";
+  line(countsBody, `boxes ${totals.boxes} - decks ${totals.decks} - cards ${totals.cards}`);
+  line(countsBody, `hands ${totals.hands} - templates ${totals.templates} - tag groups ${totals.tagGroups}`);
+  for (const box of description.boxes) {
+    line(countsBody, `${box.gameId}: decks ${box.counts.decks}, cards ${box.counts.cards}, hands ${box.counts.hands}, templates ${box.counts.templates}, tag groups ${box.counts.tagGroups}, ranking.specificity ${box.ranking.specificity}`);
+  }
+  (opts.container ?? document.body).append(el);
+  return {
+    el,
+    description,
+    destroy() {
+      el.remove();
+    }
+  };
+}
+
+// src/live-link.ts
+var OPEN = 1;
+var QUEUE_CAP = 512;
+var DEFAULT_URL = "ws://127.0.0.1:4472";
+var BOARD_EVENTS = /* @__PURE__ */ new Set(["deal", "play", "evict", "turns"]);
+function boardFrame(flow) {
+  const id = flow.id;
+  const hands = {};
+  for (const [hand, cards] of Object.entries(flow.board())) hands[hand] = cards.map((c) => c.gameId);
+  const turns = {};
+  for (const box of flow.listBoxes()) turns[box.gameId] = box.turn;
+  return { t: "board", flow: id, hands, turns };
+}
+function createLiveLink(opts) {
+  const url = opts.url ?? DEFAULT_URL;
+  const Ctor = opts.WebSocket ?? globalThis.WebSocket;
+  let queue = [];
+  let sock = null;
+  let closed = false;
+  let build = opts.build;
+  let engine = null;
+  let unsubscribe = null;
+  let announced = /* @__PURE__ */ new Set();
+  if (!Ctor) {
+    return { attach() {
+    }, detach() {
+    }, setBuild() {
+    }, close() {
+      closed = true;
+    } };
+  }
+  const flush = () => {
+    if (!sock || sock.readyState !== OPEN) return;
+    for (const m of queue) {
+      try {
+        sock.send(m);
+      } catch {
+      }
+    }
+    queue = [];
+  };
+  const post = (frame) => {
+    if (closed) return;
+    queue.push(JSON.stringify(frame));
+    if (queue.length > QUEUE_CAP) queue.splice(0, queue.length - QUEUE_CAP);
+    flush();
+  };
+  const liveFlows = () => {
+    try {
+      return engine ? engine.flows() : [];
+    } catch {
+      return [];
+    }
+  };
+  const sendHello = () => {
+    const flows = liveFlows();
+    const hello = { t: "hello", v: 2, build, flows: flows.map((f) => f.id) };
+    if (opts.project !== void 0) hello.project = opts.project;
+    const first = flows[0];
+    if (first) {
+      try {
+        hello.boxes = first.listBoxes().map((b) => b.gameId);
+      } catch {
+      }
+    }
+    announced = new Set(flows.map((f) => f.id));
+    try {
+      sock?.send(JSON.stringify(hello));
+    } catch {
+    }
+  };
+  const postBoard = (flow) => {
+    try {
+      post(boardFrame(flow));
+    } catch {
+    }
+  };
+  const syncFlows = () => {
+    const now = liveFlows();
+    const ids = new Set(now.map((f) => f.id));
+    for (const f of now) {
+      if (announced.has(f.id)) continue;
+      announced.add(f.id);
+      post({ t: "flowOpen", flow: f.id });
+      postBoard(f);
+    }
+    for (const id of [...announced]) {
+      if (ids.has(id)) continue;
+      announced.delete(id);
+      post({ t: "flowClose", flow: id });
+    }
+  };
+  const onTrace = (flowId, event) => {
+    try {
+      syncFlows();
+      post({ t: "trace", flow: flowId, event });
+      if (BOARD_EVENTS.has(event.type)) {
+        const f = engine?.getFlow(flowId);
+        if (f) postBoard(f);
+      }
+    } 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;
+      closed = true;
+      queue = [];
+    });
+  } catch {
+    sock = null;
+    closed = true;
+  }
+  const detach = () => {
+    unsubscribe?.();
+    unsubscribe = null;
+    engine = null;
+    announced = /* @__PURE__ */ new Set();
+  };
+  return {
+    attach(next) {
+      if (closed) return;
+      detach();
+      engine = next;
+      try {
+        unsubscribe = next.subscribeTrace(onTrace);
+      } catch {
+        engine = null;
+        return;
+      }
+      announced = new Set(liveFlows().map((f) => f.id));
+      for (const f of liveFlows()) postBoard(f);
+    },
+    detach,
+    setBuild(next) {
+      if (closed || next === build) return;
+      build = next;
+      if (sock && sock.readyState === OPEN) {
+        sendHello();
+        for (const f of liveFlows()) postBoard(f);
+      }
+    },
+    close() {
+      closed = true;
+      detach();
+      queue = [];
+      try {
+        sock?.close();
+      } catch {
+      }
+      sock = null;
+    }
+  };
+}
+
+// src/refresh.ts
+import { Engine } from "@storylet-studio/runtime";
+function applyLiveBundle(engine, bundleJson, opts = {}) {
+  let bundle;
+  try {
+    bundle = JSON.parse(bundleJson);
+  } catch {
+    return { ok: false, error: "pushed bundle is not valid JSON" };
+  }
+  try {
+    const next = new Engine(bundle, opts);
+    next.loadGame(engine.saveGame());
+    return { ok: true, engine: next, bundle };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+// src/world.ts
+function createWorldContainer(bundle) {
+  const bag = new PropertyBag(bundle.world.properties, { normalise: (n) => n });
+  return {
+    resolver: {
+      get: (n) => bag.get(n),
+      set: (n, v) => {
+        bag.set(n, v);
+      }
+    },
+    bag,
+    values: () => bag.values,
+    load: (values) => bag.load(values)
+  };
+}
+export {
+  applyLiveBundle,
+  boardFrame,
+  createBundleInspector,
+  createStateLogger as createKernelStateLogger,
+  createLiveLink,
+  createPropertyInspector,
+  createStateLogger2 as createStateLogger,
+  createWorldContainer,
+  deserializeState,
+  diffState,
+  ensureInspectorStyle,
+  formatLogEntry,
+  formatPropertySummary,
+  formatScopeLabel,
+  loadState,
+  saveState,
+  serializeState,
+  snapshotState
+};
+//# sourceMappingURL=index.js.map