narraleaf-react 0.39.1 → 0.40.0

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/player/stageClickIntent.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What a click that landed on the stage is asking for.
+ *
+ * The stage announcer decides *whether* a click belongs to the stage at all - it is over the player,
+ * it is not inside a menu, a notification, a page or a word that takes its own clicks. This decides
+ * what the ones that survive that walk actually mean, and it is kept apart from the walk because the
+ * walk is DOM and this is not: the rules below are the ones worth pinning, and pinning them needs no
+ * document.
+ *
+ * Comments in English per project convention.
+ */
+/**
+ * The three things a click on the stage can mean.
+ *
+ * - `advance` - settle the line, the ordinary case.
+ * - `restoreDialog` - bring the dialog box back, because it has been put away.
+ * - `ignore` - the click reached nothing that wants it.
+ */
+export type StageClickIntent = "advance" | "restoreDialog" | "ignore";
+export type StageClickInput = {
+    /**
+     * Whether the announcer's DOM walk decided this click belongs to the stage rather than to
+     * something drawn on it.
+     */
+    onStage: boolean;
+    /**
+     * The `showDialog` preference: `false` means the player has put the box away to look at the
+     * picture behind it.
+     */
+    dialogShown: boolean;
+    /** Whether anything is currently holding the line - see `GameState.suspendAdvance`. */
+    advanceSuspended: boolean;
+};
+/**
+ * Decide what one click on the stage means.
+ *
+ * Two rules, in the order they are asked:
+ *
+ * - **A click with the box put away brings it back; it does not spend a line.** The box is the thing
+ *   a click on the stage acts on, so with the box gone there is nothing on screen the click could
+ *   have been aimed at - and the line it would have settled is one the player never saw. Every
+ *   visual novel treats the next click after a hide as the one that undoes the hide, which is also
+ *   the only reading that cannot lose text.
+ * - **That outranks a hold on the line.** A suspension is a hold on *advancing*, taken by something
+ *   drawn over a line that wants the player's attention first - a definition popup on an inline
+ *   word. Everything that takes one is drawn inside the box, so while the box is away the hold is
+ *   invisible; leaving it in charge would mean a player who put the box away had no way to bring it
+ *   back and no way to reach the thing holding the line either. Restoring the box does not settle
+ *   the line, so it takes nothing away from whatever holds it: the hold is still there, and still
+ *   in charge, the moment the box is back.
+ */
+export declare function resolveStageClickIntent({ onStage, dialogShown, advanceSuspended, }: StageClickInput): StageClickIntent;

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/say/dialogVisibility.d.ts

@@ -0,0 +1,42 @@
+/**
+ * How a dialog box that has been put away is hidden.
+ *
+ * Hiding the box is how a player looks at the picture behind it; it is not the box going away. The
+ * box keeps its line, its typing task, its animations and - the part this file exists for - its
+ * place in hit testing, because whatever a game has drawn inside the box is still a thing the player
+ * can be reaching for. The engine's own UI has nothing in there, but a host that renders its own
+ * dialog into this box does, and that content is the only route it has to the pointer.
+ *
+ * Comments in English per project convention.
+ */
+export type DialogVisibility = {
+    /** The class the box carries while in this state, or an empty string for none. */
+    className: string;
+    /** Whether the box should be hidden from assistive technology. */
+    ariaHidden: boolean;
+};
+/**
+ * Decide how a box in the given `showDialog` state is presented.
+ *
+ * **Not `visibility: hidden`, and not `display: none`.** Both take the whole subtree out of hit
+ * testing, which is a different statement from "do not draw this": with either of them the box is
+ * not merely invisible, it is unreachable, and so is everything a host has rendered inside it. The
+ * box used to be hidden that way while also asking for `pointer-events: auto` on the same element -
+ * two instructions that cannot both be followed, and the one that lost is the one that was meant.
+ * What it cost: a panel inside the box could not be scrolled, tapped or dismissed while the box was
+ * away, and nothing said why, because the elements were all still there and all still styled to
+ * receive the pointer.
+ *
+ * Transparency says only "do not draw this", which is what hiding the box means. It costs a stacking
+ * context, which this element already has wherever the stage is scaled to fit, and it leaves the box
+ * in the accessibility tree - so a hidden box is marked `aria-hidden` here rather than relying on a
+ * side effect of how it is drawn.
+ *
+ * **No `pointer-events` of its own, in either state.** Whether a box is reachable at all is its
+ * layer's to say, not the box's: a scene parked behind a returnable jump keeps a layer that covers
+ * the stage with nothing in it, and that layer turns the pointer off for everything inside it. A box
+ * asserting `pointer-events: auto` would overrule that and go back to swallowing the clicks meant
+ * for the scene in front of it. The old hidden state did assert it, which was harmless only because
+ * it was paired with a rule that removed the box from hit testing anyway.
+ */
+export declare function resolveDialogVisibility(shown: boolean): DialogVisibility;

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

@@ -237,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[];
     /**