narraleaf-react 0.13.1 → 0.14.0

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/action/gameHistory.d.ts

@@ -1,3 +1,4 @@
+import type { SerializedGameHistory, SerializedGameState } from "../gameTypes";
 import { Action } from "./action";
 import { ActionHistoryManager } from "./actionHistory";
 type GameHistoryAction = {
@@ -5,7 +6,7 @@ type GameHistoryAction = {
     action: Action;
     isPending?: boolean;
 };
-type GameElementHistory = {
+export type GameElementHistory = {
     type: "say";
     text: string;
     voice: string | null;
@@ -17,6 +18,12 @@ type GameElementHistory = {
 };
 export type GameHistory = GameHistoryAction & {
     element: GameElementHistory;
+    /**
+     * Self-contained core state captured when this line was reached, used to restore the game
+     * back to this backlog line (see {@link LiveGame.restoreToHistory}). Optional because a
+     * capture can fail, and legacy in-memory entries created before a snapshot was taken.
+     */
+    snapshot?: SerializedGameState | null;
 };
 export declare class GameHistoryManager {
     private history;
@@ -24,7 +31,28 @@ export declare class GameHistoryManager {
     constructor(actionHistoryMgr: ActionHistoryManager);
     push(action: GameHistory): this;
     getHistory(): GameHistory[];
+    getByToken(token: string): GameHistory | null;
+    /**
+     * Serialize the whole backlog for persistence (save format v2).
+     */
+    serialize(): SerializedGameHistory[];
+    /**
+     * Serialize the backlog up to and including the entry with the given token.
+     *
+     * Used by restore-to-history to trim the backlog back to the restored line.
+     * Returns an empty array if the token is not found.
+     */
+    serializeUntil(token: string): SerializedGameHistory[];
+    /**
+     * Rebuild the backlog from persisted entries.
+     *
+     * Each entry is re-bound to a live {@link Action} through `actionMap`; entries whose action no
+     * longer exists (the script changed since the save) are dropped rather than throwing, so a
+     * still-loadable save degrades to a shorter backlog instead of failing.
+     */
+    load(entries: SerializedGameHistory[], actionMap: ReadonlyMap<string, Action>): void;
     reset(): void;
+    private static toSerialized;
     updateByToken(id: string, handler: (result: GameHistory | null) => void): void;
     resolvePending(id: string): void;
     private crossFilter;

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

@@ -59,6 +59,18 @@ export declare class LiveGame {
      * - If the id is not provided, it will undo **the last action**
      */
     undo(id?: string): void;
+    /**
+     * Restore the game to a past backlog line.
+     *
+     * Unlike {@link undo}, this works **after loading a save**: it does not rely on the
+     * (non-serializable) undo stack. Every backlog entry carries a self-contained state snapshot,
+     * so restoring re-applies that snapshot and trims the backlog back to that line.
+     *
+     * @param token - the backlog entry token (as returned by {@link getHistory})
+     * @returns `true` if the line was restored, `false` if the token is unknown or the entry has
+     *          no restore snapshot.
+     */
+    restoreToHistory(token: string): boolean;
     /**
      * Notify the player with a message
      *
@@ -74,6 +86,35 @@ export declare class LiveGame {
      * Skip the current dialog
      */
     skipDialog(): void;
+    /**
+     * Fast-forward playback to the next menu (or the end of the story).
+     *
+     * Every line in between is executed for real, so the backlog and its restore snapshots
+     * accumulate exactly as in normal play — only faster and silent. Audio is muted for the
+     * duration, in-flight transitions are settled immediately, and timed pauses (`Control.sleep`,
+     * auto-forward) resolve at once. It stops as soon as a menu is waiting for a choice, so the
+     * choice itself is always left to the player.
+     *
+     * Because history accumulates the whole way, {@link getHistory} and
+     * {@link restoreToHistory} cover the fast-forwarded span just like normal play.
+     *
+     * ```typescript
+     * // Jump ahead to the next decision point.
+     * await game.getLiveGame().fastForward();
+     * ```
+     *
+     * @param options.until - `"menu"` (default) stops at the next menu; `"end"` runs until the
+     *                         story finishes.
+     * @param options.maxSteps - safety bound on the number of advance steps (defaults to the
+     *                           `maxStackModelLoop` config).
+     * @returns why it stopped: `"menu"`, `"end"` (the stack drained), or `"maxSteps"`.
+     */
+    fastForward(options?: {
+        until?: "menu" | "end";
+        maxSteps?: number;
+    }): Promise<{
+        reason: "menu" | "end" | "maxSteps";
+    }>;
     private assertScreenshot;
     /**
      * Capture the game screenshot, will only include the player element

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

@@ -7,8 +7,17 @@ import { PlayerStateData } from "../player/gameState";
 import { GuardConfig } from "../player/guard";
 import React from "react";
 import { StackModel, StackModelRawData } from "./action/stackModel";
+import type { GameElementHistory } from "./action/gameHistory";
 import { MenuComponent, NotificationComponent, NvlDialogComponent, SayComponent } from "./common/player";
 import { LiveGameEventToken } from "./types";
+/**
+ * Current save format version.
+ *
+ * - v1 (undefined on the save): core resume state only, no backlog history.
+ * - v2: adds `game.history`, a full backlog where every entry carries a self-contained
+ *   restore snapshot, so loading a save keeps the backlog and any past line can be restored.
+ */
+export declare const SAVE_FORMAT_VERSION = 2;
 export interface SavedGameMetaData {
     /**
      * The timestamp of when the game was created
@@ -34,21 +43,63 @@ export interface SavedGameMetaData {
      * The hash of the story is used to check whether the stories are compatible.
      */
     storyHash: string;
+    /**
+     * The save format version (see {@link SAVE_FORMAT_VERSION}).
+     *
+     * Absent on legacy (v1) saves written before backlog history existed.
+     */
+    version?: number;
+}
+/**
+ * The core, resumable game state — everything needed to restore the game to a point,
+ * **without** the backlog history.
+ *
+ * This is the unit captured per backlog entry (see {@link SerializedGameHistory}); it is
+ * deliberately history-free so that per-entry snapshots do not nest the whole backlog inside
+ * themselves (which would make saves grow exponentially).
+ */
+export interface SerializedGameState {
+    store: {
+        [key: string]: SerializedNamespaceData;
+    };
+    elementStates: RawData<ElementStateRaw>[];
+    stage: PlayerStateData;
+    services: {
+        [key: string]: unknown;
+    };
+    stackModel: StackModelRawData;
+    asyncStackModels: StackModelRawData[];
+}
+/**
+ * A single persisted backlog line: the rendered say/menu content, a stable action anchor, and a
+ * self-contained snapshot that restores the game to exactly this line.
+ */
+export interface SerializedGameHistory {
+    /**
+     * Stable action id anchor (`action.getId()`). Used to re-bind the entry to the live story on
+     * load; entries whose action no longer exists (script changed) are dropped from the backlog.
+     */
+    actionId: string | null;
+    element: GameElementHistory;
+    isPending?: boolean;
+    /**
+     * Core game state captured when this line was reached. Restoring it returns the game to this
+     * exact line. `null` when a snapshot could not be captured (the line stays visible but is not
+     * restorable).
+     */
+    snapshot: SerializedGameState | null;
 }
 export interface SavedGame {
     name: string;
     meta: SavedGameMetaData;
-    game: {
-        store: {
-            [key: string]: SerializedNamespaceData;
-        };
-        elementStates: RawData<ElementStateRaw>[];
-        stage: PlayerStateData;
-        services: {
-            [key: string]: unknown;
-        };
-        stackModel: StackModelRawData;
-        asyncStackModels: StackModelRawData[];
+    game: SerializedGameState & {
+        /**
+         * Full backlog with per-entry restore snapshots (save format v2+).
+         *
+         * Absent on legacy saves; a missing/empty history simply means loading starts with an
+         * empty backlog, exactly as before this feature existed.
+         */
+        history?: SerializedGameHistory[];
     };
 }
 export type GameConfig = {
@@ -399,7 +450,7 @@ export type GamePreference = {
      * This is used to prevent the game from skipping actions too quickly when the player presses the skip key.
      *
      * Set to 0 to skip actions immediately when the player presses the skip key.
-     * @default 500
+     * @default 0
      */
     skipDelay: number;
     /**

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

@@ -3,3 +3,5 @@ export type ImageEvents = {
     "event:image.onLoad": [];
 };
 export declare function stackStyle(darkness: number): React.CSSProperties;
+declare const Image: React.MemoExoticComponent<typeof ImageComponent>;
+export default Image;

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

@@ -178,6 +178,7 @@ export declare class GameState {
     private stageClickBuffer;
     private readonly nvlAdvanceWaiters;
     private advDialogState;
+    private _fastForwarding;
     constructor(game: Game, stage: StageUtils);
     get deps(): number;
     addVideo(video: Video): this;

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

@@ -26,6 +26,7 @@ export type ExposedState = {
     [ExposedStateType.image]: {
         createWearable: (wearable: Image) => void;
         disposeWearable: (wearable: Image) => void;
+        flush: () => void;
         events: EventDispatcher<ImageEvents>;
         initDisplayable: (onResolve: () => void) => Timeline;
         applyTransform: (transform: Transform, onResolve: () => void) => Timeline;