narraleaf-react 0.39.0 → 0.39.2

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

@@ -22,6 +22,17 @@ export declare class Action<ContentNodeType = any, Callee = LogicAction.GameElem
     readonly __stack: string;
     constructor(callee: Callee, type: Type, contentNode: ContentNode<ContentNodeType>);
     executeAction(_state: GameState, _injection: ActionExecutionInjection): ExecutedActionResult;
+    /**
+     * Give up whatever this action was still holding, without running it and without going on to
+     * the next one.
+     *
+     * Called on an action that is dropped from an execution stack rather than executed - today
+     * only when a concurrent branch is abandoned (see {@link StackModel.abandon}). Almost every
+     * action holds nothing outside its own stack and so does nothing here; the exception is a
+     * scene call's return address, which is a promise made to a scene that is sitting suspended on
+     * the stage waiting for it.
+     */
+    abandon(_state: GameState): void;
     getId(): string;
     setId(id: string): void;
     getStaticId(): string | null;

package/dist/game/nlcore/action/actions/sceneAction.d.ts

@@ -84,10 +84,24 @@ export declare class SceneAction<T extends typeof SceneActionTypes[keyof typeof
     /** Put back what {@link SceneAction.unwindCallStack} took away, in the order it took it. */
     static rewindCallStack(unwound: [scene: Scene, snapshot: SceneSnapshot][], state: GameState): void;
     exit(state: GameState): void;
+    /**
+     * Give up the call this return address stands for.
+     *
+     * Reached when the stack holding a `scene:resume` is thrown away rather than run to it - a
+     * `Control.any` branch that lost, today. The stage half of `scene:resume` and nothing else: the
+     * scene the call entered leaves, and the scene the call had suspended is running again. What is
+     * deliberately missing is the rest of it - a return address nobody is coming back to has no
+     * next action, and no history entry either, because the branch it was on is not a place a step
+     * back can land.
+     *
+     * Every other scene action holds nothing once it is off the stack, so this is the only override.
+     */
+    abandon(state: GameState): void;
     applyNvlVisibility(gameState: GameState, visible: boolean, options: Partial<TransformDefinitions.CommonTransformProps> | undefined, injection: ActionExecutionInjection): CalledActionResult | Awaitable<CalledActionResult, CalledActionResult>;
     executeAction(gameState: GameState, injection: ActionExecutionInjection): ExecutedActionResult;
     getFutureActions(story: Story, searchOptions?: ActionSearchOptions): LogicAction.Actions[];
     _sceneNotFoundError(sceneId: string): Error;
+    _callerAlreadyParkedError(target: Scene | string): Error;
     getSceneName(scene: Scene | string): string;
     stringify(story: Story, seen: Set<LogicAction.Actions>, _strict: boolean): string;
 }

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

@@ -114,6 +114,14 @@ export declare class StackModel {
     static isStackModelsAwaiting(type: StackModelWaiting["type"], stackModels: StackModel[]): boolean;
     private stack;
     private waitingAction;
+    /**
+     * True only for as long as {@link executeActions} is running {@link waitingAction}.
+     *
+     * `waitingAction` is the last action popped off the stack, and it stays set after that action
+     * has run to completion - so on its own it cannot say whether the action is still the one the
+     * model is on. {@link serialize} needs that distinction and nothing else does.
+     */
+    private executingWaitingAction;
     private loopConfig;
     private loopBodyActions;
     private loopCondition;
@@ -192,9 +200,38 @@ export declare class StackModel {
      * @returns Snapshot that can be passed to StackModel.deserialize.
      */
     serialize(frozen?: boolean): StackModelRawData;
+    /**
+     * Give up everything this stack still holds, unwinding the scene calls it opened on the way.
+     *
+     * {@link reset} clears stacks; it does not put the stage back. A branch cut mid-call is holding
+     * a `scene:resume` - the promise to come back to the scene it suspended - and dropping that
+     * promise without keeping it leaves the caller parked on the stage with nothing able to return
+     * to it, and the called scene mounted with nothing pointing at it. Both are permanent: no later
+     * action names either scene. So the call is given up, innermost first, which is what
+     * `SceneAction.unwindCallStack` does when a plain jump walks away from a call stack.
+     *
+     * Only the call frames are unwound. A scene the branch merely *entered* - what a plain jump
+     * does - belongs to the main stack from the moment the jump re-pointed it at that scene, so it
+     * is the story's scene by then rather than the branch's, and taking it off the stage here would
+     * unload the scene the story is now in.
+     */
+    abandon(): this;
+    /**
+     * Every scene-call return address this stack is holding, innermost first.
+     *
+     * Nested groups are searched too: a branch can itself be running a `Control.all` whose own
+     * branch opened a call, and that call is held just as firmly.
+     */
+    private collectCallFrames;
     reset(): void;
     deserialize(data: StackModelRawData, actionMap: Map<string, LogicAction.Actions>): this;
     isEmpty(): boolean;
+    /**
+     * Whether the top of the stack is a `Control.all` / `Control.any` link whose branches have not
+     * all drained - the one state in which the stack accepts nothing on top of it, because the
+     * group has to finish before whatever queued behind it can run.
+     */
+    private topIsGroupStillRunning;
     /**
      * Drop everything above the innermost scene-call return address, or the whole stack if there
      * is none.

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

@@ -11,6 +11,16 @@ export declare class RGBColor {
     toString(): string;
     toHex(): string;
 }
+/**
+ * The action a {@link RuntimeScriptError} is about, reduced to what a host can put on screen:
+ * which action it was, and what kind of action it was.
+ */
+export type RuntimeScriptErrorAction = {
+    /** The action's id, as {@link Action.getId} reports it. */
+    id: string;
+    /** The action's type, e.g. `scene:preSuspend`. */
+    type: string;
+};
 /**
  * Alias for {@link Word.color}
  */

package/dist/game/player/elements/say/UIDialog.d.ts

@@ -50,6 +50,21 @@ export declare class DialogState {
     isIdle(): boolean;
     setIdle(idle: boolean): void;
     isActive(): boolean;
+    /**
+     * Hand the line to a box, or take it away from one.
+     *
+     * A box that becomes active over a line whose text has already finished revealing is idle at
+     * once. `_idle` is the latch between "there is nothing left to reveal" and "the next advance
+     * settles the line", and the `complete` event that used to be its only source is answered only
+     * by a box that was active at the instant the text finished. A line that finished while its box
+     * was displaced - another scene's dialog on top of it, a panel over the stage, the moment of
+     * retention after the line before it - therefore came back with the latch down, and the first
+     * advance the player spent went on raising it instead of settling the line. The latch now
+     * follows the fact rather than who was watching when it happened.
+     *
+     * A line that has *not* finished revealing is untouched: its box coming back must still reveal
+     * the rest of it before a click can settle it.
+     */
     setActive(active: boolean): this;
     /**
      * Only for dialog component to call

package/dist/game/player/elements/scene/dialogPresentation.d.ts

@@ -0,0 +1,101 @@
+import { PlayerStateElement } from "../../gameState";
+import { DialogAction } from "../say/type";
+/**
+ * How long a dialog box is kept on screen after the line in it has been settled.
+ *
+ * A line is usually replaced by the next one within the same tick, and the grace is what lets that
+ * happen in the same box rather than as an exit followed by an entrance. It is a hold for a line
+ * that is *finished*; see {@link resolveDialogPresentation} for why a line that is still waiting can
+ * never be held this way.
+ */
+export declare const DIRECT_DIALOG_REPLACEMENT_GRACE_MS = 120;
+/**
+ * The presence bookkeeping one scene's dialog layer carries between renders.
+ *
+ * `slotKeys` maps a slot - the index a line has in the scene's `texts` - to the React key of the
+ * box showing it, so a line replaced in place keeps its box. `exitingKeys` are the keys
+ * `AnimatePresence` is still animating out; a slot that is handed one of those has to be given a
+ * fresh key instead, or the new line would be mounted into a box that is on its way off screen.
+ */
+export type DialogPresenceState = {
+    slotKeys: Map<number, string>;
+    exitingKeys: Set<string>;
+    menuPromptIds: WeakMap<PlayerStateElement["menus"][number], string>;
+    nextKey: number;
+};
+export type DialogRenderItem = {
+    action: DialogAction;
+    onFinished?: (skiped?: boolean) => void;
+    useTypeEffect: boolean;
+    presenceKey: string;
+    slot: number;
+    /**
+     * Whether this box is showing a line that is still waiting for the player.
+     *
+     * An inactive box ignores clicks, the advance key and auto-forward: it is a picture of a line
+     * that is already over. Only a retained item is ever inactive.
+     */
+    active: boolean;
+};
+/** One line (or one menu prompt) the scene wants a box for, before a box has been assigned. */
+export type DialogSource = {
+    action: DialogAction;
+    onFinished?: (skiped?: boolean) => void;
+    useTypeEffect: boolean;
+    slot: number;
+};
+export type DialogPresentationInput = {
+    /**
+     * Every line the scene is still waiting on, in slot order - or, when it is waiting on none, the
+     * prompt of a menu it is showing. Empty means the scene has nothing of its own to say.
+     */
+    sources: DialogSource[];
+    /** How many menus the scene is showing. A menu is interactive whether or not it has a prompt. */
+    menuCount: number;
+    /** Mutated: the slot/key bookkeeping this layer carries between renders. */
+    presence: DialogPresenceState;
+    /** The snapshot currently being held on screen, if the grace is running. */
+    retained: DialogRenderItem[] | null;
+    /** The items the last render with something to say produced. */
+    lastActive: DialogRenderItem[];
+    sceneId: string;
+};
+export type DialogPresentation = {
+    /** What to render, in order. */
+    items: DialogRenderItem[];
+    /** The snapshot to keep holding, or null to stop holding one. */
+    retained: DialogRenderItem[] | null;
+    /** The snapshot to remember as the last live one. */
+    lastActive: DialogRenderItem[];
+    /** Whether the retention grace should be counting after this render. */
+    retaining: boolean;
+    /**
+     * Whether this scene's dialog layer should take pointer events.
+     *
+     * A scene's dialog layer covers the whole stage, and every scene on the stage has one -
+     * including a caller parked behind a returnable jump, which has nothing to show at all. The
+     * layers are stacked in the order the scenes are held, so a parked caller's empty layer is
+     * drawn over the box of the scene the story is actually in. A layer with nothing live in it
+     * that still took pointer events therefore swallowed every click aimed at the line underneath:
+     * the box's own click handler, an inline word's, anything a line had drawn over itself.
+     */
+    interactive: boolean;
+};
+/**
+ * Decide what one scene's dialog layer renders this frame.
+ *
+ * Deterministic given its input; it starts no timers and touches no React. `presence` is the one
+ * thing it writes to, because slot/key assignment is bookkeeping that has to survive the render
+ * that made it.
+ *
+ * Two rules the layer is built on:
+ *
+ * - **A line that is still waiting is always live.** Retention describes a line that is over and is
+ *   being held on screen for a moment; a line whose click callback has not been called yet is not
+ *   that, whatever came and went over its box in the meantime. So a snapshot is only ever taken
+ *   when the scene has nothing left to say, and any snapshot in hand is dropped the moment it has
+ *   something again.
+ * - **A layer only takes the pointer when it has something to take it for.** See
+ *   {@link DialogPresentation.interactive}.
+ */
+export declare function resolveDialogPresentation({ sources, menuCount, presence, retained, lastActive, sceneId, }: DialogPresentationInput): DialogPresentation;

package/dist/game/player/gameState.d.ts

@@ -146,6 +146,14 @@ export type PresentationSnapshot = {
 export type PlayerStateElementSnapshot = {
     scene: Scene;
     layers: Map<Layer, [LogicAction.DisplayableElements, Record<string, any>][]>;
+    /**
+     * Whether this scene was a caller parked behind a returnable jump when the snapshot was taken.
+     *
+     * A snapshot is restored by rebuilding the element, so anything the element carries and the
+     * snapshot does not is silently dropped on the way back. This one is the difference between a
+     * scene that is on the stage and one that is on the stage waiting for a call to return.
+     */
+    suspended?: boolean;
 };
 export type PlayerAction = CalledActionResult;
 interface StageUtils {
@@ -229,6 +237,27 @@ export declare class GameState {
     addScene(scene: Scene): this;
     flush(): this;
     popScene(): this;
+    /**
+     * Advance every line still waiting for a click on `scene`, because the scene is leaving.
+     *
+     * A pending line lives as a `Clickable` in the scene's own stage entry, and the click callback
+     * in it is the only thing that settles the action waiting on it. Taking the entry away used to
+     * drop the line with it: nothing rendered the line any more, so no click could reach it, and
+     * whatever was waiting on it waited for ever.
+     *
+     * On the main stack that never showed, because every path that unloads a scene also clears the
+     * stack it would have blocked. A concurrent branch has a stack of its own and `Control.all`
+     * waits for every branch, so a single line left behind by a returning scene call stopped the
+     * story with no error and every click inert.
+     *
+     * Advanced rather than abandoned, because advancing is the only handle a pending line offers -
+     * its click callback is what settles it. The line is over either way, since it is no longer on
+     * screen; this way the branch that queued it carries on instead of stopping where it stood.
+     *
+     * Menus are deliberately not touched: choosing on the player's behalf would decide the story,
+     * which is worse than any of this.
+     */
+    settlePendingLines(scene: Scene): this;
     removeScene(scene: Scene): this;
     getSceneElements(): PlayerStateElement[];
     /**

package/dist/game/player/lib/AudioManager.d.ts

@@ -154,6 +154,18 @@ export declare class AudioManager {
     stop(sound: SoundElement, duration?: number): Awaitable<void>;
     setVolume(sound: SoundElement, volume: number, duration?: number): Awaitable<void>;
     mute(sound: SoundElement, muted?: boolean): Awaitable<void>;
+    /**
+     * Arm a transport change that will only act once a fade has finished, and hand back the test
+     * for whether it is still wanted by then.
+     *
+     * `FadeToken.finished` resolves when the fade is **cancelled** as well as when it runs out, and
+     * every later transport call on the same token cancels it - `resume` writes a volume, which is
+     * what cancels a pause's fade-out. Without this test, a scene call that returned while the
+     * caller's pause fade was still in flight landed the pause *after* the resume, with nothing
+     * left to undo it: the caller's music stayed silent for the rest of the scene while
+     * `sound.state.paused` said it was playing, so the next save recorded a stopped clip.
+     */
+    private arm;
     pause(sound: SoundElement, duration?: number): Awaitable<void>;
     resume(sound: SoundElement, duration?: number): Awaitable<void>;
     /**