narraleaf-react 0.9.0 → 0.10.0

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

@@ -1,33 +1,93 @@
 import { Pausing } from "../../../nlcore/elements/character/pause";
-import { Sentence } from "../../../nlcore/elements/character/sentence";
+import { Sentence, type StaticWord } from "../../../nlcore/elements/character/sentence";
 import { Word } from "../../../nlcore/elements/character/word";
 import { GameState } from "../../../../game/nlcore/common/game";
 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 = {
+export type TextAppearanceProps = {
     /**
      * The default color of the text
      */
     defaultColor?: Color;
+    fontSize?: React.CSSProperties["fontSize"];
+    fontWeight?: React.CSSProperties["fontWeight"];
+    fontWeightBold?: React.CSSProperties["fontWeight"];
+    fontFamily?: React.CSSProperties["fontFamily"];
+};
+export type BaseTextsProps = TextAppearanceProps & {
     className?: string;
     style?: React.CSSProperties;
     dialog?: DialogState;
 } & React.HTMLAttributes<HTMLDivElement>;
-/**
- * Props-based wrapper component
- * Provides a clean interface for direct prop usage
- */
-export interface TextsProps extends DialogElementProps {
-    sentence: Sentence;
-    gameState: GameState;
+export type TextsPreviewInput = StaticWord<string | Pausing> | StaticWord<string | Pausing>[];
+export type TextsPreviewLoop = boolean | {
+    /**
+     * Whether the preview restarts after the current type effect completes.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Delay before the next preview cycle starts, in milliseconds.
+     * @default 1000
+     */
+    delay?: number;
+};
+export interface TextsPreviewProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    /**
+     * Static text or words to preview.
+     */
+    text?: TextsPreviewInput;
+    /**
+     * Sentence to preview. Dynamic words are not evaluated; pass `words` when
+     * previewing already-evaluated runtime content.
+     */
+    sentence?: Sentence;
+    /**
+     * Already-evaluated words, useful when previewing dynamic sentence content.
+     */
+    words?: Word<Pausing | string>[];
+    /**
+     * Whether the preview should use the rolling type effect.
+     * @default true
+     */
     useTypeEffect?: boolean;
+    /**
+     * Loop behavior for settings screens and other static previews.
+     * @default true
+     */
+    loop?: TextsPreviewLoop;
+    /**
+     * Delay before replay when `loop` is `true`, in milliseconds.
+     * Ignored when `loop` is an object with `delay`.
+     * @default 1000
+     */
+    restartDelay?: number;
+    /**
+     * Characters per second used by the preview.
+     * @default current game's `cps` preference, or Game.DefaultPreference.cps outside GameProvider
+     */
+    cps?: number;
+    /**
+     * Speed multiplier used by the preview.
+     * @default current game's `gameSpeed` preference, or Game.DefaultPreference.gameSpeed outside GameProvider
+     */
+    gameSpeed?: number;
+    /**
+     * Duration for a pause without an explicit duration, in milliseconds.
+     * @default current game's `autoForwardDefaultPause` config, or Game.DefaultConfig.autoForwardDefaultPause outside GameProvider
+     */
+    pauseDuration?: number;
+    /**
+     * Fallback color when neither the word nor the sentence defines one.
+     */
+    defaultColor?: Color;
+    fontSize?: React.CSSProperties["fontSize"];
+    fontWeight?: React.CSSProperties["fontWeight"];
+    fontWeightBold?: React.CSSProperties["fontWeight"];
+    fontFamily?: React.CSSProperties["fontFamily"];
     onCompleted?: () => void;
-    finished?: boolean;
-    count?: number;
-    words?: Word<Pausing | string>[];
 }
 export type EntryTextsProps = BaseTextsProps & {
     entry: NvlDialogEntry;
@@ -36,10 +96,13 @@ export type EntryTextsProps = BaseTextsProps & {
     useTypeEffect: boolean;
     isActive: boolean;
 };
+export declare function TextsPreview({ text, sentence, words, useTypeEffect, loop, restartDelay, cps, gameSpeed, pauseDuration, defaultColor, className, style, fontSize, fontWeight, fontWeightBold, fontFamily, onCompleted, ...props }: TextsPreviewProps): React.JSX.Element;
+export type RawTextsProps = BaseTextsProps;
 export declare function RawTexts(props: BaseTextsProps): React.JSX.Element;
 /**
  * Context-based wrapper component
  * Provides integration with the sentence context
  */
+export type TextsProps = BaseTextsProps | EntryTextsProps;
 export declare function Texts(props: BaseTextsProps | EntryTextsProps): React.JSX.Element;
 export default Texts;

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

@@ -6,7 +6,7 @@ import React from "react";
 import { DialogAction, DialogStateType, SayElementProps } from "./type";
 type DialogEvents = {
     "event:dialog.requestComplete": [];
-    "event:dialog.complete": [force: boolean];
+    "event:dialog.complete": [force?: boolean];
     "event:dialog.forceSkip": [];
     "event:dialog.onFlush": [];
     "event:dialog.simulateClick": [];
@@ -16,6 +16,7 @@ type DialogStateConfig = {
     action: DialogAction;
     evaluatedWords: Word<Pausing | string>[];
     gameState: GameState;
+    suppressInitialAnimation?: boolean;
 };
 export declare class DialogState {
     static Events: {
@@ -31,12 +32,15 @@ export declare class DialogState {
     private _count;
     private _forceSkipped;
     private _idle;
+    private _active;
     private autoForwardScheduler;
     constructor(config: DialogStateConfig);
     get state(): DialogStateType;
     get deps(): React.DependencyList;
     isIdle(): boolean;
     setIdle(idle: boolean): void;
+    isActive(): boolean;
+    setActive(active: boolean): this;
     /**
      * Only for dialog component to call
      *
@@ -68,5 +72,5 @@ export declare class DialogState {
     safeEmit(event: keyof DialogEvents, ...args: DialogEvents[keyof DialogEvents]): this;
     private scheduleAutoForward;
 }
-export default function PlayerDialog({ action, onFinished, useTypeEffect, gameState, }: Readonly<SayElementProps>): React.JSX.Element;
+export default function PlayerDialog({ action, onFinished, useTypeEffect, gameState, active, }: Readonly<SayElementProps>): React.JSX.Element;
 export {};

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

@@ -4,6 +4,7 @@ import { Sentence } from "../../../nlcore/elements/character/sentence";
 import { Word } from "../../../nlcore/elements/character/word";
 import { Pausing } from "../../../nlcore/elements/character/pause";
 import React from "react";
+import type { HTMLMotionProps } from "motion/react";
 export interface SayElementProps {
     action: {
         sentence: Sentence | null;
@@ -19,12 +20,13 @@ export interface SayElementProps {
     onFinished?: (skiped?: boolean) => void;
     useTypeEffect?: boolean;
     gameState: GameState;
+    active?: boolean;
 }
 export interface IDialogProps {
 }
 export type DialogProps = {
-    children: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
+    children?: React.ReactNode;
+} & HTMLMotionProps<"div">;
 export type DialogElementProps = {
     children?: never;
 } & React.HTMLAttributes<HTMLDivElement>;

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

@@ -1,3 +1,4 @@
+import type { SentenceMetadata } from "../../../nlcore/elements/character/sentence";
 /**
  * Represents the context of a dialog, containing information about its completion status
  * and the text content.
@@ -9,6 +10,8 @@ export type DialogContext = {
     text: string;
     /** Whether the dialog is the narrator */
     isNarrator: boolean;
+    /** User-provided runtime metadata from the current sentence, if any */
+    metadata?: SentenceMetadata;
 };
 /**
  * A custom hook that provides access to the current dialog's state and content.

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

@@ -3,7 +3,7 @@ import { IDialogProps, SayElementProps } from "../elements/say/type";
 import { IUserMenuProps, MenuElementProps } from "../elements/menu/type";
 import { Story } from "../../nlcore/elements/story";
 import clsx from "clsx";
-import { Game } from "../../nlcore/game";
+import { Game, type GameLifecycleEventContext } from "../../nlcore/game";
 import { GameState } from "../gameState";
 import { Storable } from "../../nlcore/elements/persistent/storable";
 import { LiveGame } from "../../nlcore/game/liveGame";
@@ -28,17 +28,42 @@ export type PlayerEventContext = {
     liveGame: LiveGame;
     storable: Storable;
 };
+export type PlayerLifecycleEventContext = GameLifecycleEventContext;
 export interface PlayerProps {
     story?: Story;
     width?: string | number;
     height?: string | number;
     className?: clsx.ClassValue;
     /**
-     * Once the game is ready to be played
+     * Once the Player is initialized.
+     *
+     * This is not a preload or first-render guarantee. Use
+     * {@link PlayerProps.onPreloadComplete} or {@link PlayerProps.onFirstSceneReady}
+     * when you need those exact lifecycle points.
      *
      * only called each lifecycle once
      */
     onReady?: (ctx: PlayerEventContext) => void;
+    /**
+     * Once the initial preload pass has actually completed.
+     *
+     * This fires before the first scene is guaranteed to be rendered.
+     */
+    onPreloadComplete?: (ctx: PlayerLifecycleEventContext) => void;
+    /**
+     * Once the internal preload pass is ready and the Player has committed that state.
+     *
+     * only called each lifecycle once
+     *
+     * @deprecated Use {@link PlayerProps.onPreloadComplete}.
+     */
+    onPreloadedReady?: (ctx: PlayerEventContext) => void;
+    /**
+     * Once the first scene has mounted and the browser has had a frame to render it.
+     *
+     * This is the most direct signal that the game is visually ready for the player.
+     */
+    onFirstSceneReady?: (ctx: PlayerLifecycleEventContext) => void;
     /**
      * Once the game is ended
      *

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

@@ -28,6 +28,7 @@ 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";
+import { type NormalizedCharacterPortraitConfig } from "../nlcore/elements/character/avatar";
 export type NvlDialogEntry = {
     id: string;
     actionId: string;
@@ -119,6 +120,8 @@ type GameStateEvents = {
     "event:state.player.lineEnd": [];
     "event:state.player.requestFlush": [];
     "event:state.player.stageClick": [];
+    "event:state.scene.mount": [scene: Scene];
+    "event:state.scene.unmount": [scene: Scene];
     "event.state.onExpose": [unknown, ExposedState[ExposedStateType]];
     "event:state.onRender": [];
     "event:state:flushPreloadedScenes": [];
@@ -182,6 +185,7 @@ export declare class GameState {
     getSceneElements(): PlayerStateElement[];
     getLastScene(): Scene | null;
     getCurrentScene(): Scene | null;
+    findCurrentPortraitForCharacter(character: Character): NormalizedCharacterPortraitConfig | null;
     sceneExists(scene?: Scene): boolean;
     isSceneActive(scene: Scene): boolean;
     wait(ms: number): Promise<void>;
@@ -317,6 +321,7 @@ export declare class GameState {
     private syncNvlDerivedState;
     private emitNvlStateChange;
     private resolveNvlAdvance;
+    private isDisplayableVisible;
     private createWaitableAction;
     private sceneNotFound;
     private layerNotFound;

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

@@ -21,6 +21,7 @@ export declare class AudioManager {
     private sound;
     private ready;
     private isReady;
+    private isInitializing;
     constructor(gameState: GameState);
     /**
      * Must be called ONCE on the client side to prepare audio subsystem.

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

@@ -1,5 +1,9 @@
 import React, { ErrorInfo } from "react";
+type ErrorFallbackInfo = ErrorInfo & {
+    digest?: string;
+};
 export default function ErrorFallback({ error, errorInfo }: {
     error: Error;
-    errorInfo: ErrorInfo;
+    errorInfo: ErrorFallbackInfo;
 }): React.JSX.Element;
+export {};

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

@@ -27,6 +27,7 @@ export type PreloadedEventTypes = {
     "event:preloaded.change": [];
     "event:preloaded.mount": [];
     "event:preloaded.ready": [];
+    "event:preloaded.complete": [];
     "event:preloaded.unmount": [];
 };
 export declare class Preloaded {

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

@@ -4,9 +4,10 @@ import { Stage } from "./lib/PageRouter/Stage";
 import GameMenu from "./elements/menu/UIMenu/Menu";
 import Item from "./elements/menu/UIMenu/Item";
 import Notifications from "./elements/notification/Notifications";
-import Texts from "./elements/say/Sentence";
+import Texts, { TextsPreview } from "./elements/say/Sentence";
 import Nametag from "./elements/say/Nametag";
 import Dialog from "./elements/say/Dialog";
+import Avatar, { useAvatar } from "./elements/say/Avatar";
 import { useDialog } from "./elements/say/useDialog";
 import { useVoiceState } from "./elements/say/useVoiceState";
 import { Page, PageInjectContext } from "./lib/PageRouter/Page";
@@ -19,4 +20,8 @@ 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, };
+export type { DialogAvatarContext } from "./elements/say/Avatar";
+export type { BaseTextsProps, EntryTextsProps, RawTextsProps, TextAppearanceProps, TextsPreviewInput, TextsPreviewLoop, TextsPreviewProps, TextsProps, } from "./elements/say/Sentence";
+export type { NametagProps } from "./elements/say/Nametag";
+export type { ItemProps } from "./elements/menu/UIMenu/Item";
+export { Isolated, usePreference, Stage, GameMenu, Item, Notifications, Texts, TextsPreview, Nametag, Dialog, Avatar, useAvatar, useDialog, useVoiceState, Page, Layout, LayoutRouterProvider, PageInjectContext, RootPath, FixedAspectRatioContainer, useKeyBinding, useLiveGame, NvlContainer, DefaultNvlContainer, NvlDialogList, DefaultNvlDialogItem, NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible, };

package/dist/game/player/provider/game-state.d.ts

@@ -21,4 +21,5 @@ export declare function GameProvider({ children, game }: {
  * @throws Error if used outside of GameProvider
  */
 export declare function useGame(): GameContextType;
+export declare function useOptionalGame(): GameContextType | null;
 export {};