@storylet-studio/play-helpers 0.4.1 → 0.5.0

package/dist/index.d.cts

@@ -4,10 +4,17 @@ export { StateChange, StateLogger, StateLoggerAdapter, StateLoggerOptions, State
 import { PropertyBag, SaveFile, Bundle } from '@storylet-studio/model';
 
 /** The full flattened snapshot of ONE FLOW's view - the shared partitions
- *  plus that flow's own - straight off the save envelope, so "what the
- *  snapshot sees" is by construction "what a save persists". @world is not
- *  here for the same reason it is not in the envelope: the host owns that
- *  container and mounts/saves it itself (createWorldContainer). */
+ *  plus that flow's own - plus its turns / cooldowns / board. @world is not
+ *  here for the same reason it is not in a save envelope: the host owns that
+ *  container and mounts/saves it itself (createWorldContainer).
+ *
+ *  Taken off the BAGS, which is what a save envelope is made of, rather than
+ *  off the envelope itself. The two used to be interchangeable; from 4.4 they
+ *  are not, because a property ADDRESS names its owner by gameId while the
+ *  envelope stays keyed by internal id (a save has to survive a rename). The
+ *  bags carry the address, so reading them is what keeps this snapshot and
+ *  the live logger's lines in ONE path space - which is the invariant the
+ *  whole diff rests on. */
 declare function snapshotState(engine: Engine, flow: Flow): StateSnapshot;
 /** The storylets state logger: the kernel core mounted on the SHARED bags
  *  (engine.listBags()) and one flow's own (flow.listBags()) - the same
@@ -81,7 +88,10 @@ interface BundleInspector {
     description: BundleDescription;
     destroy(): void;
 }
-/** "name: type = default", plus enum/flags options where declared. */
+/** "name: type = default", plus enum/flags options where declared, plus
+ *  "(durable)" where the declaration says the value outlives a run
+ *  (design/engine-server.md 4.2). Nothing is added for the ordinary
+ *  run-scoped property: that is what a property is. */
 declare function formatPropertySummary(p: PropertySummary): string;
 /** The scope label a declaration block files under ("world", "box box",
  *  "tag docks (zone)"). */
@@ -237,7 +247,11 @@ interface WorldContainer {
     /** Pass as `new Engine(bundle, { world: container.resolver })`. */
     resolver: ScopeResolver;
     /** The kernel bag itself (subscribe, audit, rows live there) - mount it
-     *  into a state logger or examiner beside the engine's own bags. */
+     *  into a state logger or examiner beside the engine's own bags. Writing it
+     *  DIRECTLY is writing the kernel, so a `writable: false` declaration asks
+     *  the kernel's question: pass `{ host: true }` to say the game is speaking
+     *  (`bag.set(name, value, { host: true })`). Through `resolver` or an
+     *  engine's setProperty that is already answered. */
     bag: PropertyBag$1;
     /** The current values, for saving beside the engine's envelope. */
     values(): PropertyBag;
@@ -245,7 +259,26 @@ interface WorldContainer {
      *  declarations keep their defaults - the same drift rule as loadGame. */
     load(values: PropertyBag): void;
 }
-/** A world container seeded from the bundle's @world declarations. */
+/** A world container seeded from the bundle's @world declarations.
+ *
+ *  The container is the GAME's state, so it WRITES - even a declaration
+ *  carrying `writable: false`. That flag is the STORY's promise not to write
+ *  the value (Reboot.md 10), and the engine keeps it where the story writes: an
+ *  outcome is refused against the engine's read-only table before it ever
+ *  reaches this resolver. Enforcing it here as well refused the HOST too - the
+ *  clock the game must move, the harness driving the value it is testing
+ *  against - which is the opposite of what the flag says.
+ *
+ *  So the declarations are seeded AS DECLARED, which is what an examiner over
+ *  this container should read, and the writes go through as HOST writes
+ *  (scoperegistry 0.6.0's `{ host: true }`). The resolver's `set` is the
+ *  engine's own doorway and passes the flag too: the engine has already sorted
+ *  story from host by then - a story write was refused earlier, a host write is
+ *  the only kind that arrives - and a resolver takes a name and a value with no
+ *  room to say which. A game wanting a rule of its own binds its own resolver
+ *  rather than this one; the ports' container (Unreal's UStoryletWorld) draws
+ *  the same line, with HostSet never refused and StorySet asking the game's own
+ *  read-only list. */
 declare function createWorldContainer(bundle: Bundle): WorldContainer;
 
 export { type BundleInspector, type BundleInspectorOptions, type LiveBundleResult, type LiveFrame, type LiveLink, type LiveLinkOptions, type LiveSocketLike, type PropertyInspector, type PropertyInspectorOptions, type WorldContainer, applyLiveBundle, boardFrame, createBundleInspector, createLiveLink, createPropertyInspector, createStateLogger, createWorldContainer, deserializeState, ensureInspectorStyle, formatLogEntry, formatPropertySummary, formatScopeLabel, loadState, saveState, serializeState, snapshotState };

package/dist/index.d.ts

@@ -4,10 +4,17 @@ export { StateChange, StateLogger, StateLoggerAdapter, StateLoggerOptions, State
 import { PropertyBag, SaveFile, Bundle } from '@storylet-studio/model';
 
 /** The full flattened snapshot of ONE FLOW's view - the shared partitions
- *  plus that flow's own - straight off the save envelope, so "what the
- *  snapshot sees" is by construction "what a save persists". @world is not
- *  here for the same reason it is not in the envelope: the host owns that
- *  container and mounts/saves it itself (createWorldContainer). */
+ *  plus that flow's own - plus its turns / cooldowns / board. @world is not
+ *  here for the same reason it is not in a save envelope: the host owns that
+ *  container and mounts/saves it itself (createWorldContainer).
+ *
+ *  Taken off the BAGS, which is what a save envelope is made of, rather than
+ *  off the envelope itself. The two used to be interchangeable; from 4.4 they
+ *  are not, because a property ADDRESS names its owner by gameId while the
+ *  envelope stays keyed by internal id (a save has to survive a rename). The
+ *  bags carry the address, so reading them is what keeps this snapshot and
+ *  the live logger's lines in ONE path space - which is the invariant the
+ *  whole diff rests on. */
 declare function snapshotState(engine: Engine, flow: Flow): StateSnapshot;
 /** The storylets state logger: the kernel core mounted on the SHARED bags
  *  (engine.listBags()) and one flow's own (flow.listBags()) - the same
@@ -81,7 +88,10 @@ interface BundleInspector {
     description: BundleDescription;
     destroy(): void;
 }
-/** "name: type = default", plus enum/flags options where declared. */
+/** "name: type = default", plus enum/flags options where declared, plus
+ *  "(durable)" where the declaration says the value outlives a run
+ *  (design/engine-server.md 4.2). Nothing is added for the ordinary
+ *  run-scoped property: that is what a property is. */
 declare function formatPropertySummary(p: PropertySummary): string;
 /** The scope label a declaration block files under ("world", "box box",
  *  "tag docks (zone)"). */
@@ -237,7 +247,11 @@ interface WorldContainer {
     /** Pass as `new Engine(bundle, { world: container.resolver })`. */
     resolver: ScopeResolver;
     /** The kernel bag itself (subscribe, audit, rows live there) - mount it
-     *  into a state logger or examiner beside the engine's own bags. */
+     *  into a state logger or examiner beside the engine's own bags. Writing it
+     *  DIRECTLY is writing the kernel, so a `writable: false` declaration asks
+     *  the kernel's question: pass `{ host: true }` to say the game is speaking
+     *  (`bag.set(name, value, { host: true })`). Through `resolver` or an
+     *  engine's setProperty that is already answered. */
     bag: PropertyBag$1;
     /** The current values, for saving beside the engine's envelope. */
     values(): PropertyBag;
@@ -245,7 +259,26 @@ interface WorldContainer {
      *  declarations keep their defaults - the same drift rule as loadGame. */
     load(values: PropertyBag): void;
 }
-/** A world container seeded from the bundle's @world declarations. */
+/** A world container seeded from the bundle's @world declarations.
+ *
+ *  The container is the GAME's state, so it WRITES - even a declaration
+ *  carrying `writable: false`. That flag is the STORY's promise not to write
+ *  the value (Reboot.md 10), and the engine keeps it where the story writes: an
+ *  outcome is refused against the engine's read-only table before it ever
+ *  reaches this resolver. Enforcing it here as well refused the HOST too - the
+ *  clock the game must move, the harness driving the value it is testing
+ *  against - which is the opposite of what the flag says.
+ *
+ *  So the declarations are seeded AS DECLARED, which is what an examiner over
+ *  this container should read, and the writes go through as HOST writes
+ *  (scoperegistry 0.6.0's `{ host: true }`). The resolver's `set` is the
+ *  engine's own doorway and passes the flag too: the engine has already sorted
+ *  story from host by then - a story write was refused earlier, a host write is
+ *  the only kind that arrives - and a resolver takes a name and a value with no
+ *  room to say which. A game wanting a rule of its own binds its own resolver
+ *  rather than this one; the ports' container (Unreal's UStoryletWorld) draws
+ *  the same line, with HostSet never refused and StorySet asking the game's own
+ *  read-only list. */
 declare function createWorldContainer(bundle: Bundle): WorldContainer;
 
 export { type BundleInspector, type BundleInspectorOptions, type LiveBundleResult, type LiveFrame, type LiveLink, type LiveLinkOptions, type LiveSocketLike, type PropertyInspector, type PropertyInspectorOptions, type WorldContainer, applyLiveBundle, boardFrame, createBundleInspector, createLiveLink, createPropertyInspector, createStateLogger, createWorldContainer, deserializeState, ensureInspectorStyle, formatLogEntry, formatPropertySummary, formatScopeLabel, loadState, saveState, serializeState, snapshotState };

package/dist/index.js

@@ -95,10 +95,14 @@ var PropertyBag = class _PropertyBag {
   }
   /** 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. */
+   *  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 (this.decls.get(n)?.writable === false) throw new Error(`'${name}' is read-only`);
+    if (!opts?.host && this.decls.get(n)?.writable === false) throw new Error(`'${name}' is read-only`);
     const change = {
       name: n,
       prev: this.values[n],
@@ -200,19 +204,13 @@ function defaultFor(d) {
 
 // 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);
+  for (const { bag } of [...engine.listBags(), ...flow.listBags()]) {
+    for (const row of bag.rows()) {
+      if (row.value !== void 0) out[row.path] = row.value;
+    }
   }
-  Object.assign(out, extraState(env.flows[flow.id]));
+  Object.assign(out, extraState(engine.saveGame().flows[flow.id]));
   return out;
 }
 function extraState(saved) {
@@ -666,7 +664,8 @@ 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}`;
+  const durable = p.durable === true ? " (durable)" : "";
+  return `${p.name}: ${p.type} = ${showVal2(p.default)}${options}${durable}`;
 }
 function formatScopeLabel(scope) {
   if (scope.scope === "world" || scope.scope === "story") return scope.scope;
@@ -722,7 +721,8 @@ function createBundleInspector(bundle, opts = {}) {
   }
   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 moves = hand.movable === void 0 ? "" : `, moves ${hand.movable.map((m) => `${m.group} from ${m.from}`).join(" and ")}`;
+    line(handsBody, `${hand.gameId}: box ${hand.box}, slots ${hand.slots}${template}${moves}` + (hand.title !== void 0 ? ` - ${hand.title}` : ""));
   }
   const tagsBody = fold(el, "Tags by box (peek criteria)", open);
   tagsBody.className = "sl-tags";
@@ -751,7 +751,7 @@ function createBundleInspector(bundle, opts = {}) {
     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}`);
+      line(mapsBody, `${map.box} - ${map.group}: zones ${map.zones}, pictures ${map.backgrounds}, sites ${map.sites}`);
     }
   }
   const countsBody = fold(el, "Counts", open);
@@ -759,7 +759,7 @@ function createBundleInspector(bundle, opts = {}) {
   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}`);
+    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}` + (box.turn !== void 0 ? `, turn = ${box.turn.seconds}s` : "") + (box.durableCards !== void 0 ? `, durable cards ${box.durableCards}` : ""));
   }
   (opts.container ?? document.body).append(el);
   return {
@@ -968,7 +968,7 @@ function createWorldContainer(bundle) {
     resolver: {
       get: (n) => bag.get(n),
       set: (n, v) => {
-        bag.set(n, v);
+        bag.set(n, v, { host: true });
       }
     },
     bag,