@storylet-studio/play-helpers 0.8.1 → 0.8.2

package/dist/index.d.cts

@@ -2,6 +2,7 @@ import { Engine, Flow, LogEntry, EngineLogEntry, BundleDescription, PropertySumm
 import { StateLoggerOptions, StateLogger, StateSnapshot, PropertyBag as PropertyBag$1 } from '@wildwinter/scoperegistry';
 export { StateChange, StateLogger, StateLoggerAdapter, StateLoggerOptions, StateSnapshot, createStateLogger as createKernelStateLogger, diffState } from '@wildwinter/scoperegistry';
 import { PropertyBag, SaveFile, Bundle } from '@storylet-studio/model';
+import { ScopeResolver } from '@wildwinter/expr';
 
 /** The full flattened snapshot of ONE FLOW's view - the shared partitions
  *  plus that flow's own - plus its turns / cooldowns / board. @world is not
@@ -224,24 +225,6 @@ type LiveBundleResult =
  */
 declare function applyLiveBundle(engine: Engine, bundleJson: string, opts?: EngineOptions): LiveBundleResult;
 
-type ScalarValue = boolean | number | string | string[];
-
-/**
- * A scope backed by a host resolver rather than a static bag - the basis for
- * *foreign* scopes (e.g. `@game` / `@world`) whose values live in a host or
- * another engine and are read (and optionally written) at runtime. The
- * evaluator treats a missing property the same as a bag does (the scope's
- * missing-policy decides false-vs-throw). A scope entirely absent from the
- * EvalContext still resolves to false regardless.
- */
-interface ScopeResolver {
-    /** Read a property's value, or undefined if the scope does not have it. */
-    get(name: string): ScalarValue | undefined;
-    /** Write a property (omit for a read-only scope). The core never calls this;
-     *  it is for host/runtime effect application (e.g. a state container's `set`). */
-    set?(name: string, value: ScalarValue): void;
-}
-
 interface WorldContainer {
     /** Pass as `new Engine(bundle, { world: container.resolver })`. */
     resolver: ScopeResolver;

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Engine, Flow, LogEntry, EngineLogEntry, BundleDescription, PropertySumm
 import { StateLoggerOptions, StateLogger, StateSnapshot, PropertyBag as PropertyBag$1 } from '@wildwinter/scoperegistry';
 export { StateChange, StateLogger, StateLoggerAdapter, StateLoggerOptions, StateSnapshot, createStateLogger as createKernelStateLogger, diffState } from '@wildwinter/scoperegistry';
 import { PropertyBag, SaveFile, Bundle } from '@storylet-studio/model';
+import { ScopeResolver } from '@wildwinter/expr';
 
 /** The full flattened snapshot of ONE FLOW's view - the shared partitions
  *  plus that flow's own - plus its turns / cooldowns / board. @world is not
@@ -224,24 +225,6 @@ type LiveBundleResult =
  */
 declare function applyLiveBundle(engine: Engine, bundleJson: string, opts?: EngineOptions): LiveBundleResult;
 
-type ScalarValue = boolean | number | string | string[];
-
-/**
- * A scope backed by a host resolver rather than a static bag - the basis for
- * *foreign* scopes (e.g. `@game` / `@world`) whose values live in a host or
- * another engine and are read (and optionally written) at runtime. The
- * evaluator treats a missing property the same as a bag does (the scope's
- * missing-policy decides false-vs-throw). A scope entirely absent from the
- * EvalContext still resolves to false regardless.
- */
-interface ScopeResolver {
-    /** Read a property's value, or undefined if the scope does not have it. */
-    get(name: string): ScalarValue | undefined;
-    /** Write a property (omit for a read-only scope). The core never calls this;
-     *  it is for host/runtime effect application (e.g. a state container's `set`). */
-    set?(name: string, value: ScalarValue): void;
-}
-
 interface WorldContainer {
     /** Pass as `new Engine(bundle, { world: container.resolver })`. */
     resolver: ScopeResolver;

package/dist/index.js

@@ -1,215 +1,8 @@
-// ../../../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)];
-  }
-  /** A name as this bag keys it: its normalisation policy applied. The registry
-   *  uses it to key quality ladders and the validation schema the bag's own way,
-   *  so a case-significant (identity) bag is not quietly folded to lower case
-   *  one layer up. */
-  normalise(name) {
-    return 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 unless the caller says it is the
-   *  HOST (`host: true`), for whom `writable: false` was never a rule - it is
-   *  the story's promise, not the game's. `silent` and `host` are separate on
-   *  purpose: one is about who hears the write, the other about who may make
-   *  it. Returns the change. */
-  set(name, value, opts) {
-    const n = this.norm(name);
-    if (!opts?.host && 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
+import {
+  createStateLogger as createKernelStateLogger,
+  diffState
+} from "@wildwinter/scoperegistry";
 function snapshotState(engine, flow) {
   const out = {};
   for (const { bag } of [...engine.listBags(), ...flow.listBags()]) {
@@ -228,10 +21,10 @@ function extraState(saved) {
   for (const [handId, cards] of Object.entries(saved.board)) out[`board:${handId}`] = [...cards];
   return out;
 }
-function createStateLogger2(engine, flow, opts = {}) {
+function createStateLogger(engine, flow, opts = {}) {
   const id = flow.id;
   const live = () => engine.getFlow(id);
-  return createStateLogger({
+  return createKernelStateLogger({
     // 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.
@@ -240,12 +33,8 @@ function createStateLogger2(engine, flow, opts = {}) {
   }, opts);
 }
 
-// ../model/src/index.ts
-var SAVE_SCHEMA = "storylets/save@2";
-var SAVE_SCHEMA_V1 = "storylets/save@1";
-var SAVEFILE_SCHEMA = "storylets/savefile@1";
-
 // src/save.ts
+import { SAVEFILE_SCHEMA, SAVE_SCHEMA, SAVE_SCHEMA_V1 } from "@storylet-studio/model";
 function serializeState(engine, world) {
   return JSON.stringify(saveState(engine, world), null, 2);
 }
@@ -435,9 +224,9 @@ function createPropertyInspector(engine, flow, opts = {}) {
     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;
+        const show = q === "" || row.text.includes(q);
+        row.el.style.display = show ? "" : "none";
+        any = any || show;
       }
       group.el.style.display = any ? "" : "none";
     }
@@ -970,8 +759,9 @@ function applyLiveBundle(engine, bundleJson, opts = {}) {
 }
 
 // src/world.ts
+import { PropertyBag as StateBag } from "@wildwinter/scoperegistry";
 function createWorldContainer(bundle) {
-  const bag = new PropertyBag(bundle.world.properties, { normalise: (n) => n });
+  const bag = new StateBag(bundle.world.properties, { normalise: (n) => n });
   return {
     resolver: {
       get: (n) => bag.get(n),
@@ -988,10 +778,10 @@ export {
   applyLiveBundle,
   boardFrame,
   createBundleInspector,
-  createStateLogger as createKernelStateLogger,
+  createKernelStateLogger,
   createLiveLink,
   createPropertyInspector,
-  createStateLogger2 as createStateLogger,
+  createStateLogger,
   createWorldContainer,
   deserializeState,
   diffState,