narraleaf-react 0.9.1 → 0.10.0

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

@@ -3,9 +3,13 @@ import { DeepPartial, Hooks, StringKeyOf } from "../../util/data";
 import { LogicAction } from "./action/logicAction";
 import { LiveGame } from "./game/liveGame";
 import { Preference } from "./game/preference";
+import { GameState } from "../player/gameState";
 import { Plugins, IGamePluginRegistry } from "./game/plugin/plugin";
 import { LayoutRouter } from "../player/lib/PageRouter/router";
 import { KeyMap } from "./game/keyMap";
+import type { Storable } from "./elements/persistent/storable";
+import type { Scene } from "./elements/scene";
+import type { LiveGameEventHandler, LiveGameEventToken } from "./types";
 declare enum GameSettingsNamespace {
     game = "game"
 }
@@ -34,6 +38,17 @@ export type GameHooks = {
      */
     "afterRestore": [];
 };
+export type GameLifecycleEventContext = {
+    game: Game;
+    gameState: GameState;
+    liveGame: LiveGame;
+    storable: Storable;
+    scene: Scene | null;
+};
+export type GameLifecycleEvents = {
+    "event:game.preloadComplete": [ctx: GameLifecycleEventContext];
+    "event:game.firstSceneReady": [ctx: GameLifecycleEventContext];
+};
 export declare class Game {
     static GameSettingsNamespace: typeof GameSettingsNamespace;
     readonly hooks: Hooks<GameHooks>;
@@ -45,11 +60,17 @@ export declare class Game {
      * Game key bindings
      */
     keyMap: KeyMap;
+    static LifecycleEventTypes: {
+        [K in keyof GameLifecycleEvents]: K;
+    };
     /**
      * Plugin registry
      */
     plugins: Plugins;
     router: LayoutRouter;
+    private readonly lifecycleEvents;
+    private preloadCompleteContext;
+    private firstSceneReadyContext;
     /**
      * Create a new game
      * @param config - Game configuration
@@ -78,6 +99,45 @@ export declare class Game {
      * @param plugin - The plugin to use
      */
     use(plugin: IGamePluginRegistry): this;
+    /**
+     * Listen for the initial preload pass completing.
+     *
+     * This is the point where the initial preload pass has actually finished.
+     * Use {@link whenPreloadComplete} if the listener may be registered after the event has fired.
+     */
+    onPreloadComplete(fc: LiveGameEventHandler<GameLifecycleEvents["event:game.preloadComplete"]>): LiveGameEventToken;
+    /**
+     * Listen once for the initial preload pass completing.
+     */
+    oncePreloadComplete(fc: LiveGameEventHandler<GameLifecycleEvents["event:game.preloadComplete"]>): LiveGameEventToken;
+    /**
+     * Resolve when the initial preload pass has completed.
+     */
+    whenPreloadComplete(): Promise<GameLifecycleEventContext>;
+    /**
+     * Whether the initial preload pass has completed.
+     */
+    isPreloadComplete(): boolean;
+    /**
+     * Listen for the first scene being fully ready.
+     *
+     * This fires after the initial preload pass has actually finished, after the first
+     * scene component is mounted, and after the browser has had a frame to render it.
+     * Use {@link whenFirstSceneReady} if the listener may be registered after the event has fired.
+     */
+    onFirstSceneReady(fc: LiveGameEventHandler<GameLifecycleEvents["event:game.firstSceneReady"]>): LiveGameEventToken;
+    /**
+     * Listen once for the first scene being fully ready.
+     */
+    onceFirstSceneReady(fc: LiveGameEventHandler<GameLifecycleEvents["event:game.firstSceneReady"]>): LiveGameEventToken;
+    /**
+     * Resolve when the first scene is fully ready.
+     */
+    whenFirstSceneReady(): Promise<GameLifecycleEventContext>;
+    /**
+     * Whether the first scene is fully ready.
+     */
+    isFirstSceneReady(): boolean;
     getLiveGame(): LiveGame;
     /**
      * Dispose the game and all its resources

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

@@ -8,7 +8,7 @@ import { GuardConfig } from "../player/guard";
 import React from "react";
 import { StackModel, StackModelRawData } from "./action/stackModel";
 import { MenuComponent, NotificationComponent, NvlDialogComponent, SayComponent } from "./common/player";
-import { Color, LiveGameEventToken } from "./types";
+import { LiveGameEventToken } from "./types";
 export interface SavedGameMetaData {
     /**
      * The timestamp of when the game was created
@@ -251,16 +251,6 @@ export type GameConfig = {
      * @default false
      */
     allowSkipVideo: boolean;
-    /**
-     * The default text color for the dialog
-     * @default "#000"
-     */
-    defaultTextColor: Color;
-    /**
-     * The default text color for the character nametag
-     * @default "#000"
-     */
-    defaultNametagColor: Color;
     /**
      * The component to use for the notification
      * @default DefaultNotification
@@ -310,36 +300,11 @@ export type GameConfig = {
          */
         guard: GuardConfig;
     };
-    /**
-     * Default font size for the game
-     * @default "16px"
-     */
-    fontSize: React.CSSProperties["fontSize"];
-    /**
-     * Default font weight for the game
-     * @default 400
-     */
-    fontWeight: number;
-    /**
-     * Default font weight for the game
-     * @default 700
-     */
-    fontWeightBold: number;
-    /**
-     * Default font family for the game
-     * @default "sans-serif"
-     */
-    fontFamily: React.CSSProperties["fontFamily"];
     /**
      * Override the default stage
      * @default null
      */
     stage: React.ReactNode | null;
-    /**
-     * The default color for the menu choices
-     * @default "#000"
-     */
-    defaultMenuChoiceColor: Color;
     /**
      * The maximum number of times a stack model can loop
      * @default 1000

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

@@ -1,4 +1,4 @@
 import "client-only";
 import { PlayerProps } from "../elements/type";
 import React from "react";
-export default function Player({ story, width, height, className, onReady, onPreloadedReady, onEnd, onError, children, active, }: Readonly<PlayerProps>): React.JSX.Element;
+export default function Player({ story, width, height, className, onReady, onPreloadComplete, onPreloadedReady, onFirstSceneReady, onEnd, onError, children, active, }: Readonly<PlayerProps>): React.JSX.Element;

package/dist/game/player/elements/menu/UIMenu/Item.d.ts

@@ -1,5 +1,6 @@
+import { type TextAppearanceProps } from "../../../elements/say/Sentence";
 import React from "react";
-export interface ItemProps {
+export interface ItemProps extends TextAppearanceProps {
     className?: string;
     style?: React.CSSProperties;
     /**
@@ -9,4 +10,4 @@ export interface ItemProps {
      */
     bindKey?: string;
 }
-export default function Item({ className, style, bindKey }: ItemProps): React.JSX.Element;
+export default function Item({ className, style, bindKey, defaultColor, fontSize, fontWeight, fontWeightBold, fontFamily, }: ItemProps): React.JSX.Element;

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

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

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

@@ -4,14 +4,19 @@ 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;
@@ -84,19 +89,6 @@ export interface TextsPreviewProps extends Omit<React.HTMLAttributes<HTMLDivElem
     fontFamily?: React.CSSProperties["fontFamily"];
     onCompleted?: () => void;
 }
-/**
- * Props-based wrapper component
- * Provides a clean interface for direct prop usage
- */
-export interface TextsProps extends DialogElementProps {
-    sentence: Sentence;
-    gameState: GameState;
-    useTypeEffect?: boolean;
-    onCompleted?: () => void;
-    finished?: boolean;
-    count?: number;
-    words?: Word<Pausing | string>[];
-}
 export type EntryTextsProps = BaseTextsProps & {
     entry: NvlDialogEntry;
     gameState: GameState;
@@ -105,10 +97,12 @@ export type EntryTextsProps = BaseTextsProps & {
     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/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,23 +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

@@ -120,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": [];

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

@@ -21,5 +21,7 @@ import { DefaultNvlContainer } from "./elements/nvl/DefaultNvlContainer";
 import { NvlDialogList, DefaultNvlDialogItem } from "./elements/nvl/NvlDialogList";
 import { NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible } from "./elements/nvl/NvlContext";
 export type { DialogAvatarContext } from "./elements/say/Avatar";
-export type { TextsPreviewInput, TextsPreviewLoop, TextsPreviewProps } from "./elements/say/Sentence";
+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, };