narraleaf-react 0.9.0 → 0.9.1

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

@@ -3,12 +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

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/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/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[];

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

@@ -0,0 +1,13 @@
+import type { Character } from "../../../nlcore/elements/character";
+import type { Image } from "../../../nlcore/elements/displayable/image";
+import React from "react";
+export type DialogAvatarContext = {
+    visible: boolean;
+    src: string | null;
+    character: Character | null;
+    portrait: Image | null;
+    alt: string;
+};
+export declare function useAvatar(): DialogAvatarContext;
+export declare function Avatar({ className, style, alt, ...props }: React.ImgHTMLAttributes<HTMLImageElement>): React.JSX.Element | null;
+export default Avatar;

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

@@ -1,5 +1,5 @@
 import { Pausing } from "../../../nlcore/elements/character/pause";
-import { Sentence } from "../../../nlcore/elements/character/sentence";
+import { Sentence, type StaticWord } from "../../../nlcore/elements/character/sentence";
 import { Word } from "../../../nlcore/elements/character/word";
 import { GameState } from "../../../../game/nlcore/common/game";
 import { Color } from "../../../../game/nlcore/types";
@@ -16,6 +16,74 @@ type BaseTextsProps = {
     style?: React.CSSProperties;
     dialog?: DialogState;
 } & React.HTMLAttributes<HTMLDivElement>;
+export type TextsPreviewInput = StaticWord<string | Pausing> | StaticWord<string | Pausing>[];
+export type TextsPreviewLoop = boolean | {
+    /**
+     * Whether the preview restarts after the current type effect completes.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Delay before the next preview cycle starts, in milliseconds.
+     * @default 1000
+     */
+    delay?: number;
+};
+export interface TextsPreviewProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    /**
+     * Static text or words to preview.
+     */
+    text?: TextsPreviewInput;
+    /**
+     * Sentence to preview. Dynamic words are not evaluated; pass `words` when
+     * previewing already-evaluated runtime content.
+     */
+    sentence?: Sentence;
+    /**
+     * Already-evaluated words, useful when previewing dynamic sentence content.
+     */
+    words?: Word<Pausing | string>[];
+    /**
+     * Whether the preview should use the rolling type effect.
+     * @default true
+     */
+    useTypeEffect?: boolean;
+    /**
+     * Loop behavior for settings screens and other static previews.
+     * @default true
+     */
+    loop?: TextsPreviewLoop;
+    /**
+     * Delay before replay when `loop` is `true`, in milliseconds.
+     * Ignored when `loop` is an object with `delay`.
+     * @default 1000
+     */
+    restartDelay?: number;
+    /**
+     * Characters per second used by the preview.
+     * @default current game's `cps` preference, or Game.DefaultPreference.cps outside GameProvider
+     */
+    cps?: number;
+    /**
+     * Speed multiplier used by the preview.
+     * @default current game's `gameSpeed` preference, or Game.DefaultPreference.gameSpeed outside GameProvider
+     */
+    gameSpeed?: number;
+    /**
+     * Duration for a pause without an explicit duration, in milliseconds.
+     * @default current game's `autoForwardDefaultPause` config, or Game.DefaultConfig.autoForwardDefaultPause outside GameProvider
+     */
+    pauseDuration?: number;
+    /**
+     * Fallback color when neither the word nor the sentence defines one.
+     */
+    defaultColor?: Color;
+    fontSize?: React.CSSProperties["fontSize"];
+    fontWeight?: React.CSSProperties["fontWeight"];
+    fontWeightBold?: React.CSSProperties["fontWeight"];
+    fontFamily?: React.CSSProperties["fontFamily"];
+    onCompleted?: () => void;
+}
 /**
  * Props-based wrapper component
  * Provides a clean interface for direct prop usage
@@ -36,6 +104,7 @@ export type EntryTextsProps = BaseTextsProps & {
     useTypeEffect: boolean;
     isActive: boolean;
 };
+export declare function TextsPreview({ text, sentence, words, useTypeEffect, loop, restartDelay, cps, gameSpeed, pauseDuration, defaultColor, className, style, fontSize, fontWeight, fontWeightBold, fontFamily, onCompleted, ...props }: TextsPreviewProps): React.JSX.Element;
 export declare function RawTexts(props: BaseTextsProps): React.JSX.Element;
 /**
  * Context-based wrapper component

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

@@ -6,7 +6,7 @@ import React from "react";
 import { DialogAction, DialogStateType, SayElementProps } from "./type";
 type DialogEvents = {
     "event:dialog.requestComplete": [];
-    "event:dialog.complete": [force: boolean];
+    "event:dialog.complete": [force?: boolean];
     "event:dialog.forceSkip": [];
     "event:dialog.onFlush": [];
     "event:dialog.simulateClick": [];
@@ -16,6 +16,7 @@ type DialogStateConfig = {
     action: DialogAction;
     evaluatedWords: Word<Pausing | string>[];
     gameState: GameState;
+    suppressInitialAnimation?: boolean;
 };
 export declare class DialogState {
     static Events: {
@@ -31,12 +32,15 @@ export declare class DialogState {
     private _count;
     private _forceSkipped;
     private _idle;
+    private _active;
     private autoForwardScheduler;
     constructor(config: DialogStateConfig);
     get state(): DialogStateType;
     get deps(): React.DependencyList;
     isIdle(): boolean;
     setIdle(idle: boolean): void;
+    isActive(): boolean;
+    setActive(active: boolean): this;
     /**
      * Only for dialog component to call
      *
@@ -68,5 +72,5 @@ export declare class DialogState {
     safeEmit(event: keyof DialogEvents, ...args: DialogEvents[keyof DialogEvents]): this;
     private scheduleAutoForward;
 }
-export default function PlayerDialog({ action, onFinished, useTypeEffect, gameState, }: Readonly<SayElementProps>): React.JSX.Element;
+export default function PlayerDialog({ action, onFinished, useTypeEffect, gameState, active, }: Readonly<SayElementProps>): React.JSX.Element;
 export {};

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

@@ -4,6 +4,7 @@ import { Sentence } from "../../../nlcore/elements/character/sentence";
 import { Word } from "../../../nlcore/elements/character/word";
 import { Pausing } from "../../../nlcore/elements/character/pause";
 import React from "react";
+import type { HTMLMotionProps } from "motion/react";
 export interface SayElementProps {
     action: {
         sentence: Sentence | null;
@@ -19,12 +20,13 @@ export interface SayElementProps {
     onFinished?: (skiped?: boolean) => void;
     useTypeEffect?: boolean;
     gameState: GameState;
+    active?: boolean;
 }
 export interface IDialogProps {
 }
 export type DialogProps = {
-    children: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
+    children?: React.ReactNode;
+} & HTMLMotionProps<"div">;
 export type DialogElementProps = {
     children?: never;
 } & React.HTMLAttributes<HTMLDivElement>;

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

@@ -1,3 +1,4 @@
+import type { SentenceMetadata } from "../../../nlcore/elements/character/sentence";
 /**
  * Represents the context of a dialog, containing information about its completion status
  * and the text content.
@@ -9,6 +10,8 @@ export type DialogContext = {
     text: string;
     /** Whether the dialog is the narrator */
     isNarrator: boolean;
+    /** User-provided runtime metadata from the current sentence, if any */
+    metadata?: SentenceMetadata;
 };
 /**
  * A custom hook that provides access to the current dialog's state and content.

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

@@ -39,6 +39,12 @@ export interface PlayerProps {
      * only called each lifecycle once
      */
     onReady?: (ctx: PlayerEventContext) => void;
+    /**
+     * Once the internal preload pass is ready and the Player has committed that state.
+     *
+     * only called each lifecycle once
+     */
+    onPreloadedReady?: (ctx: PlayerEventContext) => void;
     /**
      * Once the game is ended
      *

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

@@ -28,6 +28,7 @@ import { GameHistoryManager } from "../../game/nlcore/action/gameHistory";
 import type { Character } from "../nlcore/elements/character";
 import type { TransformDefinitions } from "../nlcore/elements/transform/type";
 import type { NvlBlockOptions } from "../nlcore/action/actionTypes";
+import { type NormalizedCharacterPortraitConfig } from "../nlcore/elements/character/avatar";
 export type NvlDialogEntry = {
     id: string;
     actionId: string;
@@ -182,6 +183,7 @@ export declare class GameState {
     getSceneElements(): PlayerStateElement[];
     getLastScene(): Scene | null;
     getCurrentScene(): Scene | null;
+    findCurrentPortraitForCharacter(character: Character): NormalizedCharacterPortraitConfig | null;
     sceneExists(scene?: Scene): boolean;
     isSceneActive(scene: Scene): boolean;
     wait(ms: number): Promise<void>;
@@ -317,6 +319,7 @@ export declare class GameState {
     private syncNvlDerivedState;
     private emitNvlStateChange;
     private resolveNvlAdvance;
+    private isDisplayableVisible;
     private createWaitableAction;
     private sceneNotFound;
     private layerNotFound;

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

@@ -21,6 +21,7 @@ export declare class AudioManager {
     private sound;
     private ready;
     private isReady;
+    private isInitializing;
     constructor(gameState: GameState);
     /**
      * Must be called ONCE on the client side to prepare audio subsystem.