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

@@ -4,4 +4,17 @@ import { MaskTransition } from "../elements/transition/transitions/image/maskTra
 import { Transition } from "../elements/transition/transition";
 import { ImageTransition } from "../elements/transition/transitions/image/imageTransition";
 import { TextTransition } from "../elements/transition/transitions/text/textTransition";
-export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, MaskTransition, };
+import { SoftWipe } from "../elements/transition/transitions/image/softWipe";
+import { Blinds } from "../elements/transition/transitions/image/blinds";
+import { SoftIris } from "../elements/transition/transitions/image/softIris";
+import { BlurDissolve } from "../elements/transition/transitions/image/blurDissolve";
+import { Push } from "../elements/transition/transitions/image/push";
+import { ThroughColor } from "../elements/transition/transitions/image/throughColor";
+export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, MaskTransition, SoftWipe, Blinds, SoftIris, BlurDissolve, Push, ThroughColor, };
+export type { SoftWipeOptions } from "../elements/transition/transitions/image/softWipe";
+export type { BlindsOptions } from "../elements/transition/transitions/image/blinds";
+export type { SoftIrisOptions } from "../elements/transition/transitions/image/softIris";
+export type { BlurDissolveOptions } from "../elements/transition/transitions/image/blurDissolve";
+export type { PushOptions } from "../elements/transition/transitions/image/push";
+export type { ThroughColorFadeOptions, ThroughColorWipeOptions, ThroughColorBlindsOptions, ThroughColorIrisOptions, } from "../elements/transition/transitions/image/throughColor";
+export type { BlindsOrientation } from "../elements/transition/transitions/image/transitionMaskUtils";

package/dist/game/nlcore/elements/built-in/DevTools.d.ts

@@ -2,6 +2,7 @@ import { ControlAction } from "../../action/actions/controlAction";
 import { Chained, Proxied } from "../../action/chain";
 import { GameState } from "../../common/game";
 import { LogicAction } from "../../game";
+import { Layer } from "../layer";
 import { DynamicPersistent, Persistent } from "../persistent";
 import { Scene } from "../scene";
 export declare class DevTools {
@@ -13,5 +14,40 @@ export declare class DevTools {
     static wrapAction(action: LogicAction.Actions[] | Proxied<LogicAction.GameElement, Chained<LogicAction.Actions>>): ControlAction;
     static getNamespaceName(persistent: Persistent<any>): string;
     static getCurrentScene(gameState: GameState): Scene | null;
+    /**
+     * Register a displayable into a scene's render tree without emitting a `displayable:init`
+     * action. The element renders immediately at its constructor-config transform state
+     * (visibility is governed by `opacity > 0`).
+     *
+     * Intended for editor hosts that pre-pose a stage: construct elements with their computed
+     * state as constructor config (config state survives `element.reset()` / `newGame()`), then
+     * register them from a `Script` action or after mount.
+     */
+    static registerDisplayable(gameState: GameState, displayable: LogicAction.DisplayableElements, scene?: Scene | null, layer?: Layer | null): void;
+    /**
+     * Assign an explicit element id. Elements reachable from a scene's action tree receive
+     * generated ids (`e-0`, `e-1`, ...) at story construction, but elements registered directly
+     * via {@link registerDisplayable} are outside the tree and would otherwise share the default
+     * id — colliding as React keys. Editor hosts should give those elements unique ids
+     * (use a distinct prefix so they never collide with generated ids).
+     */
+    static setElementId(element: LogicAction.GameElement, id: string): void;
+    /**
+     * Read a displayable's current transform-state props (position/opacity/zoom/rotation/scale/
+     * effects...). Returns a shallow copy. Intended for editor hosts capturing a live pose
+     * (e.g. prefilling a motion editor with an element's current stage state).
+     */
+    static getDisplayableTransformProps(displayable: LogicAction.DisplayableElements): Record<string, unknown>;
+    /**
+     * Overwrite a displayable's transform-state props with no animation and push the result to
+     * the DOM immediately when the element is mounted. With `merge: false` the previous state is
+     * discarded entirely; by default the given props are merged over the current state.
+     *
+     * Throws if the transform state is locked by an in-flight transform — editor hosts should
+     * only inject while the stage is idle.
+     */
+    static setDisplayableTransformProps(gameState: GameState, displayable: LogicAction.DisplayableElements, props: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): void;
     static DynamicPersistent: typeof DynamicPersistent;
 }

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

@@ -0,0 +1,28 @@
+import { TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
+import { BlindsOrientation } from "../../../../elements/transition/transitions/image/transitionMaskUtils";
+type AnimationType = [TransitionAnimationType.Number];
+export type BlindsOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /** Slat orientation. @default "horizontal" */
+    orientation?: BlindsOrientation;
+    /** Number of slats. @default 8 */
+    slats?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * Venetian "blinds": the target image is revealed over the previous one through
+ * a set of hard-edged slats that widen until they cover the frame.
+ */
+export declare class Blinds extends ImageTransition<AnimationType> {
+    private duration;
+    private orientation;
+    private slats;
+    private easing?;
+    constructor(options: BlindsOptions);
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    copy(): Blinds;
+}
+export {};

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

@@ -0,0 +1,24 @@
+import { TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
+type AnimationType = [TransitionAnimationType.Number];
+export type BlurDissolveOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /** Peak blur radius applied at the crossover, in pixels. @default 16 */
+    blur?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * A blur dissolve: the previous image blurs out and fades while the target one
+ * sharpens in — the dreamy crossfade used for flashbacks / dream states.
+ */
+export declare class BlurDissolve extends ImageTransition<AnimationType> {
+    private duration;
+    private blur;
+    private easing?;
+    constructor(options: BlurDissolveOptions);
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    copy(): BlurDissolve;
+}
+export {};

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

@@ -0,0 +1,31 @@
+import { TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
+type AnimationType = [TransitionAnimationType.Number];
+export type PushOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /** Direction the previous image travels toward. @default "left" */
+    direction?: TransformDefinitions.WipeDirection;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * A push / slide: the target image slides in from one edge while the previous
+ * 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.
+ */
+export declare class Push extends ImageTransition<AnimationType> {
+    private duration;
+    private direction;
+    private easing?;
+    constructor(options: PushOptions);
+    private axisUnit;
+    private translate;
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    copy(): Push;
+}
+export {};

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

@@ -0,0 +1,28 @@
+import { TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
+type AnimationType = [TransitionAnimationType.Number];
+export type SoftIrisOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /** Centre of the iris, as a CSS position. @default "50% 50%" */
+    center?: string;
+    /** Width of the soft (feathered) edge band, in percent. @default 12 */
+    feather?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * A soft, feathered iris: the target image is revealed over the previous one
+ * through an expanding `radial-gradient` circle with a feathered edge — the
+ * soft-edged counterpart of {@link MaskTransition.circle}.
+ */
+export declare class SoftIris extends ImageTransition<AnimationType> {
+    private duration;
+    private center;
+    private feather;
+    private easing?;
+    constructor(options: SoftIrisOptions);
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    copy(): SoftIris;
+}
+export {};

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

@@ -0,0 +1,28 @@
+import { TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
+type AnimationType = [TransitionAnimationType.Number];
+export type SoftWipeOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /** Direction the wipe travels toward. @default "left" */
+    direction?: TransformDefinitions.WipeDirection;
+    /** Width of the soft (feathered) edge band, in percent. @default 12 */
+    feather?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * A soft, feathered directional wipe. The target image is revealed over the
+ * previous one through a moving `linear-gradient` alpha mask, giving a gradual
+ * erase rather than the hard geometric cut of {@link MaskTransition.wipe}.
+ */
+export declare class SoftWipe extends ImageTransition<AnimationType> {
+    private duration;
+    private direction;
+    private feather;
+    private easing?;
+    constructor(options: SoftWipeOptions);
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    copy(): SoftWipe;
+}
+export {};

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

@@ -0,0 +1,67 @@
+import { TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
+import { BlindsOrientation } from "../../../../elements/transition/transitions/image/transitionMaskUtils";
+type AnimationType = [TransitionAnimationType.Number];
+type ThroughColorBaseOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /** Hold colour. @default "#000000" */
+    color?: string;
+    /** Fraction (0–1) of the duration spent fully covered by the colour. @default 0.3 */
+    hold?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+export type ThroughColorFadeOptions = ThroughColorBaseOptions;
+export type ThroughColorWipeOptions = ThroughColorBaseOptions & {
+    /** Direction the feathered edge travels toward. @default "left" */
+    direction?: TransformDefinitions.WipeDirection;
+    /** Width of the soft edge band, in percent. @default 12 */
+    feather?: number;
+};
+export type ThroughColorBlindsOptions = ThroughColorBaseOptions & {
+    /** Slat orientation. @default "horizontal" */
+    orientation?: BlindsOrientation;
+    /** Number of slats. @default 8 */
+    slats?: number;
+};
+export type ThroughColorIrisOptions = ThroughColorBaseOptions & {
+    /** Centre of the iris, as a CSS position. @default "50% 50%" */
+    center?: string;
+    /** Width of the soft edge band, in percent. @default 12 */
+    feather?: number;
+};
+/**
+ * The "through colour" engine. A colour overlay covers the frame using the
+ * chosen pattern, holds a solid-colour frame, then uncovers to reveal the
+ * target image — so the target never appears until *after* the colour hold. The
+ * previous/target images simply swap opacity at the midpoint, unseen behind the
+ * fully-covered frame.
+ *
+ * Created through its static factories (mirroring {@link MaskTransition}):
+ * - {@link ThroughColor.fade}   — the overlay fades in/out (fade-to-black/white; `hold: 0` = flash).
+ * - {@link ThroughColor.wipe}   — a feathered directional edge (soft wipe through the colour).
+ * - {@link ThroughColor.blinds} — venetian slats (blinds through the colour).
+ * - {@link ThroughColor.iris}   — a circle closing from the rim in (iris to the colour).
+ */
+export declare class ThroughColor extends ImageTransition<AnimationType> {
+    private duration;
+    private color;
+    private hold;
+    private coverMask;
+    private easing?;
+    private constructor();
+    /** Fade the frame to a solid colour, hold, then fade to the target. */
+    static fade(options: ThroughColorFadeOptions): ThroughColor;
+    /** Cover the frame with a feathered directional edge, hold, then uncover. */
+    static wipe(options: ThroughColorWipeOptions): ThroughColor;
+    /** Cover the frame with venetian slats, hold, then uncover. */
+    static blinds(options: ThroughColorBlindsOptions): ThroughColor;
+    /** Close a circle over the frame from the rim in, hold, then open it. */
+    static iris(options: ThroughColorIrisOptions): ThroughColor;
+    /** Style for the colour overlay at a given coverage (0 = clear, 1 = fully covered). */
+    private coverStyle;
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    copy(): ThroughColor;
+}
+export {};