narraleaf-react 0.9.1 → 0.10.1

package/README.md

@@ -1,165 +1,165 @@
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-transparent.png">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
-  <img alt="NarraLeaf Logo" src="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
-</picture>
-
-<h1 align="center">NarraLeaf-React</h1>
-
-<h4 align="center">A React visual novel player framework</h4>
-
-<p align="center">English | <a href="docs/README.zh-CN.md">简体中文</a></p>
-
-
-## What is NarraLeaf-React?
-
-NarraLeaf-React is a lightweight front-end visual novel player.  
-NL focuses on visual novel playing, so the user interface can be customized very easily.
-
-It doesn't use any rendering libraries and can be used on any web platform (e.g. Electron)
-
-## Why NarraLeaf-React?
-
-- **Lightweight**: NarraLeaf-React is a front-end framework, and it doesn't use any rendering libraries.
-- **Customizable**: You can customize the UI as you like, even replace the whole components.
-- **Easy to use**: It is easy to use and has a simple API that is built for developers. Based on OOP principles.
-
-### Scripting
-
-NarraLeaf-React uses TypeScript for all scripting, so you don't have to learn a whole new language to use it.
-
-It also has a highly abstracted and easy-to-use API, for example:
-
-```typescript
-import {Character, Menu, Scene, c, b} from "narraleaf-react";
-```
-
-```typescript
-const scene1 = new Scene("Scene1: Hello World", {
-  background: "/link/to/background.jpg",
-});
-
-const jS = new Character("John Smith");
-const jD = new Character("John Doe");
-
-scene1.action([
-  jS`Hello, world!`,
-  jS`This is my first ${b("NarraLeaf")} story.`,
-  jS`Start editing ${c("src/story.js", "#00f")} and enjoy the journey!`,
-
-  jD`Also, don't forget to check out the ${c("documentation", "#00f")}!`,
-
-  "By the way, the documentation is available on https://www.narraleaf.com/docs/narraleaf-react",
-  "You can also visit the website for demo and more information.",
-
-  Menu.prompt("Start the journey")
-
-    .choose("Yes I will!", [
-      jS`Great! Let's start the journey!`,
-      jS`You can open issues on GitHub if you have any questions.`
-    ])
-
-    .choose("No, I'm going to check the documentation", [
-      jS`Sure! Take your time!`
-    ])
-]);
-```
-
-For more information, please visit the [NarraLeaf-React documentation](https://www.narraleaf.com/docs/narraleaf-react).
-
-## Get Started
-
-### Install
-
-```bash
-npm install narraleaf-react
-```
-
-### Documentation
-
-- [Introduction](https://www.narraleaf.com/docs/narraleaf-react)
-- [Quick Start](https://www.narraleaf.com/docs/narraleaf-react/quick-start)
-- [Installation](https://www.narraleaf.com/docs/narraleaf-react/installation)
-- [Basic](https://www.narraleaf.com/docs/narraleaf-react/basic)
-  - [Create a Scene](https://www.narraleaf.com/docs/narraleaf-react/basic/create-scene)
-  - [Add Actions](https://www.narraleaf.com/docs/narraleaf-react/basic/add-actions)
-  - [Show Dialog](https://www.narraleaf.com/docs/narraleaf-react/basic/show-dialog)
-  - [Show Image](https://www.narraleaf.com/docs/narraleaf-react/basic/show-image)
-  - [Play Story](https://www.narraleaf.com/docs/narraleaf-react/basic/play-story)
-  - [Make Choices](https://www.narraleaf.com/docs/narraleaf-react/basic/make-choices)
-  - [Play Sound](https://www.narraleaf.com/docs/narraleaf-react/basic/sound)
-  - [Store Data](https://www.narraleaf.com/docs/narraleaf-react/basic/store-data)
-  - [Conditional](https://www.narraleaf.com/docs/narraleaf-react/basic/conditional)
-  - [Voice](https://www.narraleaf.com/docs/narraleaf-react/basic/voice)
-  - [Manage Preferences](https://www.narraleaf.com/docs/narraleaf-react/basic/manage-preferences)
-- [Solutions](https://www.narraleaf.com/docs/narraleaf-react/solutions)
-  - [Customizing the Font](https://www.narraleaf.com/docs/narraleaf-react/solutions/font)
-  - [Migration from Ren'Py](https://www.narraleaf.com/docs/narraleaf-react/solutions/from-renpy)
-  - [Quick Menu](https://www.narraleaf.com/docs/narraleaf-react/solutions/quick-menu)
-  - [Dialog Avatar](https://www.narraleaf.com/docs/narraleaf-react/solutions/dialog-avatar)
-  - [Custom Dialog](https://www.narraleaf.com/docs/narraleaf-react/solutions/custom-dialog)
-  - [Custom NVL Dialog](https://www.narraleaf.com/docs/narraleaf-react/solutions/custom-nvl-dialog)
-  - [Custom Menu](https://www.narraleaf.com/docs/narraleaf-react/solutions/custom-menu)
-  - [Page Overlay Settings](https://www.narraleaf.com/docs/narraleaf-react/solutions/page-overlay-settings)
-  - [Save System with localStorage](https://www.narraleaf.com/docs/narraleaf-react/solutions/save-system-localstorage)
-  - [Custom Notification](https://www.narraleaf.com/docs/narraleaf-react/solutions/custom-notification)
-  - [Gallery Service with localStorage](https://www.narraleaf.com/docs/narraleaf-react/solutions/gallery-service-localstorage)
-- [Core](https://www.narraleaf.com/docs/narraleaf-react/core)
-  - [Elements](https://www.narraleaf.com/docs/narraleaf-react/core/elements)
-    - [Scene](https://www.narraleaf.com/docs/narraleaf-react/core/elements/scene)
-    - [Character](https://www.narraleaf.com/docs/narraleaf-react/core/elements/character)
-      - [Sentence](https://www.narraleaf.com/docs/narraleaf-react/core/elements/character/sentence)
-      - [Word](https://www.narraleaf.com/docs/narraleaf-react/core/elements/character/word)
-      - [Pause](https://www.narraleaf.com/docs/narraleaf-react/core/elements/character/pause)
-    - [Image](https://www.narraleaf.com/docs/narraleaf-react/core/elements/image)
-    - [Sound](https://www.narraleaf.com/docs/narraleaf-react/core/elements/sound)
-    - [Menu](https://www.narraleaf.com/docs/narraleaf-react/core/elements/menu)
-    - [Script](https://www.narraleaf.com/docs/narraleaf-react/core/elements/script)
-    - [Condition](https://www.narraleaf.com/docs/narraleaf-react/core/elements/condition)
-    - [Control](https://www.narraleaf.com/docs/narraleaf-react/core/elements/control)
-    - [Text](https://www.narraleaf.com/docs/narraleaf-react/core/elements/text)
-    - [Persistent](https://www.narraleaf.com/docs/narraleaf-react/core/elements/persistent)
-    - [Story](https://www.narraleaf.com/docs/narraleaf-react/core/elements/story)
-    - [Displayable](https://www.narraleaf.com/docs/narraleaf-react/core/elements/displayable)
-    - [Layer](https://www.narraleaf.com/docs/narraleaf-react/core/elements/layer)
-    - [Service](https://www.narraleaf.com/docs/narraleaf-react/core/elements/service)
-    - [Video](https://www.narraleaf.com/docs/narraleaf-react/core/elements/video)
-    - [Built-in Gallery](https://www.narraleaf.com/docs/narraleaf-react/core/elements/built-in/gallery)
-  - [Animation](https://www.narraleaf.com/docs/narraleaf-react/core/animation)
-    - [Transform](https://www.narraleaf.com/docs/narraleaf-react/core/animation/transform)
-    - [Transitions](https://www.narraleaf.com/docs/narraleaf-react/core/animation/transition)
-  - [Game](https://www.narraleaf.com/docs/narraleaf-react/core/game)
-    - [LiveGame](https://www.narraleaf.com/docs/narraleaf-react/core/game/live-game)
-    - [Storable](https://www.narraleaf.com/docs/narraleaf-react/core/game/storable)
-    - [Preference](https://www.narraleaf.com/docs/narraleaf-react/core/game/preference/preference)
-    - [Key Map](https://www.narraleaf.com/docs/narraleaf-react/core/game/key-map)
-    - [Hooks](https://www.narraleaf.com/docs/narraleaf-react/core/game/hooks)
-  - [Plugin](https://www.narraleaf.com/docs/narraleaf-react/core/plugin)
-  - [Utils](https://www.narraleaf.com/docs/narraleaf-react/core/utils)
-- [Player](https://www.narraleaf.com/docs/narraleaf-react/player)
-  - [Player](https://www.narraleaf.com/docs/narraleaf-react/player/player)
-  - [FixedAspectRatioContainer](https://www.narraleaf.com/docs/narraleaf-react/player/fixed-aspect-ratio-container)
-  - [GameProviders](https://www.narraleaf.com/docs/narraleaf-react/player/game-providers)
-  - [Hooks](https://www.narraleaf.com/docs/narraleaf-react/player/hooks)
-  - [LayoutRouter](https://www.narraleaf.com/docs/narraleaf-react/player/page-router)
-  - [Dialog](https://www.narraleaf.com/docs/narraleaf-react/player/dialog)
-  - [Notification](https://www.narraleaf.com/docs/narraleaf-react/player/notification)
-  - [Menu](https://www.narraleaf.com/docs/narraleaf-react/player/menu)
-  - [NvlContainer](https://www.narraleaf.com/docs/narraleaf-react/player/nvl-container)
-- About
-  - [License](https://www.narraleaf.com/docs/narraleaf-react/info/license)
-  - [Incompatible Changes](https://www.narraleaf.com/docs/narraleaf-react/info/incompatible-changes)
-
-Read more in the [NarraLeaf-React documentation](https://www.narraleaf.com/docs/narraleaf-react).
-
-## License
-
-> NarraLeaf-React is licensed under the MPL-2.0 License.
->
-> We updated the license to MPL-2.0 on 2024-9-24.
-
-## Contributing
-
-We welcome all contributions.  
-If you have any ideas, just open an issue or a pull request.
-
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-transparent.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
+  <img alt="NarraLeaf Logo" src="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
+</picture>
+
+<h1 align="center">NarraLeaf-React</h1>
+
+<h4 align="center">A React visual novel player framework</h4>
+
+<p align="center">English | <a href="docs/README.zh-CN.md">简体中文</a></p>
+
+
+## What is NarraLeaf-React?
+
+NarraLeaf-React is a lightweight front-end visual novel player.  
+NL focuses on visual novel playing, so the user interface can be customized very easily.
+
+It doesn't use any rendering libraries and can be used on any web platform (e.g. Electron)
+
+## Why NarraLeaf-React?
+
+- **Lightweight**: NarraLeaf-React is a front-end framework, and it doesn't use any rendering libraries.
+- **Customizable**: You can customize the UI as you like, even replace the whole components.
+- **Easy to use**: It is easy to use and has a simple API that is built for developers. Based on OOP principles.
+
+### Scripting
+
+NarraLeaf-React uses TypeScript for all scripting, so you don't have to learn a whole new language to use it.
+
+It also has a highly abstracted and easy-to-use API, for example:
+
+```typescript
+import {Character, Menu, Scene, c, b} from "narraleaf-react";
+```
+
+```typescript
+const scene1 = new Scene("Scene1: Hello World", {
+  background: "/link/to/background.jpg",
+});
+
+const jS = new Character("John Smith");
+const jD = new Character("John Doe");
+
+scene1.action([
+  jS`Hello, world!`,
+  jS`This is my first ${b("NarraLeaf")} story.`,
+  jS`Start editing ${c("src/story.js", "#00f")} and enjoy the journey!`,
+
+  jD`Also, don't forget to check out the ${c("documentation", "#00f")}!`,
+
+  "By the way, the documentation is available on https://www.narraleaf.com/docs/narraleaf-react",
+  "You can also visit the website for demo and more information.",
+
+  Menu.prompt("Start the journey")
+
+    .choose("Yes I will!", [
+      jS`Great! Let's start the journey!`,
+      jS`You can open issues on GitHub if you have any questions.`
+    ])
+
+    .choose("No, I'm going to check the documentation", [
+      jS`Sure! Take your time!`
+    ])
+]);
+```
+
+For more information, please visit the [NarraLeaf-React documentation](https://www.narraleaf.com/docs/narraleaf-react).
+
+## Get Started
+
+### Install
+
+```bash
+npm install narraleaf-react
+```
+
+### Documentation
+
+- [Introduction](https://www.narraleaf.com/docs/narraleaf-react)
+- [Quick Start](https://www.narraleaf.com/docs/narraleaf-react/quick-start)
+- [Installation](https://www.narraleaf.com/docs/narraleaf-react/installation)
+- [Basic](https://www.narraleaf.com/docs/narraleaf-react/basic)
+  - [Create a Scene](https://www.narraleaf.com/docs/narraleaf-react/basic/create-scene)
+  - [Add Actions](https://www.narraleaf.com/docs/narraleaf-react/basic/add-actions)
+  - [Show Dialog](https://www.narraleaf.com/docs/narraleaf-react/basic/show-dialog)
+  - [Show Image](https://www.narraleaf.com/docs/narraleaf-react/basic/show-image)
+  - [Play Story](https://www.narraleaf.com/docs/narraleaf-react/basic/play-story)
+  - [Make Choices](https://www.narraleaf.com/docs/narraleaf-react/basic/make-choices)
+  - [Play Sound](https://www.narraleaf.com/docs/narraleaf-react/basic/sound)
+  - [Store Data](https://www.narraleaf.com/docs/narraleaf-react/basic/store-data)
+  - [Conditional](https://www.narraleaf.com/docs/narraleaf-react/basic/conditional)
+  - [Voice](https://www.narraleaf.com/docs/narraleaf-react/basic/voice)
+  - [Manage Preferences](https://www.narraleaf.com/docs/narraleaf-react/basic/manage-preferences)
+- [Solutions](https://www.narraleaf.com/docs/narraleaf-react/solutions)
+  - [Customizing the Font](https://www.narraleaf.com/docs/narraleaf-react/solutions/font)
+  - [Migration from Ren'Py](https://www.narraleaf.com/docs/narraleaf-react/solutions/from-renpy)
+  - [Quick Menu](https://www.narraleaf.com/docs/narraleaf-react/solutions/quick-menu)
+  - [Dialog Avatar](https://www.narraleaf.com/docs/narraleaf-react/solutions/dialog-avatar)
+  - [Custom Dialog](https://www.narraleaf.com/docs/narraleaf-react/solutions/custom-dialog)
+  - [Custom NVL Dialog](https://www.narraleaf.com/docs/narraleaf-react/solutions/custom-nvl-dialog)
+  - [Custom Menu](https://www.narraleaf.com/docs/narraleaf-react/solutions/custom-menu)
+  - [Page Overlay Settings](https://www.narraleaf.com/docs/narraleaf-react/solutions/page-overlay-settings)
+  - [Save System with localStorage](https://www.narraleaf.com/docs/narraleaf-react/solutions/save-system-localstorage)
+  - [Custom Notification](https://www.narraleaf.com/docs/narraleaf-react/solutions/custom-notification)
+  - [Gallery Service with localStorage](https://www.narraleaf.com/docs/narraleaf-react/solutions/gallery-service-localstorage)
+- [Core](https://www.narraleaf.com/docs/narraleaf-react/core)
+  - [Elements](https://www.narraleaf.com/docs/narraleaf-react/core/elements)
+    - [Scene](https://www.narraleaf.com/docs/narraleaf-react/core/elements/scene)
+    - [Character](https://www.narraleaf.com/docs/narraleaf-react/core/elements/character)
+      - [Sentence](https://www.narraleaf.com/docs/narraleaf-react/core/elements/character/sentence)
+      - [Word](https://www.narraleaf.com/docs/narraleaf-react/core/elements/character/word)
+      - [Pause](https://www.narraleaf.com/docs/narraleaf-react/core/elements/character/pause)
+    - [Image](https://www.narraleaf.com/docs/narraleaf-react/core/elements/image)
+    - [Sound](https://www.narraleaf.com/docs/narraleaf-react/core/elements/sound)
+    - [Menu](https://www.narraleaf.com/docs/narraleaf-react/core/elements/menu)
+    - [Script](https://www.narraleaf.com/docs/narraleaf-react/core/elements/script)
+    - [Condition](https://www.narraleaf.com/docs/narraleaf-react/core/elements/condition)
+    - [Control](https://www.narraleaf.com/docs/narraleaf-react/core/elements/control)
+    - [Text](https://www.narraleaf.com/docs/narraleaf-react/core/elements/text)
+    - [Persistent](https://www.narraleaf.com/docs/narraleaf-react/core/elements/persistent)
+    - [Story](https://www.narraleaf.com/docs/narraleaf-react/core/elements/story)
+    - [Displayable](https://www.narraleaf.com/docs/narraleaf-react/core/elements/displayable)
+    - [Layer](https://www.narraleaf.com/docs/narraleaf-react/core/elements/layer)
+    - [Service](https://www.narraleaf.com/docs/narraleaf-react/core/elements/service)
+    - [Video](https://www.narraleaf.com/docs/narraleaf-react/core/elements/video)
+    - [Built-in Gallery](https://www.narraleaf.com/docs/narraleaf-react/core/elements/built-in/gallery)
+  - [Animation](https://www.narraleaf.com/docs/narraleaf-react/core/animation)
+    - [Transform](https://www.narraleaf.com/docs/narraleaf-react/core/animation/transform)
+    - [Transitions](https://www.narraleaf.com/docs/narraleaf-react/core/animation/transition)
+  - [Game](https://www.narraleaf.com/docs/narraleaf-react/core/game)
+    - [LiveGame](https://www.narraleaf.com/docs/narraleaf-react/core/game/live-game)
+    - [Storable](https://www.narraleaf.com/docs/narraleaf-react/core/game/storable)
+    - [Preference](https://www.narraleaf.com/docs/narraleaf-react/core/game/preference/preference)
+    - [Key Map](https://www.narraleaf.com/docs/narraleaf-react/core/game/key-map)
+    - [Hooks](https://www.narraleaf.com/docs/narraleaf-react/core/game/hooks)
+  - [Plugin](https://www.narraleaf.com/docs/narraleaf-react/core/plugin)
+  - [Utils](https://www.narraleaf.com/docs/narraleaf-react/core/utils)
+- [Player](https://www.narraleaf.com/docs/narraleaf-react/player)
+  - [Player](https://www.narraleaf.com/docs/narraleaf-react/player/player)
+  - [FixedAspectRatioContainer](https://www.narraleaf.com/docs/narraleaf-react/player/fixed-aspect-ratio-container)
+  - [GameProviders](https://www.narraleaf.com/docs/narraleaf-react/player/game-providers)
+  - [Hooks](https://www.narraleaf.com/docs/narraleaf-react/player/hooks)
+  - [LayoutRouter](https://www.narraleaf.com/docs/narraleaf-react/player/page-router)
+  - [Dialog](https://www.narraleaf.com/docs/narraleaf-react/player/dialog)
+  - [Notification](https://www.narraleaf.com/docs/narraleaf-react/player/notification)
+  - [Menu](https://www.narraleaf.com/docs/narraleaf-react/player/menu)
+  - [NvlContainer](https://www.narraleaf.com/docs/narraleaf-react/player/nvl-container)
+- About
+  - [License](https://www.narraleaf.com/docs/narraleaf-react/info/license)
+  - [Incompatible Changes](https://www.narraleaf.com/docs/narraleaf-react/info/incompatible-changes)
+
+Read more in the [NarraLeaf-React documentation](https://www.narraleaf.com/docs/narraleaf-react).
+
+## License
+
+> NarraLeaf-React is licensed under the MPL-2.0 License.
+>
+> We updated the license to MPL-2.0 on 2024-9-24.
+
+## Contributing
+
+We welcome all contributions.  
+If you have any ideas, just open an issue or a pull request.
+

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
      *