narraleaf-react 0.9.0-beta.5 → 0.9.1

package/dist/game/nlcore/common/transition.d.ts

@@ -1,6 +1,7 @@
 import { Dissolve } from "../elements/transition/transitions/image/dissolve";
 import { FadeIn } from "../elements/transition/transitions/image/fadeIn";
+import { MaskTransition } from "../elements/transition/transitions/image/maskTransition";
 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, };
+export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, MaskTransition, };

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

@@ -7,6 +7,8 @@ import { Scene } from "../scene";
 export declare class DevTools {
     static getActionId(action: LogicAction.Actions): string;
     static setActionId(action: LogicAction.Actions, id: string): LogicAction.Actions;
+    static getStaticId(action: LogicAction.Actions): string | null;
+    static setStaticId(action: LogicAction.Actions, id: string | null): LogicAction.Actions;
     static chainToActions(chain: Proxied<LogicAction.GameElement, Chained<LogicAction.Actions>>): LogicAction.Actions[];
     static wrapAction(action: LogicAction.Actions[] | Proxied<LogicAction.GameElement, Chained<LogicAction.Actions>>): ControlAction;
     static getNamespaceName(persistent: Persistent<any>): string;

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

@@ -1,2 +1,4 @@
 export { Gallery } from "./Gallery";
 export { DevTools } from "./DevTools";
+export { blink, effectLayer, vignette, } from "./screenEffects";
+export type { BlinkOptions, EffectLayerOptions, ScreenEffectColor, VignetteOptions, } from "./screenEffects";

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

@@ -0,0 +1,31 @@
+import { Control, Layer } from "narraleaf-react";
+import type { Scene, TransformDefinitions } from "narraleaf-react";
+export type ScreenEffectColor = string | {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+};
+export type EffectLayerOptions = {
+    name?: string;
+    zIndex?: number;
+};
+export type BlinkOptions = {
+    closeDuration?: number;
+    hold?: number;
+    openDuration?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+    color?: ScreenEffectColor;
+};
+export type VignetteOptions = {
+    duration?: number;
+    opacity?: number;
+    color?: ScreenEffectColor;
+    inner?: string;
+    outer?: string;
+    hold?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+export declare function effectLayer(scene: Scene, options?: EffectLayerOptions): Layer;
+export declare function blink(scene: Scene, options?: BlinkOptions): ReturnType<typeof Control.do>;
+export declare function vignette(scene: Scene, options?: VignetteOptions): ReturnType<typeof Control.do>;

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

@@ -0,0 +1,35 @@
+import type { ImageSrc } from "../../types";
+import type { Character } from "../../elements/character";
+import type { Image } from "../../elements/displayable/image";
+import type { Sentence } from "../../elements/character/sentence";
+import type { GameState } from "../../../player/gameState";
+export type DialogAvatarSource = ImageSrc | null;
+export type DialogAvatarResolverContext = {
+    character: Character;
+    sentence: Sentence | null;
+    portrait: Image | null;
+    currentSrc: string | null;
+    tags: string[] | null;
+    gameState: GameState;
+};
+export type DialogAvatarResolver = (ctx: DialogAvatarResolverContext) => DialogAvatarSource | undefined;
+export type DialogAvatar = DialogAvatarSource | DialogAvatarResolver;
+export type CharacterPortraitConfig = {
+    image: Image;
+    avatar?: DialogAvatar;
+};
+export type NormalizedCharacterPortraitConfig = {
+    image: Image;
+    avatar?: DialogAvatar;
+};
+export type DialogAvatarResolution = {
+    source: DialogAvatarSource;
+    character: Character | null;
+    portrait: Image | null;
+};
+export declare function normalizeCharacterPortraitConfig(portrait: Image | CharacterPortraitConfig): NormalizedCharacterPortraitConfig;
+export declare function resolveDialogAvatar(ctx: DialogAvatarResolverContext & {
+    sentenceAvatar?: DialogAvatar | false;
+    portraitAvatar?: DialogAvatar;
+    characterAvatar?: DialogAvatar | false;
+}): DialogAvatarResolution;

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

@@ -4,12 +4,22 @@ import { Word } from "../../elements/character/word";
 import type { ScriptCtx } from "../../elements/script";
 import { Sound } from "../../elements/sound";
 import { Color, Font } from "../../types";
+import type { DialogAvatar } from "../../elements/character/avatar";
+/**
+ * User-provided runtime metadata attached to a sentence; not serialized with saves.
+ * Use plain serializable values when possible.
+ */
+export type SentenceMetadata = Record<string, unknown>;
 export type SentenceConfig = {
     pause?: boolean | number;
     voice: Sound | null;
     character: Character | null;
     voiceId: string | number | null;
     color?: Color;
+    /** Optional runtime-only metadata for UI hooks and integrations */
+    metadata?: SentenceMetadata;
+    /** Optional per-line dialog avatar override. Use `false` to hide the avatar for this sentence. */
+    avatar?: DialogAvatar | false;
 } & Font;
 export type SentenceUserConfig = Partial<Omit<SentenceConfig, "voice"> & {
     voice: Sound | string | null | undefined;
@@ -20,6 +30,10 @@ export type StaticWord<T extends string | DynamicWord | Pausing = string | Dynam
 export type SingleWord = StaticWord | DynamicWord;
 export type SentencePrompt = SingleWord[] | SingleWord;
 export declare class Sentence {
+    /**
+     * Returns runtime-only user metadata from sentence config; undefined when not set.
+     */
+    getMetadata(): SentenceMetadata | undefined;
     /**
      * Build a new sentence from a prompt or mix of words, pauses, and dynamic data.
      * @param text - The sentence prompt used to render the dialogue.

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

@@ -4,8 +4,12 @@ import { DeepPartial } from "../../../util/data";
 import { Actionable } from "../action/actionable";
 import { Chained, Proxied } from "../action/chain";
 import { Sentence, SentencePrompt, SentenceUserConfig, SingleWord } from "../elements/character/sentence";
+import type { CharacterPortraitConfig, DialogAvatar } from "../elements/character/avatar";
+import type { Image } from "../elements/displayable/image";
 export type CharacterConfig = {
     color?: Color;
+    avatar?: DialogAvatar | false;
+    portraits: (Image | CharacterPortraitConfig)[];
 };
 export interface Character {
     (content: string, config?: SentenceUserConfig): Proxied<Character, Chained<LogicAction.Actions>>;
@@ -58,6 +62,32 @@ export declare class Character extends Actionable<CharacterStateData, Character>
      * ```
      */
     setName(name: string): Proxied<Character, Chained<LogicAction.Actions>>;
+    /**
+     * Set the avatar strategy used by dialogs for this character.
+     * @param avatar - Image source, resolver, `false` to hide by default, or `null` for no avatar.
+     * @example
+     * ```ts
+     * character.setAvatar("alice-avatar.png");
+     * ```
+     */
+    setAvatar(avatar: DialogAvatar | false | null): this;
+    /**
+     * Register a portrait image as a possible visual source for this character's dialog avatar.
+     * @param image - The stage image that represents the character.
+     * @param config - Optional avatar override for this portrait.
+     * @example
+     * ```ts
+     * character.addPortrait(aliceSprite, { avatar: "alice-happy-avatar.png" });
+     * ```
+     */
+    addPortrait(image: Image, config?: {
+        avatar?: DialogAvatar;
+    }): this;
+    /**
+     * Replace all portrait bindings for this character.
+     * @param portraits - Stage images or image/avatar pairs.
+     */
+    setPortraits(portraits: (Image | CharacterPortraitConfig)[]): this;
     apply(content: string, config?: SentenceUserConfig): Proxied<Character, Chained<LogicAction.Actions>>;
     apply(content: Sentence): Proxied<Character, Chained<LogicAction.Actions>>;
     apply(content: SentencePrompt, config?: SentenceUserConfig): Proxied<Character, Chained<LogicAction.Actions>>;

package/dist/game/nlcore/elements/control.d.ts

@@ -79,6 +79,16 @@ export declare class Control extends Actionable {
      * @chainable
      */
     static sleep(duration: number | Awaitable<any> | Promise<any>): ChainedControl;
+    /**
+     * Pause execution until the user clicks anywhere on the stage (excluding GUI/Page elements).
+     * Similar to inserting a pause with no duration in a Sentence.
+     * @chainable
+     * @example
+     * ```ts
+     * Control.waitForClick();
+     * ```
+     */
+    static waitForClick(): ChainedControl;
     constructor(/**@internal */ config?: Partial<ControlConfig>);
     /**
      * Execute actions in order, waiting for each action to complete
@@ -126,4 +136,9 @@ export declare class Control extends Actionable {
      * @chainable
      */
     sleep(duration: number | Awaitable<any> | Promise<any>): ChainedControl;
+    /**
+     * Wait for user to click the stage (excluding GUI elements)
+     * @chainable
+     */
+    waitForClick(): ChainedControl;
 }

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

@@ -4,6 +4,7 @@ import { Chained, Proxied } from "../../action/chain";
 import { LogicAction } from "../../action/logicAction";
 import { EventfulDisplayable } from "../../../player/elements/displayable/type";
 import type { TransformDefinitions } from "../../elements/transform/type";
+import type { ImageSrc } from "../../types";
 export declare abstract class Displayable<StateData extends Record<string, any>, Self extends Displayable<any, any, any>, TransformType extends TransformDefinitions.Types = TransformDefinitions.Types> extends Actionable<StateData, Self> implements EventfulDisplayable {
     /**
      * Set Image Position
@@ -92,6 +93,83 @@ export declare abstract class Displayable<StateData extends Record<string, any>,
      * ```
      */
     opacity(opacity: number, duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Self, Chained<LogicAction.Actions>>;
+    /**
+     * Apply visual effects to the Displayable.
+     *
+     * This is the low-level effect entry. Resource-aware helpers such as
+     * {@link Displayable.mask} should be preferred when an effect depends on an image source.
+     *
+     * @chainable
+     */
+    effect(effect: TransformDefinitions.VisualEffectTransformProps, options?: TransformDefinitions.VisualEffectOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Apply an image mask to the Displayable.
+     *
+     * The source is registered for image preload and resolved to a CSS `url(...)` mask image.
+     *
+     * @chainable
+     */
+    mask(src: ImageSrc, options?: TransformDefinitions.MaskOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Clear the current CSS mask from the Displayable.
+     *
+     * @chainable
+     */
+    clearMask(options?: TransformDefinitions.VisualEffectOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Apply a CSS clip-path to the Displayable.
+     *
+     * @chainable
+     */
+    clip(clipPath: TransformDefinitions.VisualEffectTransformProps["clipPath"], options?: TransformDefinitions.VisualEffectOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Clear the current CSS clip-path from the Displayable.
+     *
+     * @chainable
+     */
+    clearClip(options?: TransformDefinitions.VisualEffectOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Reveal the Displayable with an animated circular clip-path.
+     *
+     * @chainable
+     */
+    circleReveal(options?: TransformDefinitions.CircleRevealOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Close the Displayable with an animated circular clip-path.
+     *
+     * @chainable
+     */
+    circleClose(options?: TransformDefinitions.CircleCloseOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Reveal or close the Displayable with an animated directional wipe.
+     *
+     * @chainable
+     */
+    wipe(options?: TransformDefinitions.WipeOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Apply a CSS filter to the Displayable.
+     *
+     * @chainable
+     */
+    filter(filter: TransformDefinitions.VisualEffectTransformProps["filter"], options?: TransformDefinitions.VisualEffectOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Clear the current CSS filter from the Displayable.
+     *
+     * @chainable
+     */
+    clearFilter(options?: TransformDefinitions.VisualEffectOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Apply a CSS backdrop-filter to the Displayable.
+     *
+     * @chainable
+     */
+    backdrop(backdropFilter: TransformDefinitions.VisualEffectTransformProps["backdropFilter"], options?: TransformDefinitions.VisualEffectOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Apply a CSS mix-blend-mode to the Displayable.
+     *
+     * @chainable
+     */
+    blend(mixBlendMode: TransformDefinitions.VisualEffectTransformProps["mixBlendMode"], options?: TransformDefinitions.VisualEffectOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
     /**
      * Apply a transform to the Displayable
      * @chainable
@@ -101,6 +179,12 @@ export declare abstract class Displayable<StateData extends Record<string, any>,
      * ```
      */
     transform(transform: Transform<TransformType>): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    private registerEffectSrc;
+    private static toCSSUrl;
+    private static extractCSSUrls;
+    private static createClipPathTransform;
+    private static circleClipPath;
+    private static wipeClipPath;
     /**
      * Show the Displayable
      *

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

@@ -1,5 +1,5 @@
 import type { TransformDefinitions } from "../../elements/transform/type";
-import { Color, CommonDisplayableConfig, ImageSrc } from "../../types";
+import { Color, ImageSrc } from "../../types";
 import { LogicAction } from "../../game";
 import { FlexibleTuple, SelectElementFromEach } from "../../../../util/data";
 import { Chained, Proxied } from "../../action/chain";
@@ -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 CommonDisplayableConfig {
+export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGroupDefinition | null> extends TransformDefinitions.ImageTransformProps {
     /**
      * The name of the image, only for debugging purposes
      */

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

@@ -1,4 +1,4 @@
-import { Color, CommonDisplayableConfig } from "../../types";
+import { Color } from "../../types";
 import { Chained, Proxied } from "../../action/chain";
 import { LogicAction } from "../../action/logicAction";
 import type { TransformDefinitions } from "../../elements/transform/type";
@@ -16,7 +16,7 @@ export type TextState = {
     display: boolean;
     text: string;
 };
-export interface ITextUserConfig extends CommonDisplayableConfig {
+export interface ITextUserConfig extends TransformDefinitions.TextTransformProps {
     /**
      * Where to align the text horizontally
      * @default "center"

package/dist/game/nlcore/elements/layer.d.ts

@@ -1,4 +1,3 @@
-import { CommonDisplayableConfig } from "../types";
 import { LogicAction } from "../action/logicAction";
 import { TransformDefinitions } from "../elements/transform/type";
 import { Displayable } from "../elements/displayable/displayable";
@@ -6,7 +5,7 @@ import { EventfulDisplayable } from "../../player/elements/displayable/type";
 import { Image } from "../elements/displayable/image";
 import { Text } from "../elements/displayable/text";
 import { Chained, Proxied } from "../action/chain";
-export interface ILayerUserConfig extends CommonDisplayableConfig {
+export interface ILayerUserConfig extends TransformDefinitions.ImageTransformProps {
     /**
      * The z-index of the layer, higher z-index will be rendered on top of the lower z-index, allows negative values.
      *

package/dist/game/nlcore/elements/nvl.d.ts

@@ -0,0 +1,41 @@
+import { Actionable } from "../action/actionable";
+import { LogicAction } from "../action/logicAction";
+import { Chained, Proxied } from "../action/chain";
+import type { TransformDefinitions } from "../elements/transform/type";
+import type { Scene } from "../elements/scene";
+type ChainedNVL = Proxied<NVLToken, Chained<LogicAction.Actions>>;
+export declare class NVLToken extends Actionable<null, NVLToken> {
+    constructor(scene: Scene);
+    /**
+     * Show the NVL layer with optional transition
+     * @param options - Optional transition properties for showing the NVL layer
+     * @chainable
+     * @example
+     * ```ts
+     * nvl.show({ duration: 500 });
+     * ```
+     */
+    show(options?: Partial<TransformDefinitions.CommonTransformProps>): ChainedNVL;
+    /**
+     * Hide the NVL layer with optional transition
+     * Does not exit NVL mode or clear dialogs
+     * @param options - Optional transition properties for hiding the NVL layer
+     * @chainable
+     * @example
+     * ```ts
+     * nvl.hide({ duration: 500 });
+     * ```
+     */
+    hide(options?: Partial<TransformDefinitions.CommonTransformProps>): ChainedNVL;
+    /**
+     * Force exit NVL mode immediately
+     * Clears all accumulated dialogs and hides the NVL layer
+     * @chainable
+     * @example
+     * ```ts
+     * nvl.end();
+     * ```
+     */
+    end(): ChainedNVL;
+}
+export {};

package/dist/game/nlcore/elements/scene.d.ts

@@ -3,10 +3,13 @@ import { Color, ImageSrc } from "../types";
 import { LogicAction } from "../action/logicAction";
 import { Sound, VoiceIdMap, VoiceSrcGenerator } from "../elements/sound";
 import { Image } from "../elements/displayable/image";
-import { ActionStatements, Persistent } from "../common/core";
 import { Chained, Proxied } from "../action/chain";
 import { ImageTransition } from "../elements/transition/transitions/image/imageTransition";
 import { Layer } from "../elements/layer";
+import { NVLToken } from "./nvl";
+import type { TransformDefinitions } from "../elements/transform/type";
+import type { ActionStatements } from "../elements/type";
+import type { Persistent } from "../elements/persistent";
 export interface ISceneUserConfig {
     /**
      * Background music
@@ -79,6 +82,31 @@ export declare class Scene extends Constructable<LogicAction.Actions, Scene> {
      * ```
      */
     setBackgroundMusic(sound: Sound | null, fade?: number): ChainedScene;
+    /**
+     * Create an NVL (Novel) mode block for displaying accumulated dialog.
+     * In NVL mode, dialogs are stacked on screen rather than replacing each other.
+     * @param actions - Actions to execute within NVL mode, or a callback receiving an NVLToken
+     * @chainable
+     * @example
+     * ```ts
+     * scene.nvl([
+     *     character.say("First line"),
+     *     character.say("Second line"),
+     *     character.say("Third line"),
+     * ]);
+     * ```
+     * @example
+     * ```ts
+     * scene.nvl(nvl => [
+     *     nvl.show({ duration: 500 }),
+     *     character.say("Line 1"),
+     *     character.say("Line 2"),
+     *     nvl.hide({ duration: 500 }),
+     * ]);
+     * ```
+     */
+    nvl(actions: ActionStatements | ((nvl: NVLToken) => ActionStatements)): ChainableAction;
+    nvl(options: Partial<TransformDefinitions.CommonTransformProps>, actions: ActionStatements | ((nvl: NVLToken) => ActionStatements)): ChainableAction;
     /**
      * Register the list of actions (or an action-generating callback) that this scene will execute.
      * @param actions - Either a list of actions or a factory that receives the scene and returns actions.

package/dist/game/nlcore/elements/transform/transform.d.ts

@@ -1,4 +1,3 @@
-import type { CommonDisplayableConfig } from "../../types";
 import { TransformDefinitions } from "./type";
 import { CSSProps } from "../../elements/transition/type";
 type OverwriteMap = {
@@ -8,7 +7,7 @@ export type OverwriteDefinition = {
     [K in keyof OverwriteMap]?: OverwriteHandler<OverwriteMap[K]>;
 };
 type OverwriteHandler<T> = (value: Partial<TransformDefinitions.Types>) => T;
-export declare class Transform<T extends TransformDefinitions.Types = CommonDisplayableConfig> {
+export declare class Transform<T extends TransformDefinitions.Types = TransformDefinitions.Types> {
     /**
      * Apply transform immediately
      */
@@ -30,7 +29,7 @@ export declare class Transform<T extends TransformDefinitions.Types = CommonDisp
      * @param config - The config for the transform.
      * @returns A new transform with the given config.
      */
-    static create<T extends TransformDefinitions.Types = CommonDisplayableConfig>(config?: Partial<TransformDefinitions.TransformConfig>): Transform<T>;
+    static create<T extends TransformDefinitions.Types = TransformDefinitions.Types>(config?: Partial<TransformDefinitions.TransformConfig>): Transform<T>;
     /**
      * @example
      * ```ts
@@ -124,5 +123,29 @@ export declare class Transform<T extends TransformDefinitions.Types = CommonDisp
      * @returns {this} The current Transform instance for method chaining.
      */
     fontColor(fontColor: TransformDefinitions.Types["fontColor"]): this;
+    /**
+     * Set visual effect fields in the current staging sequence.
+     */
+    effect(effect: TransformDefinitions.VisualEffectTransformProps): this;
+    /**
+     * Set the CSS mask image of the current staging sequence.
+     */
+    maskImage(maskImage: TransformDefinitions.Types["maskImage"]): this;
+    /**
+     * Set the CSS clip-path of the current staging sequence.
+     */
+    clipPath(clipPath: TransformDefinitions.Types["clipPath"]): this;
+    /**
+     * Set the CSS filter of the current staging sequence.
+     */
+    filter(filter: TransformDefinitions.Types["filter"]): this;
+    /**
+     * Set the CSS backdrop-filter of the current staging sequence.
+     */
+    backdropFilter(backdropFilter: TransformDefinitions.Types["backdropFilter"]): this;
+    /**
+     * Set the CSS mix-blend-mode of the current staging sequence.
+     */
+    mixBlendMode(mixBlendMode: TransformDefinitions.Types["mixBlendMode"]): this;
 }
 export {};

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

@@ -1,4 +1,5 @@
 import { Color, CommonDisplayableConfig } from "../../types";
+import type React from "react";
 export declare namespace TransformDefinitions {
     type BezierDefinition = [number, number, number, number];
     type CustomEasingFunction = (t: number) => number;
@@ -17,10 +18,37 @@ export declare namespace TransformDefinitions {
         repeat?: number;
         repeatDelay?: number;
     };
-    type ImageTransformProps = CommonDisplayableConfig & {};
+    type VisualEffectTransformProps = {
+        maskImage?: React.CSSProperties["maskImage"];
+        maskSize?: React.CSSProperties["maskSize"];
+        maskPosition?: React.CSSProperties["maskPosition"];
+        maskRepeat?: React.CSSProperties["maskRepeat"];
+        maskMode?: React.CSSProperties["maskMode"];
+        clipPath?: React.CSSProperties["clipPath"];
+        filter?: React.CSSProperties["filter"];
+        backdropFilter?: React.CSSProperties["backdropFilter"];
+        mixBlendMode?: React.CSSProperties["mixBlendMode"];
+    };
+    type VisualEffectOptions = Partial<CommonTransformProps>;
+    type MaskOptions = VisualEffectOptions & Pick<VisualEffectTransformProps, "maskSize" | "maskPosition" | "maskRepeat" | "maskMode">;
+    type WipeDirection = "left" | "right" | "top" | "bottom";
+    type CircleClipOptions = VisualEffectOptions & {
+        center?: string;
+        from?: number;
+        to?: number;
+        clearClip?: boolean;
+    };
+    type CircleRevealOptions = CircleClipOptions;
+    type CircleCloseOptions = CircleClipOptions;
+    type WipeOptions = VisualEffectOptions & {
+        direction?: WipeDirection;
+        reverse?: boolean;
+        clearClip?: boolean;
+    };
+    type ImageTransformProps = CommonDisplayableConfig & VisualEffectTransformProps;
     type TextTransformProps = CommonDisplayableConfig & {
         fontColor?: Color;
-    };
+    } & VisualEffectTransformProps;
     type Types = CommonDisplayableConfig & ImageTransformProps & TextTransformProps;
     type SequenceProps<T> = Partial<T>;
     type SequenceOptions = Partial<CommonTransformProps>;

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

@@ -0,0 +1,38 @@
+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 MaskTransitionCircleOptions = {
+    duration: number;
+    easing?: TransformDefinitions.EasingDefinition;
+    center?: string;
+    from?: number;
+    to?: number;
+};
+export type MaskTransitionWipeOptions = {
+    duration: number;
+    easing?: TransformDefinitions.EasingDefinition;
+    direction?: TransformDefinitions.WipeDirection;
+    reverse?: boolean;
+};
+export declare class MaskTransition extends ImageTransition<AnimationType> {
+    private duration;
+    private easing;
+    private clipPathResolver;
+    private constructor();
+    /**
+     * Reveal the target image through an animated circular clip-path.
+     */
+    static circle(options: MaskTransitionCircleOptions): MaskTransition;
+    /**
+     * Reveal or close the target image through an animated directional wipe.
+     */
+    static wipe(options: MaskTransitionWipeOptions): MaskTransition;
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    copy(): MaskTransition;
+    private static lerp;
+    private static circleClipPath;
+    private static wipeClipPath;
+    private static formatNumber;
+}
+export {};

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

@@ -7,7 +7,7 @@ import { PlayerStateData } from "../player/gameState";
 import { GuardConfig } from "../player/guard";
 import React from "react";
 import { StackModel, StackModelRawData } from "./action/stackModel";
-import { MenuComponent, NotificationComponent, SayComponent } from "./common/player";
+import { MenuComponent, NotificationComponent, NvlDialogComponent, SayComponent } from "./common/player";
 import { Color, LiveGameEventToken } from "./types";
 export interface SavedGameMetaData {
     /**
@@ -276,6 +276,11 @@ export type GameConfig = {
      * @default DefaultSay
      */
     dialog: SayComponent;
+    /**
+     * The component to use for NVL mode dialog
+     * @default DefaultNvlContainer
+     */
+    nvlDialog: NvlDialogComponent;
     /**
      * The function to call when an error occurs
      * @default () => {}

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

@@ -1,6 +1,6 @@
 import { Awaitable } from "../../util/data";
 import { GameStateGuard } from "./guard";
-type TimelineStatus = "pending" | "cancelled" | "resolved";
+type TimelineStatus = "pending" | "cancelled" | "resolved" | "failed";
 export declare class Timeline {
     awaitable: Awaitable;
     guard?: GameStateGuard | undefined;
@@ -74,6 +74,7 @@ export declare class Timeline {
     private children;
     private _onResolved;
     private _onCancelled;
+    private _onFailed;
     private _onTimelineRegistered;
     private _ableToAttach;
     private _status;
@@ -82,8 +83,10 @@ export declare class Timeline {
     isSettled(): boolean;
     isResolved(): boolean;
     isCancelled(): boolean;
+    isFailed(): boolean;
     onResolved(callback: () => void): void;
     onCancelled(callback: () => void): void;
+    onFailed(callback: (error: unknown) => void): void;
     onSettled(callback: () => void): void;
     abort(): void;
     attachChild(arg0: Awaitable | Timeline): this;

package/dist/game/player/elements/Player.d.ts

@@ -1,4 +1,4 @@
 import "client-only";
 import { PlayerProps } from "../elements/type";
 import React from "react";
-export default function Player({ story, width, height, className, onReady, onEnd, onError, children, active, }: Readonly<PlayerProps>): React.JSX.Element;
+export default function Player({ story, width, height, className, onReady, onPreloadedReady, onEnd, onError, children, active, }: Readonly<PlayerProps>): React.JSX.Element;

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

@@ -1,8 +1,10 @@
 import { DefaultDialog } from "../../../game/player/elements/say/Dialog";
 import { DefaultMenu } from "../../../game/player/elements/menu/PlayerMenu";
 import { DefaultNotification } from "../elements/notification/PlayerNotification";
+import { DefaultNvlContainer } from "../elements/nvl/DefaultNvlContainer";
 export declare const DefaultElements: {
     readonly say: typeof DefaultDialog;
     readonly menu: typeof DefaultMenu;
     readonly notification: typeof DefaultNotification;
+    readonly nvlDialog: typeof DefaultNvlContainer;
 };

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

@@ -10,6 +10,7 @@ export interface MenuElementProps {
     afterChoose: (choice: Chosen) => void;
     state: GameState;
     words: Word<Pausing | string>[] | null;
+    renderPrompt?: boolean;
 }
 export interface IUserMenuProps {
     items: number[];