narraleaf-react 0.16.0 → 0.17.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/common/transition.d.ts

@@ -5,14 +5,16 @@ import { ImageTransition } from "../elements/transition/transitions/image/imageT
 import { TextTransition } from "../elements/transition/transitions/text/textTransition";
 import { BlurDissolve } from "../elements/transition/transitions/image/blurDissolve";
 import { Push } from "../elements/transition/transitions/image/push";
+import { Darkness } from "../elements/transition/transitions/image/darkness";
 import { ThroughColor } from "../elements/transition/transitions/image/throughColor";
 import { Reveal } from "../elements/transition/transitions/image/reveal";
 import { Mask } from "../elements/transition/transitions/image/mask";
-export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, BlurDissolve, Push, ThroughColor, Reveal, Mask, };
+export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, BlurDissolve, Push, Darkness, ThroughColor, Reveal, Mask, };
 export type { DissolveOptions } from "../elements/transition/transitions/image/dissolve";
 export type { FadeInOptions } from "../elements/transition/transitions/image/fadeIn";
 export type { BlurDissolveOptions } from "../elements/transition/transitions/image/blurDissolve";
 export type { PushOptions } from "../elements/transition/transitions/image/push";
+export type { DarknessOptions } from "../elements/transition/transitions/image/darkness";
 export type { ThroughColorOptions, ThroughColorUncover, } from "../elements/transition/transitions/image/throughColor";
 export type { RevealOptions } from "../elements/transition/transitions/image/reveal";
 export type { MaskPattern, WipePatternOptions, BarnDoorPatternOptions, IrisPatternOptions, ClockPatternOptions, FanPatternOptions, BlindsPatternOptions, DotsPatternOptions, } from "../elements/transition/transitions/image/mask";

package/dist/game/nlcore/elements/character/textEvent.d.ts

@@ -34,6 +34,14 @@ export type TextEventConfig = {
  *
  * First version carries a closed set: a character-expression switch and/or a sound effect.
  *
+ * **Skip / instant reveal semantics.** Skipping the typewriter — or an instant, non-type-effect
+ * reveal that uncovers the whole sentence at once — does not drop the tokens it flies past. Every
+ * crossed token fires exactly once, in source order, so the outcome is identical to letting the
+ * typewriter reach each one in turn: the image ends in the appearance the *last* crossed token
+ * specifies, and each crossed sound effect plays once. Re-visiting an already-fired token within the
+ * same reveal is a no-op — it never double-plays a sound effect nor re-writes the expression — which
+ * is what keeps a re-mount of an already-revealed line from replaying its effects.
+ *
  * @example
  * ```ts
  * // switch Alice's portrait to "angry" the moment the typewriter reaches this point

package/dist/game/nlcore/elements/transition/transitions/image/darkness.d.ts

@@ -12,8 +12,12 @@ export type DarknessOptions = {
     easing?: TransformDefinitions.EasingDefinition;
 };
 /**
- * Darken the original image and fade in the target image at the same time.
- * Internal: drives `image.darken(x, duration)`.
+ * A brightness-dim transition: swaps to the incoming image and animates its
+ * brightness from `1 - from` to `1 - to` (darkness `0` leaves it untouched, `1`
+ * drives it fully black), replacing the outgoing image at once.
+ *
+ * This is what backs `image.darken(amount, duration)` — darkening an image in
+ * place is expressed as a transition from its current darkness to the new one.
  */
 export declare class Darkness extends ImageTransition<AnimationType> {
     private from;

package/dist/game/nlcore/elements/transition/transitions/image/push.d.ts

@@ -14,16 +14,25 @@ export type PushOptions = {
  * image slides out the opposite way, as if the camera panned.
  *
  * The offset is applied via the independent CSS `translate` property (not
- * `transform`) in viewport units. That composes additively with the layer's
- * base positioning instead of overriding it, and is the identity at offset `0`,
- * so neither image jumps at the start/end of the slide.
+ * `transform`) in **percentages of the layer's own size**. That composes
+ * additively with the layer's base positioning instead of overriding it, and is
+ * the identity at offset `0`, so neither image jumps at the start/end of the slide.
+ *
+ * Percentages — not viewport units — matter here: whichever element this drives
+ * lives inside the letterboxed stage box. On the layered render path that element
+ * is the transition stack wrapper (`inset: 0`, see `Image.tsx` `stackStyle`); on the
+ * non-layered path the style is applied to the `<img>` itself. A `100vw`/`100vh`
+ * travel is measured against the *window*, so whenever the window aspect differs
+ * from the design aspect the slide overshoots the stage and exposes the backdrop
+ * mid-transition. `100%` is measured against that element, so either way a full
+ * slide lands exactly one stage width/height away regardless of window shape.
  */
 export declare class Push extends ImageTransition<AnimationType> {
     private duration;
     private direction;
     private easing?;
     constructor(options: PushOptions);
-    private axisUnit;
+    private axisSign;
     private translate;
     createTask(): TransitionTask<HTMLImageElement, AnimationType>;
     copy(): Push;

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

@@ -0,0 +1,34 @@
+import type { Scene } from "../../../nlcore/elements/scene";
+import type { Sound } from "../../../nlcore/elements/sound";
+export type ScenePreloadPlan = {
+    /**
+     * Image urls the scene that is about to paint registers directly: its own backgrounds and
+     * images, plus the immediate background of any scene it jumps to. This tier is on the path to
+     * the first painted frame, so it is fetched unpaced and nothing is revealed until it is warm.
+     */
+    critical: string[];
+    /**
+     * Image urls belonging to the scenes reachable from here, minus anything already in
+     * {@link ScenePreloadPlan.critical}. Speculative: warmed after the critical tier, paced, and
+     * nothing waits for it.
+     */
+    lookAhead: string[];
+    /** Every url in the plan, in order — the set the cache should keep for this scene. */
+    all: string[];
+    /**
+     * Sounds this scene registers. Warmed alongside the critical tier but never gated on: the
+     * audio context can be locked until the player interacts with the page (see
+     * `AudioManager.preload`), so waiting for these could wait forever.
+     */
+    criticalAudio: Sound[];
+};
+/**
+ * Split a scene's registered image sources into what must be warm before the scene paints and what
+ * is merely likely to be needed soon.
+ *
+ * The distinction matters because a scene's `srcManager` reaches transitively: `getFutureSrc()`
+ * carries the whole asset set of every scene this one can jump to. Treating that as one preload
+ * pass meant the first frame of a large story waited on assets from scenes the player had not
+ * reached yet.
+ */
+export declare function planScenePreload(scene: Scene): ScenePreloadPlan;

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

@@ -18,6 +18,13 @@ type DialogStateConfig = {
     evaluatedWords: Word<Pausing | string | TextEvent>[];
     gameState: GameState;
     suppressInitialAnimation?: boolean;
+    /**
+     * Persistent per-reveal text-event fire guard. When supplied (NVL entries pass the set stored on
+     * their long-lived {@link NvlDialogEntry}), a re-mount of the same line reuses it and so replays
+     * neither the sound effects nor the stale expression. Left undefined for ADV, whose dialog state
+     * is already memoized per action and falls back to a per-run set.
+     */
+    firedTextEvents?: Set<TextEvent>;
 };
 export declare class DialogState {
     static Events: {

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

@@ -1,5 +1,7 @@
 import type { GameState } from "../../gameState";
 import type { TextEvent } from "../../../nlcore/elements/character/textEvent";
+import type { Word } from "../../../nlcore/elements/character/word";
+import type { Pausing } from "../../../nlcore/elements/character/pause";
 /**
  * Apply a {@link TextEvent}'s effect directly to element state — no transition, no action history,
  * no stack model. This is the "reveal semantics" seam: the typewriter calls it the moment it
@@ -17,3 +19,15 @@ export declare function dispatchTextEvent(event: TextEvent, state: GameState): v
  * a replay of the same `say` — starts with an empty set and fires again (contract 4).
  */
 export declare function fireTextEventOnce(event: TextEvent, fired: Set<TextEvent>, state: GameState): void;
+/**
+ * Land the final state of an instantly-revealed sentence: every {@link TextEvent} token in `words`
+ * fires once, in source order — the same "final state" a typewriter skip produces (contract 3).
+ *
+ * `fired` is the persistent per-reveal guard. Pass the SAME set across re-mounts of one dialog line
+ * (e.g. an NVL entry re-keyed on a phase/active change, or the whole container re-mounting) so the
+ * re-mount replays neither the sound effects nor the — now stale — expression writes. A genuinely
+ * fresh reveal (a new line, or a `say` re-evaluated on load) passes its own empty set and fires
+ * again, preserving replay safety (contract 4). Returns the tokens that actually fired this call
+ * (empty on a guarded re-mount), for tests.
+ */
+export declare function fireInstantRevealEvents(words: readonly Word<string | Pausing | TextEvent>[], fired: Set<TextEvent>, state: GameState): TextEvent[];

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 { TextEvent } from "../nlcore/elements/character/textEvent";
 import { type SceneSnapshot } from "../nlcore/action/actions/sceneAction";
 import { Logger } from "../../util/logger";
 import { Story } from "../nlcore/elements/story";
@@ -36,6 +37,13 @@ export type NvlDialogEntry = {
     character: Character | null;
     sentence: Sentence;
     text: string;
+    /**
+     * Runtime-only, per-line text-event fire guard. Lives on the long-lived entry (not the React
+     * dialog state, which is re-created on every re-mount) so the tokens a line reveals fire once and
+     * a re-mount replays nothing. Absent from {@link NvlDialogEntryData}, so a load starts a fresh
+     * reveal that fires again (replay safety). See {@link fireInstantRevealEvents}.
+     */
+    firedTextEvents?: Set<TextEvent>;
 };
 export type NvlDialogPhase = "idle" | "typing" | "awaitAdvance";
 /**

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

@@ -43,6 +43,18 @@ export declare class AudioManager {
     fromData(data: AudioManagerDataRaw, elementMap: Map<string, LogicAction.GameElement>): this;
     soundFromData(sound: SoundElement, data: AudioDataRaw): void;
     isManaged(sound: SoundElement): boolean;
+    /**
+     * Fetch and decode a sound into the audio cache without playing it, so the first `play()` of
+     * this source starts on the same frame it is asked to instead of after a fetch and a decode.
+     *
+     * Deliberately **not** something to gate a loading screen on: the audio context only becomes
+     * ready once the browser's autoplay policy is satisfied by a user gesture, so this can sit
+     * pending indefinitely on a page nobody has interacted with yet. Start it and let it land —
+     * in practice the gesture that opens a menu unlocks the context long before the scene it
+     * belongs to is entered. Failures resolve quietly; the sound then loads on first play, exactly
+     * as it did before.
+     */
+    preload(sound: SoundElement): Promise<void>;
     reset(): void;
     setGroupVolume(type: SoundType, volume: number): void;
     setGlobalVolume(volume: number): void;

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

@@ -14,19 +14,46 @@ export declare class ImageCacheManager {
      * the bytes are cached — the first reveal still pays the (async) decode cost and can paint
      * a blank frame. Decode failures are ignored: the image then simply decodes lazily on
      * first paint, exactly as before.
+     *
+     * Returns the element the decode ran on so callers can keep it alive (see
+     * {@link ImageCacheManager.preload}'s `retainDecoded`); `null` when the environment has no
+     * `Image` or no `decode()`.
      */
     private static decodeImage;
     private src;
     private preloadTasks;
+    /**
+     * Decoded images held on purpose. A decoded bitmap only stays in the browser's cache while
+     * something still references it, so dropping the element right after `decode()` lets the
+     * bitmap be evicted and the reveal decodes all over again. Retention is opt-in per preload
+     * (`retainDecoded`) because a full-resolution bitmap costs width × height × 4 bytes — worth
+     * it for the scene that is about to paint, far too expensive for a whole reachable graph.
+     */
+    private decoded;
     constructor(game: Game);
     has(name: string): boolean;
     add(name: string, src: string): this;
     remove(name: string): this;
     get(name: string): string | undefined;
+    /**
+     * Whether this source has been decoded and its decoded bitmap is still held, i.e. attaching
+     * it to an `<img>` can paint without an asynchronous decode first.
+     */
+    isDecoded(name: string): boolean;
     clear(): this;
     size(): number;
     isPreloading(src: string): boolean;
-    preload(gameState: GameState, url: string): PreloadedToken;
+    /**
+     * Fetch `url`, cache it as a data URL and decode it, resolving the returned token's
+     * `onFinished` only once the decode has settled.
+     *
+     * @param options.retainDecoded keep the decoded bitmap alive until this source leaves the
+     * cache. Use it for the assets that are about to be revealed; leave it off for speculative
+     * look-ahead preloading, whose bitmaps would otherwise pile up in memory.
+     */
+    preload(gameState: GameState, url: string, options?: {
+        retainDecoded?: boolean;
+    }): PreloadedToken;
     abortAll(): void;
     abort(src: string): void;
     preloadedSrc(): string[];