narraleaf-react 0.9.0-beta.5 → 0.9.0

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

@@ -40,9 +40,17 @@ export declare const SceneActionTypes: {
     readonly setBackgroundMusic: "scene:setBackgroundMusic";
     readonly preUnmount: "scene:preUnmount";
     readonly transitionToScene: "scene:transitionToScene";
+    readonly nvlBlock: "scene:nvlBlock";
+    readonly nvlShow: "scene:nvlShow";
+    readonly nvlHide: "scene:nvlHide";
+    readonly nvlEnd: "scene:nvlEnd";
+};
+export type NvlBlockOptions = {
+    showTransition?: Partial<TransformDefinitions.CommonTransformProps>;
+    hideTransition?: Partial<TransformDefinitions.CommonTransformProps>;
 };
 export type SceneActionContentType = {
-    [K in typeof SceneActionTypes[keyof typeof SceneActionTypes]]: K extends typeof SceneActionTypes["action"] ? Scene : K extends typeof SceneActionTypes["init"] ? [Scene] : K extends typeof SceneActionTypes["exit"] ? [] : K extends typeof SceneActionTypes["jumpTo"] ? [Scene] : K extends typeof SceneActionTypes["setBackgroundMusic"] ? [Sound | null, number?] : K extends typeof SceneActionTypes["preUnmount"] ? [] : K extends typeof SceneActionTypes["transitionToScene"] ? [ImageTransition, Scene | undefined, ImageSrc | Color | undefined] : any;
+    [K in typeof SceneActionTypes[keyof typeof SceneActionTypes]]: K extends typeof SceneActionTypes["action"] ? Scene : K extends typeof SceneActionTypes["init"] ? [Scene] : K extends typeof SceneActionTypes["exit"] ? [] : K extends typeof SceneActionTypes["jumpTo"] ? [Scene] : K extends typeof SceneActionTypes["setBackgroundMusic"] ? [Sound | null, number?] : K extends typeof SceneActionTypes["preUnmount"] ? [] : K extends typeof SceneActionTypes["transitionToScene"] ? [ImageTransition, Scene | undefined, ImageSrc | Color | undefined] : K extends typeof SceneActionTypes["nvlBlock"] ? [LogicAction.Actions[], NvlBlockOptions] : K extends typeof SceneActionTypes["nvlShow"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlHide"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlEnd"] ? [NvlBlockOptions?] : any;
 };
 export declare const StoryActionTypes: {
     readonly action: "story:action";
@@ -103,9 +111,10 @@ export declare const ControlActionTypes: {
     readonly while: "control:while";
     readonly break: "control:break";
     readonly sleep: "control:sleep";
+    readonly waitForClick: "control:waitForClick";
 };
 export type ControlActionContentType = {
-    [K in typeof ControlActionTypes[keyof typeof ControlActionTypes]]: K extends "control:do" ? [LogicAction.Actions[]] : K extends "control:doAsync" ? [LogicAction.Actions[]] : K extends "control:any" ? [LogicAction.Actions[]] : K extends "control:all" ? [LogicAction.Actions[]] : K extends "control:parallel" ? [LogicAction.Actions[]] : K extends "control:allAsync" ? [LogicAction.Actions[]] : K extends "control:repeat" ? [LogicAction.Actions[], number] : K extends "control:while" ? [LogicAction.Actions[], Lambda<boolean>] : K extends "control:break" ? [] : K extends "control:sleep" ? [LogicAction.Actions[], number | Awaitable<any> | Promise<any>] : any;
+    [K in typeof ControlActionTypes[keyof typeof ControlActionTypes]]: K extends "control:do" ? [LogicAction.Actions[]] : K extends "control:doAsync" ? [LogicAction.Actions[]] : K extends "control:any" ? [LogicAction.Actions[]] : K extends "control:all" ? [LogicAction.Actions[]] : K extends "control:parallel" ? [LogicAction.Actions[]] : K extends "control:allAsync" ? [LogicAction.Actions[]] : K extends "control:repeat" ? [LogicAction.Actions[], number] : K extends "control:while" ? [LogicAction.Actions[], Lambda<boolean>] : K extends "control:break" ? [] : K extends "control:sleep" ? [LogicAction.Actions[], number | Awaitable<any> | Promise<any>] : K extends "control:waitForClick" ? [] : any;
 };
 export declare const TextActionTypes: {
     readonly action: "text:action";

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

@@ -19,6 +19,7 @@ export declare class ControlAction<T extends typeof ControlActionTypes[keyof typ
         readonly while: "control:while";
         readonly break: "control:break";
         readonly sleep: "control:sleep";
+        readonly waitForClick: "control:waitForClick";
     };
     static executeActionsAsync(gameState: GameState, action: LogicAction.Actions): Awaitable<void>;
     checkActionChain(actions: LogicAction.Actions[]): LogicAction.Actions[];

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

@@ -10,9 +10,10 @@ import { Story } from "../../elements/story";
 import { ImageTransition } from "../../elements/transition/transitions/image/imageTransition";
 import { ActionSearchOptions } from "../../types";
 import { ExposedState, ExposedStateType } from "../../../player/type";
+import type { TransformDefinitions } from "../../elements/transform/type";
 import { ImageDataRaw } from "../../elements/displayable/image";
 import { ActionExecutionInjection, ExecutedActionResult } from "../action";
-type SceneSnapshot = {
+export type SceneSnapshot = {
     state: SceneDataRaw | null;
     local: Record<string, any>;
     element: PlayerStateElementSnapshot;
@@ -27,6 +28,10 @@ export declare class SceneAction<T extends typeof SceneActionTypes[keyof typeof
         readonly setBackgroundMusic: "scene:setBackgroundMusic";
         readonly preUnmount: "scene:preUnmount";
         readonly transitionToScene: "scene:transitionToScene";
+        readonly nvlBlock: "scene:nvlBlock";
+        readonly nvlShow: "scene:nvlShow";
+        readonly nvlHide: "scene:nvlHide";
+        readonly nvlEnd: "scene:nvlEnd";
     };
     static handleSceneInit(scene: Scene, next: CalledActionResult, state: GameState, awaitable: Awaitable<CalledActionResult, any>): {
         type: any;
@@ -43,10 +48,10 @@ export declare class SceneAction<T extends typeof SceneActionTypes[keyof typeof
     static restoreSceneSnapshot(snapshot: SceneSnapshot, state: GameState): void;
     applyTransition(gameState: GameState, transition: ImageTransition, injection: ActionExecutionInjection): Awaitable<CalledActionResult, CalledActionResult>;
     exit(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;
     getSceneName(scene: Scene | string): string;
     stringify(story: Story, seen: Set<LogicAction.Actions>, _strict: boolean): string;
 }
-export {};

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

@@ -155,7 +155,7 @@ export declare class StackModel {
      *                 The undo/history system will then re-insert the action
      *                 manually (see LiveGame.undo) to avoid having two copies
      *                 of the same action after deserialisation.
-     * @returns Snapshot that can be passed to {@link StackModel.deserialize}.
+     * @returns Snapshot that can be passed to StackModel.deserialize.
      */
     serialize(frozen?: boolean): StackModelRawData;
     reset(): void;

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

@@ -16,4 +16,5 @@ import { Persistent } from "../elements/persistent";
 import { Service } from "../elements/service";
 import { Layer } from "../elements/layer";
 import { Video } from "../elements/video";
-export { Character, Condition, Control, Image, Lambda, Menu, Scene, Script, Sentence, Sound, Story, Transform, Word, Text, Pause, Persistent, Service, Layer, Video, };
+import { NVLToken } from "../elements/nvl";
+export { Character, Condition, Control, Image, Lambda, Menu, NVLToken, Scene, Script, Sentence, Sound, Story, Transform, Word, Text, Pause, Persistent, Service, Layer, Video, };

package/dist/game/nlcore/elements/control.d.ts

@@ -79,6 +79,16 @@ export declare class Control extends Actionable {
      * @chainable
      */
     static sleep(duration: number | Awaitable<any> | Promise<any>): ChainedControl;
+    /**
+     * Pause execution until the user clicks anywhere on the stage (excluding GUI/Page elements).
+     * Similar to inserting a pause with no duration in a Sentence.
+     * @chainable
+     * @example
+     * ```ts
+     * Control.waitForClick();
+     * ```
+     */
+    static waitForClick(): ChainedControl;
     constructor(/**@internal */ config?: Partial<ControlConfig>);
     /**
      * Execute actions in order, waiting for each action to complete
@@ -126,4 +136,9 @@ export declare class Control extends Actionable {
      * @chainable
      */
     sleep(duration: number | Awaitable<any> | Promise<any>): ChainedControl;
+    /**
+     * Wait for user to click the stage (excluding GUI elements)
+     * @chainable
+     */
+    waitForClick(): ChainedControl;
 }

package/dist/game/nlcore/elements/nvl.d.ts

@@ -0,0 +1,41 @@
+import { Actionable } from "../action/actionable";
+import { LogicAction } from "../action/logicAction";
+import { Chained, Proxied } from "../action/chain";
+import type { TransformDefinitions } from "../elements/transform/type";
+import type { Scene } from "../elements/scene";
+type ChainedNVL = Proxied<NVLToken, Chained<LogicAction.Actions>>;
+export declare class NVLToken extends Actionable<null, NVLToken> {
+    constructor(scene: Scene);
+    /**
+     * Show the NVL layer with optional transition
+     * @param options - Optional transition properties for showing the NVL layer
+     * @chainable
+     * @example
+     * ```ts
+     * nvl.show({ duration: 500 });
+     * ```
+     */
+    show(options?: Partial<TransformDefinitions.CommonTransformProps>): ChainedNVL;
+    /**
+     * Hide the NVL layer with optional transition
+     * Does not exit NVL mode or clear dialogs
+     * @param options - Optional transition properties for hiding the NVL layer
+     * @chainable
+     * @example
+     * ```ts
+     * nvl.hide({ duration: 500 });
+     * ```
+     */
+    hide(options?: Partial<TransformDefinitions.CommonTransformProps>): ChainedNVL;
+    /**
+     * Force exit NVL mode immediately
+     * Clears all accumulated dialogs and hides the NVL layer
+     * @chainable
+     * @example
+     * ```ts
+     * nvl.end();
+     * ```
+     */
+    end(): ChainedNVL;
+}
+export {};

package/dist/game/nlcore/elements/scene.d.ts

@@ -7,6 +7,8 @@ import { ActionStatements, Persistent } from "../common/core";
 import { Chained, Proxied } from "../action/chain";
 import { ImageTransition } from "../elements/transition/transitions/image/imageTransition";
 import { Layer } from "../elements/layer";
+import { NVLToken } from "./nvl";
+import type { TransformDefinitions } from "../elements/transform/type";
 export interface ISceneUserConfig {
     /**
      * Background music
@@ -79,6 +81,31 @@ export declare class Scene extends Constructable<LogicAction.Actions, Scene> {
      * ```
      */
     setBackgroundMusic(sound: Sound | null, fade?: number): ChainedScene;
+    /**
+     * Create an NVL (Novel) mode block for displaying accumulated dialog.
+     * In NVL mode, dialogs are stacked on screen rather than replacing each other.
+     * @param actions - Actions to execute within NVL mode, or a callback receiving an NVLToken
+     * @chainable
+     * @example
+     * ```ts
+     * scene.nvl([
+     *     character.say("First line"),
+     *     character.say("Second line"),
+     *     character.say("Third line"),
+     * ]);
+     * ```
+     * @example
+     * ```ts
+     * scene.nvl(nvl => [
+     *     nvl.show({ duration: 500 }),
+     *     character.say("Line 1"),
+     *     character.say("Line 2"),
+     *     nvl.hide({ duration: 500 }),
+     * ]);
+     * ```
+     */
+    nvl(actions: ActionStatements | ((nvl: NVLToken) => ActionStatements)): ChainableAction;
+    nvl(options: Partial<TransformDefinitions.CommonTransformProps>, actions: ActionStatements | ((nvl: NVLToken) => ActionStatements)): ChainableAction;
     /**
      * Register the list of actions (or an action-generating callback) that this scene will execute.
      * @param actions - Either a list of actions or a factory that receives the scene and returns actions.

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

@@ -7,7 +7,7 @@ import { PlayerStateData } from "../player/gameState";
 import { GuardConfig } from "../player/guard";
 import React from "react";
 import { StackModel, StackModelRawData } from "./action/stackModel";
-import { MenuComponent, NotificationComponent, SayComponent } from "./common/player";
+import { MenuComponent, NotificationComponent, NvlDialogComponent, SayComponent } from "./common/player";
 import { Color, LiveGameEventToken } from "./types";
 export interface SavedGameMetaData {
     /**
@@ -276,6 +276,11 @@ export type GameConfig = {
      * @default DefaultSay
      */
     dialog: SayComponent;
+    /**
+     * The component to use for NVL mode dialog
+     * @default DefaultNvlContainer
+     */
+    nvlDialog: NvlDialogComponent;
     /**
      * The function to call when an error occurs
      * @default () => {}

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

@@ -1,8 +1,10 @@
 import { DefaultDialog } from "../../../game/player/elements/say/Dialog";
 import { DefaultMenu } from "../../../game/player/elements/menu/PlayerMenu";
 import { DefaultNotification } from "../elements/notification/PlayerNotification";
+import { DefaultNvlContainer } from "../elements/nvl/DefaultNvlContainer";
 export declare const DefaultElements: {
     readonly say: typeof DefaultDialog;
     readonly menu: typeof DefaultMenu;
     readonly notification: typeof DefaultNotification;
+    readonly nvlDialog: typeof DefaultNvlContainer;
 };

package/dist/game/player/elements/nvl/DefaultNvlContainer.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+import { INvlContainerProps } from "./type";
+export declare function DefaultNvlContainer({ renderDialogItem, dialogs }: INvlContainerProps): React.JSX.Element;
+export default DefaultNvlContainer;

package/dist/game/player/elements/nvl/NvlContainer.d.ts

@@ -0,0 +1,5 @@
+import React from "react";
+import { NvlContainerProps, INvlContainerProps } from "./type";
+export declare function NvlContainer({ children, className, style }: NvlContainerProps): React.JSX.Element;
+export declare function BaseNvlContainer({ renderDialogItem: _renderDialogItem, ...props }: INvlContainerProps & NvlContainerProps): React.JSX.Element;
+export default NvlContainer;

package/dist/game/player/elements/nvl/NvlContext.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+import { NvlDialogEntry } from "../../gameState";
+import { NvlContextValue } from "./type";
+declare const NvlContext: React.Context<NvlContextValue>;
+export declare function useNvl(): NvlContextValue;
+export declare function useNvlDialogs(): NvlDialogEntry[];
+export declare function useIsNvlMode(): boolean;
+export declare function useIsNvlVisible(): boolean;
+export interface NvlProviderProps {
+    children: React.ReactNode;
+}
+export declare function NvlProvider({ children }: NvlProviderProps): React.JSX.Element;
+export default NvlContext;

package/dist/game/player/elements/nvl/NvlDialogList.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+import { NvlDialogListProps, NvlDialogItemProps } from "./type";
+export declare function NvlDialogList({ children, className, style, renderDialogItem }: NvlDialogListProps): React.JSX.Element;
+export declare function DefaultNvlDialogItem({ entry, index, className, style, texts }: NvlDialogItemProps & {
+    texts?: React.ReactNode;
+}): React.JSX.Element;
+export default NvlDialogList;

package/dist/game/player/elements/nvl/type.d.ts

@@ -0,0 +1,49 @@
+import type { GameState, NvlDialogEntry, NvlState } from "../../gameState";
+import type { TransformDefinitions } from "../../../nlcore/elements/transform/type";
+import type { Word } from "../../../nlcore/elements/character/word";
+import type { Pausing } from "../../../nlcore/elements/character/pause";
+import React from "react";
+export type NvlDialogProxy = {
+    entry: NvlDialogEntry;
+    index: number;
+    isActive: boolean;
+    gameState: GameState;
+    words: Word<Pausing | string>[];
+    useTypeEffect: boolean;
+};
+export interface INvlContainerProps {
+    dialogs?: NvlDialogProxy[];
+    renderDialogItem?: NvlDialogItemRenderer;
+}
+export interface NvlContainerProps {
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export interface NvlDialogListProps {
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    renderDialogItem?: NvlDialogItemRenderer;
+}
+export interface NvlDialogItemProps {
+    entry: NvlDialogEntry;
+    index: number;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export interface NvlDialogItemRenderProps {
+    entry: NvlDialogEntry;
+    index: number;
+    isActive: boolean;
+    nametag: React.ReactNode;
+    texts: React.ReactNode;
+}
+export type NvlDialogItemRenderer = (props: NvlDialogItemRenderProps) => React.ReactNode;
+export interface NvlContextValue {
+    state: NvlState;
+    dialogs: NvlDialogEntry[];
+    isActive: boolean;
+    isVisible: boolean;
+    transitionOptions: Partial<TransformDefinitions.CommonTransformProps> | null;
+}

package/dist/game/player/elements/nvl/useNvlDialogState.d.ts

@@ -0,0 +1,14 @@
+import { DialogState } from "../say/UIDialog";
+import { GameState } from "../../gameState";
+import type { NvlDialogEntry } from "../../gameState";
+import type { Word } from "../../../nlcore/elements/character/word";
+import type { Pausing } from "../../../nlcore/elements/character/pause";
+type UseNvlDialogStateParams = {
+    entry: NvlDialogEntry;
+    gameState: GameState;
+    words: Word<Pausing | string>[];
+    isActive: boolean;
+    useTypeEffect: boolean;
+};
+export declare function useNvlDialogState({ entry, gameState, words, isActive, useTypeEffect, }: UseNvlDialogStateParams): DialogState;
+export {};

package/dist/game/player/elements/player/StageClickAnnouncer.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -1,2 +1,9 @@
 import React from "react";
-export default function Nametag({ ...props }: Readonly<React.HTMLAttributes<HTMLDivElement>>): React.JSX.Element;
+import type { Character } from "../../../nlcore/elements/character";
+import type { NvlDialogEntry } from "../../gameState";
+type NametagProps = React.HTMLAttributes<HTMLDivElement> & {
+    entry?: NvlDialogEntry;
+    character?: Character | null;
+};
+export default function Nametag({ entry, character, ...props }: Readonly<NametagProps>): React.JSX.Element;
+export {};

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

@@ -6,6 +6,7 @@ import { Color } from "../../../../game/nlcore/types";
 import React from "react";
 import { DialogElementProps } from "./type";
 import { DialogState } from "./UIDialog";
+import type { NvlDialogEntry } from "../../gameState";
 type BaseTextsProps = {
     /**
      * The default color of the text
@@ -28,10 +29,17 @@ export interface TextsProps extends DialogElementProps {
     count?: number;
     words?: Word<Pausing | string>[];
 }
+export type EntryTextsProps = BaseTextsProps & {
+    entry: NvlDialogEntry;
+    gameState: GameState;
+    words: Word<Pausing | string>[];
+    useTypeEffect: boolean;
+    isActive: boolean;
+};
 export declare function RawTexts(props: BaseTextsProps): React.JSX.Element;
 /**
  * Context-based wrapper component
  * Provides integration with the sentence context
  */
-export declare function Texts(props: BaseTextsProps): React.JSX.Element;
+export declare function Texts(props: BaseTextsProps | EntryTextsProps): React.JSX.Element;
 export default Texts;

package/dist/game/player/elements/type.d.ts

@@ -8,16 +8,20 @@ import { GameState } from "../gameState";
 import { Storable } from "../../nlcore/elements/persistent/storable";
 import { LiveGame } from "../../nlcore/game/liveGame";
 import { INotificationsProps, NotificationsProps } from "./notification/type";
+import { INvlContainerProps } from "./nvl/type";
 export type Components<T extends Record<string, any>> = (props: Readonly<T>) => React.JSX.Element;
 export type SayComponent = Components<IDialogProps>;
 export type MenuComponent = Components<IUserMenuProps>;
 export type NotificationComponent = Components<INotificationsProps>;
+export type NvlDialogComponent = Components<INvlContainerProps>;
 export type ComponentsTypes = {
     say: SayComponent;
     menu: MenuComponent;
     notification: NotificationComponent;
+    nvlDialog: NvlDialogComponent;
 };
 export type { SayElementProps, MenuElementProps, NotificationsProps as INotificationProps, };
+export type { INvlContainerProps, NvlDialogItemRenderProps } from "./nvl/type";
 export type PlayerEventContext = {
     game: Game;
     gameState: GameState;

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

@@ -10,6 +10,7 @@ import { Storable } from "../nlcore/elements/persistent/storable";
 import { Game } from "../nlcore/game";
 import { Clickable, MenuElement, TextElement } from "./gameState.type";
 import { Sentence } from "../nlcore/elements/character/sentence";
+import { type SceneSnapshot } from "../nlcore/action/actions/sceneAction";
 import { Logger } from "../../util/logger";
 import { Story } from "../nlcore/elements/story";
 import { LiveGame } from "../nlcore/game/liveGame";
@@ -24,6 +25,28 @@ import { Timelines } from "./Tasks";
 import { Notification, NotificationManager } from "./lib/notification";
 import { ActionHistoryManager } from "../../game/nlcore/action/actionHistory";
 import { GameHistoryManager } from "../../game/nlcore/action/gameHistory";
+import type { Character } from "../nlcore/elements/character";
+import type { TransformDefinitions } from "../nlcore/elements/transform/type";
+import type { NvlBlockOptions } from "../nlcore/action/actionTypes";
+export type NvlDialogEntry = {
+    id: string;
+    actionId: string;
+    character: Character | null;
+    sentence: Sentence;
+    text: string;
+};
+export type NvlDialogPhase = "idle" | "typing" | "awaitAdvance";
+export type NvlState = {
+    active: boolean;
+    visible: boolean;
+    sessionId: string | null;
+    dialogs: NvlDialogEntry[];
+    options: NvlBlockOptions | null;
+    activeDialogId: string | null;
+    phase: NvlDialogPhase;
+    pendingAdvance: boolean;
+    isTyping: boolean;
+};
 type Legacy_PlayerStateElement = {
     texts: Clickable<TextElement>[];
     menus: Clickable<MenuElement, Chosen>[];
@@ -47,6 +70,23 @@ export type PlayerStateElement = {
     texts: Clickable<TextElement>[];
     menus: Clickable<MenuElement, Chosen>[];
 };
+export type NvlStateData = {
+    active: boolean;
+    visible: boolean;
+    sessionId: string | null;
+    options?: NvlBlockOptions | null;
+    activeDialogId?: string | null;
+    phase?: NvlDialogPhase;
+    pendingAdvance?: boolean;
+    dialogIds?: string[];
+    dialogs?: NvlDialogEntryData[];
+};
+export type NvlDialogEntryData = {
+    id: string;
+    actionId?: string;
+    text: string;
+    characterId: string | null;
+};
 export type PlayerStateData = {
     scenes: {
         sceneId: string;
@@ -61,6 +101,11 @@ export type PlayerStateData = {
     }[];
     audio: AudioManagerDataRaw;
     videos: [videoId: string, videoState: VideoStateRaw][];
+    nvlState?: NvlStateData;
+};
+export type PresentationSnapshot = {
+    scenes: SceneSnapshot[];
+    nvlState: NvlState;
 };
 interface StageUtils {
     update: () => void;
@@ -73,9 +118,16 @@ type GameStateEvents = {
     "event:state.player.skip": [force?: boolean];
     "event:state.player.lineEnd": [];
     "event:state.player.requestFlush": [];
+    "event:state.player.stageClick": [];
     "event.state.onExpose": [unknown, ExposedState[ExposedStateType]];
     "event:state.onRender": [];
     "event:state:flushPreloadedScenes": [];
+    "event:state.nvl.enter": [sessionId: string, options: NvlBlockOptions | null];
+    "event:state.nvl.exit": [];
+    "event:state.nvl.dialogComplete": [dialogId: string];
+    "event:state.nvl.dialogAppend": [entry: NvlDialogEntry];
+    "event:state.nvl.visibilityChange": [visible: boolean, options?: Partial<TransformDefinitions.CommonTransformProps>];
+    "event:state.nvl.change": [state: NvlState];
 };
 /**
  * Core game state management class
@@ -86,6 +138,8 @@ export declare class GameState {
         [K in keyof GameStateEvents]: K;
     };
     private state;
+    private nvlState;
+    private _suppressNextNvlTyping;
     currentHandling: CalledActionResult | null;
     stage: StageUtils;
     game: Game;
@@ -106,6 +160,8 @@ export declare class GameState {
     readonly actionHistory: ActionHistoryManager;
     readonly gameHistory: GameHistoryManager;
     pageRouter: null;
+    private stageClickBuffer;
+    private readonly nvlAdvanceWaiters;
     constructor(game: Game, stage: StageUtils);
     get deps(): number;
     addVideo(video: Video): this;
@@ -138,6 +194,78 @@ export declare class GameState {
     createMenu(menu: MenuData, afterChoose?: (choice: Chosen) => void, scene?: Scene): LiveGameEventToken & {
         prompt: null | string;
     };
+    /**
+     * Enter NVL mode
+     * @param options - Optional block options for transitions
+     */
+    enterNvlMode(options?: NvlBlockOptions | null): this;
+    /**
+     * Exit NVL mode
+     * @param options - Optional block options for transitions
+     */
+    exitNvlMode(options?: NvlBlockOptions | null): this;
+    /**
+     * Set NVL layer visibility without exiting NVL mode
+     * @param visible - Whether to show or hide the NVL layer
+     * @param options - Optional transition properties
+     */
+    setNvlVisibility(visible: boolean, options?: Partial<TransformDefinitions.CommonTransformProps>): this;
+    /**
+     * Append a dialog to the NVL dialog list
+     * @param entry - The dialog entry to append
+     */
+    appendNvlDialog(entry: NvlDialogEntry): this;
+    /**
+     * Remove a dialog from the NVL dialog list
+     * @param id - The dialog id to remove
+     */
+    removeNvlDialog(id: string): this;
+    /**
+     * Get current NVL dialogs
+     */
+    getNvlDialogs(): NvlDialogEntry[];
+    /**
+     * Check if currently in NVL mode
+     */
+    isNvlMode(): boolean;
+    /**
+     * Get NVL state
+     */
+    getNvlState(): NvlState;
+    /**
+     * Create a snapshot of the current NVL state.
+     */
+    createNvlSnapshot(): NvlState;
+    createPresentationSnapshot(): PresentationSnapshot;
+    /**
+     * Restore NVL state and refresh UI.
+     */
+    restoreNvlSnapshot(snapshot: NvlState): this;
+    restorePresentationSnapshot(snapshot: PresentationSnapshot): this;
+    /**
+     * Clear NVL dialogs
+     */
+    clearNvlDialogs(): this;
+    setNvlActiveDialog(dialogId: string | null, isTyping: boolean): this;
+    setNvlTyping(isTyping: boolean): this;
+    getNvlDialog(dialogId: string): NvlDialogEntry | null;
+    getActiveNvlDialogForAction(actionId: string): NvlDialogEntry | null;
+    getLatestNvlDialogForAction(actionId: string): NvlDialogEntry | null;
+    allocateNvlDialogId(actionId: string): string;
+    ensureNvlDialog(entry: NvlDialogEntry): {
+        created: boolean;
+        entry: NvlDialogEntry;
+    };
+    activateNvlDialog(dialogId: string, phase?: Exclude<NvlDialogPhase, "idle">, preserveProgress?: boolean): this;
+    waitForNvlAdvance(dialogId: string, resolve: () => void): LiveGameEventToken;
+    requestNvlAdvance(dialogId: string): "ignore" | "typing" | "advance";
+    requestNvlSkip(dialogId: string): "ignore" | "typing" | "advance";
+    completeNvlTyping(dialogId: string): boolean;
+    settleNvlDialog(dialogId: string): this;
+    suppressNextNvlTyping(): this;
+    consumeNvlTypingSuppression(): boolean;
+    recordStageClick(): this;
+    consumeStageClick(maxAgeMs?: number): boolean;
     createDisplayable(displayable: LogicAction.DisplayableElements, scene?: Scene | null, layer?: Layer | null): this;
     disposeDisplayable(displayable: LogicAction.DisplayableElements, scene?: Scene | null, layer?: Layer | null): this;
     forceReset(): void;
@@ -186,6 +314,9 @@ export declare class GameState {
     fromElementSnapshot(snapshot: PlayerStateElementSnapshot): PlayerStateElement;
     private removeElements;
     private resetLayers;
+    private syncNvlDerivedState;
+    private emitNvlStateChange;
+    private resolveNvlAdvance;
     private createWaitableAction;
     private sceneNotFound;
     private layerNotFound;

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

@@ -15,4 +15,8 @@ import { RootPath } from "./lib/PageRouter/router";
 import { FixedAspectRatioContainer } from "./lib/FixedAspectRatioContainer";
 import { useKeyBinding } from "./lib/keyMap";
 import { useLiveGame } from "./lib/useLiveGame";
-export { Isolated, usePreference, Stage, GameMenu, Item, Notifications, Texts, Nametag, Dialog, useDialog, useVoiceState, Page, Layout, LayoutRouterProvider, PageInjectContext, RootPath, FixedAspectRatioContainer, useKeyBinding, useLiveGame, };
+import { NvlContainer } from "./elements/nvl/NvlContainer";
+import { DefaultNvlContainer } from "./elements/nvl/DefaultNvlContainer";
+import { NvlDialogList, DefaultNvlDialogItem } from "./elements/nvl/NvlDialogList";
+import { NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible } from "./elements/nvl/NvlContext";
+export { Isolated, usePreference, Stage, GameMenu, Item, Notifications, Texts, Nametag, Dialog, useDialog, useVoiceState, Page, Layout, LayoutRouterProvider, PageInjectContext, RootPath, FixedAspectRatioContainer, useKeyBinding, useLiveGame, NvlContainer, DefaultNvlContainer, NvlDialogList, DefaultNvlDialogItem, NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible, };