narraleaf-react 0.18.0 → 0.19.1

package/dist/game/nlcore/action/stackModel.d.ts

@@ -64,7 +64,13 @@ export type StackModelRawData = {
 /**
  * One frame of a read-only {@link StackModel.snapshot} — an action currently on the execution
  * stack. A frame that is a concurrent group ({@link Control.all}/{@link Control.any}) also lists
- * its branches (each a top-to-bottom frame list).
+ * its branches, each a whole {@link StackSnapshot}.
+ *
+ * `branches` used to be `StackFrameSnapshot[][]` — only each branch's `frames`. That silently threw
+ * away everything a nested stack knows about ITSELF: a `Control.repeat` runs as a nested StackModel,
+ * so its `loop` counter lived on a snapshot whose frames were kept and whose `loop` and `tag` were
+ * dropped on the way out. The counter was therefore unreachable from `getStackSnapshot()` no matter
+ * how a caller asked, which is exactly what a debug view most wants to show.
  *
  * **Experimental / read-only.** For tooling (Studio's call-stack view). The exact shape is not a
  * stable contract and may change; do not serialize it or drive game logic from it.
@@ -73,7 +79,7 @@ export type StackFrameSnapshot = {
     actionId: string | null;
     actionType: string | null;
     branchWaitType?: StackModelWaiting["type"];
-    branches?: StackFrameSnapshot[][];
+    branches?: StackSnapshot[];
 };
 /**
  * Read-only view of a StackModel's execution stack. `frames` are ordered top-first (the frame

package/dist/game/nlcore/common/game.d.ts

@@ -3,8 +3,9 @@ import { GameState } from "../../player/gameState";
 import { Storable, Namespace } from "../elements/persistent/storable";
 import { LiveGame } from "../game/liveGame";
 import { Preference } from "../game/preference";
+import type { StorableChange, StorableRestore } from "../elements/persistent/storable";
 import type { SavedGame } from "../gameTypes";
 import type { StackSnapshot, StackFrameSnapshot } from "../action/stackModel";
 import { KeyMap } from "../game/keyMap";
 export { LiveGame, GameState, Game, Storable, Namespace, Preference, KeyMap, };
-export type { SavedGame, StackSnapshot, StackFrameSnapshot, };
+export type { SavedGame, StackSnapshot, StackFrameSnapshot, StorableChange, StorableRestore, };

package/dist/game/nlcore/elements/persistent/storable.d.ts

@@ -1,4 +1,31 @@
-import { NameSpaceContent } from "../../elements/persistent/type";
+import { NameSpaceContent, StorableType } from "../../elements/persistent/type";
+import { EventDispatcher, EventToken } from "../../../../util/data";
+/**
+ * One stored value changing. Reported by {@link Storable.onChange} after the new value is
+ * already readable through `getNamespace(namespace).get(key)`.
+ */
+export type StorableChange<T extends StorableType = any> = {
+    /**
+     * The key the namespace is registered under in the {@link Storable} — the same string
+     * {@link Storable.getNamespace} takes, and the one a save file carries. For a namespace
+     * declared with `new Persistent("player", ...)` this is `"persistent:player"`.
+     */
+    namespace: string;
+    key: string;
+    /** The value that was there. `undefined` if the key had never been written. */
+    previous: T | undefined;
+    /** The value that is there now. `undefined` if the key was dropped (see {@link Namespace.reset}). */
+    next: T | undefined;
+};
+/**
+ * A bulk value application — a save being loaded, or a namespace being rewound to a
+ * snapshot. Reported by {@link Storable.onRestore} *instead of* per-key changes; see the
+ * note on {@link Namespace.deserialize}.
+ */
+export type StorableRestore = {
+    /** The namespace keys whose contents were replaced. */
+    namespaces: string[];
+};
 export declare class Namespace<T extends NameSpaceContent<keyof T>> {
     static isSerializable(value: any): boolean;
     name: string;
@@ -11,10 +38,25 @@ export declare class Namespace<T extends NameSpaceContent<keyof T>> {
     keys(): (keyof T)[];
     values(): T[keyof T][];
     entries(): [keyof T, T[keyof T]][];
+    /**
+     * Restore the author's defaults.
+     *
+     * Reports one change per key that actually moved. A key written after construction is
+     * not in the defaults, so it is dropped and reported as changing to `undefined`.
+     */
     reset(): this;
 }
 export declare class Storable {
+    static EventTypes: {
+        readonly "event:storable.change": "event:storable.change";
+        readonly "event:storable.restore": "event:storable.restore";
+    };
     static createNamespace<T extends NameSpaceContent<keyof T>>(name: string, initContent: T, key?: string): Namespace<T>;
+    /**
+     * Changes to any value in any registered namespace. Prefer {@link Storable.onChange},
+     * which filters by namespace and key.
+     */
+    readonly events: EventDispatcher<StorableEvents>;
     addNamespace<T extends NameSpaceContent<keyof T>>(namespace: Namespace<T>): this | undefined;
     getNamespace<T extends NameSpaceContent<keyof T> = any>(key: string): Namespace<T>;
     setNamespace<T extends NameSpaceContent<keyof T> = any>(key: string, namespace: Namespace<T>): this;
@@ -26,4 +68,45 @@ export declare class Storable {
     keys(): string[];
     values(): Namespace<any>[];
     entries(): [string, Namespace<any>][];
+    /**
+     * Listen for a stored value changing.
+     *
+     * The listener runs after the new value is readable, and only when the value actually
+     * moved — writing a value equal to the one already there reports nothing, so a line that
+     * re-asserts a flag every time it runs does not wake anything up. Equality is structural,
+     * so rebuilding an object with the same contents is also a no-op.
+     *
+     * Loading a save does not report changes; see {@link Storable.onRestore}.
+     *
+     * Subscriptions outlive the namespaces they watch: `newGame()` and loading a save both
+     * rebuild every namespace from scratch, and a listener registered here survives that.
+     *
+     * @example
+     * ```ts
+     * // every change, anywhere
+     * liveGame.getStorable().onChange(({namespace, key, previous, next}) => {...});
+     *
+     * // one namespace
+     * liveGame.getStorable().onChange("persistent:player", ({key, next}) => {...});
+     *
+     * // one key
+     * liveGame.getStorable().onChange("persistent:player", "gold", ({next}) => {
+     *     if (next === 100) {...}
+     * });
+     * ```
+     * @returns a token whose `cancel()` removes the listener
+     */
+    onChange(listener: (change: StorableChange) => void): EventToken;
+    onChange(namespace: string, listener: (change: StorableChange) => void): EventToken;
+    onChange(namespace: string, key: string, listener: (change: StorableChange) => void): EventToken;
+    /**
+     * Listen for the store being replaced wholesale — loading a save, or rewinding a
+     * namespace to a snapshot. Fires once per bulk application, naming the namespaces
+     * involved, instead of the changes it implies.
+     *
+     * Re-read whatever you derive from the store when this fires.
+     *
+     * @returns a token whose `cancel()` removes the listener
+     */
+    onRestore(listener: (restore: StorableRestore) => void): EventToken;
 }