@patterkit/runtime 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, LogMount, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
 import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
 export { Bundle } from '@patterkit/model';
@@ -569,6 +569,18 @@ declare class Engine {
     getFlow(id: string): Flow | undefined;
     /** All currently-open flows. */
     flows(): Flow[];
+    /**
+     * The SHARED kernel bags with the path each answers to in a log: the `@patter` globals,
+     * and one per scene for the shared `@scene` props. Parity with the Storylet Engine's
+     * listBags of the same name - it is what a state logger mounts.
+     *
+     * A stage bag's log path is `@scene:<sceneId>.`, not the bag's own `@scene.`: a property
+     * is ADDRESSED relative to a flow's current scene, but a log spans scenes and has to say
+     * which one. That is why a mount may override the bag's prefix.
+     *
+     * loadGame() replaces every bag, so re-enumerate after a load.
+     */
+    listBags(): LogMount[];
     /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
      *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
     closeFlow(id: string): void;
@@ -702,7 +714,12 @@ declare class Flow {
      * to its caller (call-return) or ends the flow.
      */
     private settle;
-    /** The options of a pending choice (empty when not at a choice point). */
+    /**
+     * THIS flow's own kernel bags: its not-shared `@patter` half and its per-scene `@scene`
+     * props, each prefixed with the flow id so one path space holds every flow. The shared
+     * halves are the Engine's listBags.
+     */
+    listBags(): LogMount[];
     /** This flow's decisions, in order. Empty unless the run was opened with `log: true`.
      *  The engine's log carries the same events tagged with the flow; this one is what a
      *  single conversation reads as. */
@@ -712,6 +729,7 @@ declare class Flow {
     /** Record one decision, on this flow's log and the engine's. Cheap to call with logging
      *  off: the entry is never built. */
     private emit;
+    /** The options of a pending choice (empty when not at a choice point). */
     getChoices(): ChoiceOption[];
     /** Pick an eligible option by id; the next `advance()` runs it. */
     choose(id: string): void;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ScalarValue } from '@wildwinter/expr';
-import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, PropertyRow } from '@wildwinter/scoperegistry';
+import { ScopeResolver, ScopeRegistry, ScopeDeclaration, PropertyBag, LogMount, PropertyRow } from '@wildwinter/scoperegistry';
 export { PropertyRow } from '@wildwinter/scoperegistry';
 import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
 export { Bundle } from '@patterkit/model';
@@ -569,6 +569,18 @@ declare class Engine {
     getFlow(id: string): Flow | undefined;
     /** All currently-open flows. */
     flows(): Flow[];
+    /**
+     * The SHARED kernel bags with the path each answers to in a log: the `@patter` globals,
+     * and one per scene for the shared `@scene` props. Parity with the Storylet Engine's
+     * listBags of the same name - it is what a state logger mounts.
+     *
+     * A stage bag's log path is `@scene:<sceneId>.`, not the bag's own `@scene.`: a property
+     * is ADDRESSED relative to a flow's current scene, but a log spans scenes and has to say
+     * which one. That is why a mount may override the bag's prefix.
+     *
+     * loadGame() replaces every bag, so re-enumerate after a load.
+     */
+    listBags(): LogMount[];
     /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
      *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
     closeFlow(id: string): void;
@@ -702,7 +714,12 @@ declare class Flow {
      * to its caller (call-return) or ends the flow.
      */
     private settle;
-    /** The options of a pending choice (empty when not at a choice point). */
+    /**
+     * THIS flow's own kernel bags: its not-shared `@patter` half and its per-scene `@scene`
+     * props, each prefixed with the flow id so one path space holds every flow. The shared
+     * halves are the Engine's listBags.
+     */
+    listBags(): LogMount[];
     /** This flow's decisions, in order. Empty unless the run was opened with `log: true`.
      *  The engine's log carries the same events tagged with the flow; this one is what a
      *  single conversation reads as. */
@@ -712,6 +729,7 @@ declare class Flow {
     /** Record one decision, on this flow's log and the engine's. Cheap to call with logging
      *  off: the entry is never built. */
     private emit;
+    /** The options of a pending choice (empty when not at a choice point). */
     getChoices(): ChoiceOption[];
     /** Pick an eligible option by id; the next `advance()` runs it. */
     choose(id: string): void;

package/dist/index.js

@@ -463,6 +463,22 @@ var Engine = class _Engine {
   flows() {
     return [...this.flowsById.values()];
   }
+  /**
+   * The SHARED kernel bags with the path each answers to in a log: the `@patter` globals,
+   * and one per scene for the shared `@scene` props. Parity with the Storylet Engine's
+   * listBags of the same name - it is what a state logger mounts.
+   *
+   * A stage bag's log path is `@scene:<sceneId>.`, not the bag's own `@scene.`: a property
+   * is ADDRESSED relative to a flow's current scene, but a log spans scenes and has to say
+   * which one. That is why a mount may override the bag's prefix.
+   *
+   * loadGame() replaces every bag, so re-enumerate after a load.
+   */
+  listBags() {
+    const mounts = [{ bag: this.host.shared.ownedBag("patter") }];
+    for (const [sceneId, bag] of this.host.stageBags) mounts.push({ bag, pathPrefix: `@scene:${sceneId}.` });
+    return mounts;
+  }
   /** Close (remove) a flow. The flow object is FINISHED, not merely unregistered, so a host still
    *  holding it cannot keep advancing it into the shared world (see {@link Flow.close}). */
   closeFlow(id) {
@@ -902,7 +918,16 @@ var Flow = class {
       this.enterChild(children[frame.index++]);
     }
   }
-  /** The options of a pending choice (empty when not at a choice point). */
+  /**
+   * THIS flow's own kernel bags: its not-shared `@patter` half and its per-scene `@scene`
+   * props, each prefixed with the flow id so one path space holds every flow. The shared
+   * halves are the Engine's listBags.
+   */
+  listBags() {
+    const mounts = [{ bag: this.local.ownedBag("patter"), pathPrefix: `${this.id}/@patter.` }];
+    for (const [sceneId, bag] of this.sceneBags) mounts.push({ bag, pathPrefix: `${this.id}/@scene:${sceneId}.` });
+    return mounts;
+  }
   /** This flow's decisions, in order. Empty unless the run was opened with `log: true`.
    *  The engine's log carries the same events tagged with the flow; this one is what a
    *  single conversation reads as. */
@@ -921,6 +946,7 @@ var Flow = class {
     if (!this.host.logEnabled) return;
     this.flowLog.push({ ...event, seq: this.flowSeq++, ...scene ? { scene } : {} });
   }
+  /** The options of a pending choice (empty when not at a choice point). */
   getChoices() {
     return this.pendingChoice?.options ?? [];
   }