narraleaf-react 0.12.3 → 0.13.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/elements.d.ts

@@ -18,5 +18,6 @@ import { Layer } from "../elements/layer";
 import { Video } from "../elements/video";
 import { NVLToken } from "../elements/nvl";
 export { Character, Narrator, Condition, Control, Image, Lambda, Menu, NVLToken, Scene, Script, Sentence, Sound, Story, Transform, Word, Text, Pause, Persistent, Service, Layer, Video, };
+export type { LayeredDefinition, LayerGroupDefinition, LayerResolver, LayerSlot, LayerTagsOf, LayerVariants, } from "../elements/displayable/image";
 export type { SentenceMetadata } from "../elements/character/sentence";
 export type { CharacterPortraitConfig, DialogAvatar, DialogAvatarResolver, DialogAvatarResolverContext, DialogAvatarResolution, DialogAvatarSource, } from "../elements/character/avatar";

package/dist/game/nlcore/elements/displayable/image.d.ts

@@ -14,7 +14,7 @@ export type TagDefinitionObject<T extends TagGroupDefinition> = {
     resolve: TagSrcResolver<T>;
 };
 type ImageSrcType<T extends TagGroupDefinition | null = TagGroupDefinition | null> = T extends TagGroupDefinition ? TagDefinition<T> : (Color | ImageSrc);
-export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGroupDefinition | null> extends TransformDefinitions.ImageTransformProps {
+export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGroupDefinition | null, Layers extends LayerGroupDefinition = LayerGroupDefinition> extends TransformDefinitions.ImageTransformProps {
     /**
      * The name of the image, only for debugging purposes
      */
@@ -27,7 +27,7 @@ export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGro
     /**
      * Image Src, see [Image](https://react.narraleaf.com/documentation/core/elements/image) for more information
      */
-    src: ImageSrcType<Tag>;
+    src: ImageSrcType<Tag> | LayeredDefinition<Layers>;
     /**
      * Auto resize image's width to fit the screen
      * @default false
@@ -45,7 +45,40 @@ export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGro
 }
 export type TagGroupDefinition = string[][];
 export type TagSrcResolver<T extends TagGroupDefinition> = (...tags: SelectElementFromEach<T>) => string;
-export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefinition | null> extends Displayable<ImageDataRaw, Image, TransformDefinitions.ImageTransformProps> implements EventfulDisplayable {
+/**
+ * A set of mutually exclusive variants for one layer, keyed by tag.
+ *
+ * `null` means the layer draws nothing for that tag.
+ */
+export type LayerVariants = Record<string, string | null>;
+/**
+ * Derives a layer's src from the currently active tags. Declares no tags of its own.
+ */
+export type LayerResolver = (tags: ReadonlySet<string>) => string | null;
+/**
+ * One slot of a layered image, from bottom to top. Either a constant src, `null`,
+ * a {@link LayerVariants} map, or a {@link LayerResolver}.
+ */
+export type LayerSlot = string | null | LayerVariants | LayerResolver;
+export type LayerGroupDefinition = readonly LayerSlot[];
+/**
+ * The union of every tag declared by a layer stack.
+ */
+export type LayerTagsOf<L> = L extends readonly (infer E)[] ? (E extends LayerResolver ? never : E extends LayerVariants ? keyof E & string : never) : never;
+/**
+ * Layered image src, see [Image](https://react.narraleaf.com/documentation/core/elements/image).
+ */
+export type LayeredDefinition<L extends LayerGroupDefinition = LayerGroupDefinition> = {
+    /**
+     * The layer stack, from bottom to top. Array order is the stacking order.
+     */
+    layers: L;
+    /**
+     * One tag per variant layer, in any order.
+     */
+    defaults: readonly LayerTagsOf<L>[];
+};
+export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefinition | null, const Layers extends LayerGroupDefinition = LayerGroupDefinition> extends Displayable<ImageDataRaw, Image, TransformDefinitions.ImageTransformProps> implements EventfulDisplayable {
     /**
      * Construct an image element. The config can describe either static sources or tagged outfits, but not both.
      * @param config - Image metadata such as tags, source, layer, and wearables.
@@ -53,14 +86,17 @@ export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefi
      * ```ts
      * const image = new Image({
      *   src: {
-     *     groups: [["happy", "sad"], ["top", "coat"]],
-     *     defaults: ["happy", "top"],
-     *     resolve: (emotion, top) => `https://img/${emotion}_${top}.png`
+     *     layers: [
+     *       "body.png",
+     *       {happy: "happy.png", sad: "sad.png"},
+     *       {shirt: "shirt.png", coat: "coat.png"},
+     *     ],
+     *     defaults: ["happy", "shirt"],
      *   }
      * });
      * ```
      */
-    constructor(config?: Partial<IImageUserConfig<Tags>>);
+    constructor(config?: Partial<IImageUserConfig<Tags, Layers>>);
     /**
      * Set the source of the image
      *
@@ -78,6 +114,7 @@ export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefi
      */
     char(src: ImageSrc | Color, transition?: ImageTransition): Proxied<Image, Chained<LogicAction.Actions>>;
     char(tags: SelectElementFromEach<Tags> | FlexibleTuple<SelectElementFromEach<Tags>>, transition?: ImageTransition): Proxied<Image, Chained<LogicAction.Actions>>;
+    char(tags: LayerTagsOf<Layers>[], transition?: ImageTransition): Proxied<Image, Chained<LogicAction.Actions>>;
     /**
      * Set the darkness of the image
      * @param darkness - The darkness of the image, between 0 and 1

package/dist/game/nlcore/elements/persistent/type.d.ts

@@ -2,3 +2,20 @@ export type StorableData<K extends string = string> = {
     [key in K]: number | boolean | string | StorableData | StorableData[] | undefined | null | Date;
 };
 export type StorableType = BaseStorableType | Record<string, BaseStorableType> | Array<BaseStorableType>;
+/**
+ * A single stored value as it appears in a saved game. Values are tagged on the way out so
+ * that types JSON cannot express (currently `Date`) survive the round-trip.
+ *
+ * This is part of the on-disk save format rather than an implementation detail: it is what
+ * {@link SavedGame}'s `store` actually contains. Read it through `Namespace`, never by hand.
+ */
+export type WrappedStorableData<T extends StorableType = any> = {
+    type: BaseStorableTypeName;
+    data: T;
+};
+/**
+ * One namespace's contents in a saved game: every value wrapped by {@link WrappedStorableData}.
+ */
+export type SerializedNamespaceData = {
+    [key: string]: WrappedStorableData;
+};

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

@@ -3,6 +3,17 @@ import { TransformDefinitions } from "../../../../elements/transform/type";
 import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
 import { GameState } from "../../../../../player/gameState";
 type AnimationType = [TransitionAnimationType.Number, TransitionAnimationType.Number, TransitionAnimationType.Number];
+/**
+ * A fade in, optionally travelling from a pixel offset to rest.
+ *
+ * The offset rides on the independent CSS `translate` property (not `transform`,
+ * and not `left`/`top`) for the same reason as {@link Push}: it composes additively
+ * with whatever base positioning the driven element already has, and it is the
+ * identity at offset `0`. Writing `transform` here instead would overwrite that
+ * base — a layered image's stack wrapper is positioned by `inset: 0` and carries
+ * no transform of its own, so a leftover `transform` from this transition would
+ * survive the crossfade and displace the settled stack.
+ */
 export declare class FadeIn extends ImageTransition<AnimationType> {
     private duration;
     private startPos;

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

@@ -9,6 +9,20 @@ export declare abstract class ImageTransition<T extends TransitionAnimationType[
     /**@package */
     private _currentSrc;
     /**@package */
+    private _prevLayers;
+    /**@package */
+    private _targetLayers;
+    /**@package */
+    _setPrevLayers(layers: (string | null)[]): this;
+    /**@package */
+    _setTargetLayers(layers: (string | null)[]): this;
+    /**@package */
+    _getPrevLayers(): (string | null)[] | undefined;
+    /**@package */
+    _getTargetLayers(): (string | null)[] | undefined;
+    /**@package */
+    _isLayered(): boolean;
+    /**@package */
     _setPrevSrc(src: Color | ImageSrc | undefined): this;
     /**@package */
     _setTargetSrc(src: Color | ImageSrc | undefined): this;

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

@@ -1,6 +1,6 @@
 import { LogicAction } from "./action/logicAction";
 import { ContentNode, RawData } from "./action/tree/actionTree";
-import { StorableData } from "./elements/persistent/type";
+import { SerializedNamespaceData } from "./elements/persistent/type";
 import { ElementStateRaw } from "./elements/story";
 import { StringKeyOf } from "../../util/data";
 import { PlayerStateData } from "../player/gameState";
@@ -40,7 +40,7 @@ export interface SavedGame {
     meta: SavedGameMetaData;
     game: {
         store: {
-            [key: string]: StorableData;
+            [key: string]: SerializedNamespaceData;
         };
         elementStates: RawData<ElementStateRaw>[];
         stage: PlayerStateData;

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

@@ -1,3 +1,5 @@
+import React from "react";
 export type ImageEvents = {
     "event:image.onLoad": [];
 };
+export declare function stackStyle(darkness: number): React.CSSProperties;