narraleaf-react 0.19.2 → 0.20.1

package/dist/built-in.d.ts

@@ -1,3 +1,3 @@
-export { Gallery, DevTools, } from "narraleaf-react";
+export { Gallery, DevTools, } from "./game/nlcore/common/core";
 export { blink, effectLayer, vignette, } from "./game/nlcore/elements/built-in/screenEffects";
 export type { BlinkOptions, EffectLayerOptions, ScreenEffectColor, VignetteOptions, } from "./game/nlcore/elements/built-in/screenEffects";

package/dist/game/nlcore/action/actionTypes.d.ts

@@ -16,6 +16,7 @@ import type { Transition } from "../elements/transition/transition";
 import type { ImageTransition } from "../elements/transition/transitions/image/imageTransition";
 import type { Layer } from "../elements/layer";
 import type { VfxFadeOptions } from "../elements/vfx";
+import type { PuppetCommandOptions } from "../elements/displayable/puppet";
 export declare const DisplayableActionTypes: {
     readonly action: "displayable:action";
     readonly applyTransform: "displayable:applyTransform";
@@ -166,3 +167,15 @@ export declare const VfxActionTypes: {
 export type VfxActionContentType = {
     [K in typeof VfxActionTypes[keyof typeof VfxActionTypes]]: K extends "vfx:action" ? any : K extends "vfx:show" | "vfx:hide" ? [VfxFadeOptions?] : K extends "vfx:pause" | "vfx:resume" ? [] : K extends "vfx:setRate" ? [number] : any;
 };
+export declare const PuppetActionTypes: {
+    readonly action: "puppet:action";
+    readonly setMotion: "puppet:setMotion";
+    readonly setExpression: "puppet:setExpression";
+    readonly setSkin: "puppet:setSkin";
+    readonly setParam: "puppet:setParam";
+    readonly setSlot: "puppet:setSlot";
+    readonly command: "puppet:command";
+};
+export type PuppetActionContentType = {
+    [K in typeof PuppetActionTypes[keyof typeof PuppetActionTypes]]: K extends "puppet:action" ? any : K extends "puppet:setMotion" ? [motion: string | null] : K extends "puppet:setExpression" ? [expression: string | null] : K extends "puppet:setSkin" ? [skin: string | null] : K extends "puppet:setParam" ? [id: string, value: number] : K extends "puppet:setSlot" ? [id: string, value: string | null] : K extends "puppet:command" ? [name: string, payload: unknown, options: PuppetCommandOptions | undefined] : any;
+};

package/dist/game/nlcore/action/actions/puppetAction.d.ts

@@ -0,0 +1,59 @@
+import { PuppetActionContentType, PuppetActionTypes } from "../../action/actionTypes";
+import { TypedAction } from "../../action/actions";
+import type { Puppet } from "../../elements/displayable/puppet";
+import { GameState } from "../../../player/gameState";
+import { Values } from "../../../../util/data";
+import { ActionExecutionInjection, ExecutedActionResult } from "../../action/action";
+import { LogicAction } from "../../action/logicAction";
+import { Story } from "../../elements/story";
+/**
+ * The story's half of the puppet seam.
+ *
+ * Two kinds of thing happen here, and the line between them is the same one
+ * {@link import("../../game/puppet/puppetBackend").PuppetState} draws:
+ *
+ * - The five `set*` types edit the persistent state and then push **the whole of it** to the
+ *   backend. They never send a delta, because a delta is exactly what a saved game cannot replay —
+ *   restoring is one `apply` of a complete state, so an undo has to be one too.
+ * - `command` sends a one-shot the engine does not model and does not interpret. It leaves no state
+ *   behind, which is why it is the only one that can take `{await: true}` and the only one an undo
+ *   cannot take back.
+ */
+export declare class PuppetAction<T extends Values<typeof PuppetActionTypes> = Values<typeof PuppetActionTypes>> extends TypedAction<PuppetActionContentType, T, Puppet> {
+    static ActionTypes: {
+        readonly action: "puppet:action";
+        readonly setMotion: "puppet:setMotion";
+        readonly setExpression: "puppet:setExpression";
+        readonly setSkin: "puppet:setSkin";
+        readonly setParam: "puppet:setParam";
+        readonly setSlot: "puppet:setSlot";
+        readonly command: "puppet:command";
+    };
+    executeAction(state: GameState, injection: ActionExecutionInjection): ExecutedActionResult;
+    /**
+     * Write a patch over the puppet's state, then hand the backend the complete result.
+     *
+     * `params` and `slots` merge key by key, so setting one parameter does not silently clear the
+     * rest. Undo restores the state as it stood and applies that — one call, no replay, which is the
+     * same path a saved game takes.
+     */
+    private patchState;
+    /**
+     * Push the current state to the backend without making the story wait for it.
+     *
+     * A pose change is not a beat: an author writing `setExpression("smile")` before a line expects
+     * the line, not a pause of whatever length the renderer decides. A backend that throws or
+     * rejects is logged and the stage stays alive — it is a renderer this library has never seen,
+     * and it does not get to take the game down.
+     */
+    private pushState;
+    /**
+     * Forward a one-shot command, optionally waiting for it.
+     *
+     * Waiting is opt-in ({@link import("../../elements/displayable/puppet").PuppetCommandOptions}):
+     * the engine cannot know whether a command is a motion worth a beat or a parameter nudge, and
+     * defaulting to waiting would make every backend that forgets to resolve into a hung story.
+     */
+    private runCommand;
+    stringify(_story: Story, _seen: Set<LogicAction.Actions>, _strict: boolean): string;
+}

package/dist/game/nlcore/action/logicAction.d.ts

@@ -9,7 +9,7 @@ import type { StringKeyOf, Values } from "../../../util/data";
 import type { TypedAction } from "../action/actions";
 import type { Sound } from "../elements/sound";
 import type { Control } from "../elements/control";
-import { CharacterActionContentType, CharacterActionTypes, ConditionActionContentType, ConditionActionTypes, ControlActionContentType, ControlActionTypes, DisplayableActionContentType, DisplayableActionTypes, ImageActionContentType, ImageActionTypes, LayerActionContentType, LayerActionTypes, MenuActionContentType, MenuActionTypes, PersistentActionContentType, PersistentActionTypes, SceneActionContentType, SceneActionTypes, ScriptActionContentType, ScriptActionTypes, SoundActionContentType, SoundActionTypes, StoryActionContentType, StoryActionTypes, TextActionContentType, TextActionTypes, VfxActionContentType, VfxActionTypes, VideoActionContentType, VideoActionTypes } from "../action/actionTypes";
+import { CharacterActionContentType, CharacterActionTypes, ConditionActionContentType, ConditionActionTypes, ControlActionContentType, ControlActionTypes, DisplayableActionContentType, DisplayableActionTypes, ImageActionContentType, ImageActionTypes, LayerActionContentType, LayerActionTypes, MenuActionContentType, MenuActionTypes, PersistentActionContentType, PersistentActionTypes, PuppetActionContentType, PuppetActionTypes, SceneActionContentType, SceneActionTypes, ScriptActionContentType, ScriptActionTypes, SoundActionContentType, SoundActionTypes, StoryActionContentType, StoryActionTypes, TextActionContentType, TextActionTypes, VfxActionContentType, VfxActionTypes, VideoActionContentType, VideoActionTypes } from "../action/actionTypes";
 import type { CharacterAction } from "../action/actions/characterAction";
 import type { SceneAction } from "../action/actions/sceneAction";
 import type { StoryAction } from "../action/actions/storyAction";
@@ -35,21 +35,23 @@ import type { Video } from "../elements/video";
 import type { VideoAction } from "../action/actions/videoAction";
 import type { Vfx } from "../elements/vfx";
 import type { VfxAction } from "../action/actions/vfxAction";
+import type { Puppet } from "../elements/displayable/puppet";
+import type { PuppetAction } from "../action/actions/puppetAction";
 export interface LogicActionInterface {
-    DisplayableElements: Text | Image | Layer | Camera | AbstractDisplayable<any, any>;
-    DisplayableExposed: ExposedStateType.image | ExposedStateType.layer | ExposedStateType.text | ExposedStateType.camera;
-    GameElement: Character | Scene | Story | Image | Condition | Script | Menu | Sound | Control | Text | Layer | Camera | AbstractDisplayable<any, any> | Persistent<any> | ServiceSkeleton | Video | Vfx;
-    Actions: TypedAction | CharacterAction | ConditionAction | ImageAction | SceneAction | ScriptAction | StoryAction | MenuAction | SoundAction | ControlAction | TextAction | DisplayableAction | PersistentAction | ServiceAction | LayerAction | VideoAction | VfxAction;
-    ActionTypes: Values<typeof CharacterActionTypes> | Values<typeof ConditionActionTypes> | Values<typeof ImageActionTypes> | Values<typeof SceneActionTypes> | Values<typeof ScriptActionTypes> | Values<typeof StoryActionTypes> | Values<typeof MenuActionTypes> | Values<typeof SoundActionTypes> | Values<typeof ControlActionTypes> | Values<typeof TextActionTypes> | Values<typeof DisplayableActionTypes> | Values<typeof PersistentActionTypes> | StringKeyOf<ServiceActionContentType> | Values<typeof LayerActionTypes> | Values<typeof VideoActionTypes> | Values<typeof VfxActionTypes>;
-    ActionContents: CharacterActionContentType & ConditionActionContentType & ImageActionContentType & SceneActionContentType & ScriptActionContentType & StoryActionContentType & MenuActionContentType & SoundActionContentType & ControlActionContentType & TextActionContentType & DisplayableActionContentType & PersistentActionContentType & ServiceActionContentType & LayerActionContentType & VideoActionContentType & VfxActionContentType;
+    DisplayableElements: Text | Image | Layer | Camera | Puppet | AbstractDisplayable<any, any>;
+    DisplayableExposed: ExposedStateType.image | ExposedStateType.layer | ExposedStateType.text | ExposedStateType.camera | ExposedStateType.puppet;
+    GameElement: Character | Scene | Story | Image | Condition | Script | Menu | Sound | Control | Text | Layer | Camera | Puppet | AbstractDisplayable<any, any> | Persistent<any> | ServiceSkeleton | Video | Vfx;
+    Actions: TypedAction | CharacterAction | ConditionAction | ImageAction | SceneAction | ScriptAction | StoryAction | MenuAction | SoundAction | ControlAction | TextAction | DisplayableAction | PersistentAction | ServiceAction | LayerAction | VideoAction | VfxAction | PuppetAction;
+    ActionTypes: Values<typeof CharacterActionTypes> | Values<typeof ConditionActionTypes> | Values<typeof ImageActionTypes> | Values<typeof SceneActionTypes> | Values<typeof ScriptActionTypes> | Values<typeof StoryActionTypes> | Values<typeof MenuActionTypes> | Values<typeof SoundActionTypes> | Values<typeof ControlActionTypes> | Values<typeof TextActionTypes> | Values<typeof DisplayableActionTypes> | Values<typeof PersistentActionTypes> | StringKeyOf<ServiceActionContentType> | Values<typeof LayerActionTypes> | Values<typeof VideoActionTypes> | Values<typeof VfxActionTypes> | Values<typeof PuppetActionTypes>;
+    ActionContents: CharacterActionContentType & ConditionActionContentType & ImageActionContentType & SceneActionContentType & ScriptActionContentType & StoryActionContentType & MenuActionContentType & SoundActionContentType & ControlActionContentType & TextActionContentType & DisplayableActionContentType & PersistentActionContentType & ServiceActionContentType & LayerActionContentType & VideoActionContentType & VfxActionContentType & PuppetActionContentType;
 }
 export declare const LogicAction: {};
 export declare namespace LogicAction {
-    type DisplayableElements = Text | Image | Layer | Camera | AbstractDisplayable<any, any>;
-    type DisplayableExposed = ExposedStateType.image | ExposedStateType.layer | ExposedStateType.text | ExposedStateType.camera;
-    type GameElement = Character | Scene | Story | Image | Condition | Script | Menu | Sound | Control | Text | Layer | Camera | AbstractDisplayable<any, any> | Persistent<any> | ServiceSkeleton | Video | Vfx;
-    type Actions = TypedAction | CharacterAction | ConditionAction | ImageAction | SceneAction | ScriptAction | StoryAction | MenuAction | SoundAction | ControlAction | TextAction | DisplayableAction | PersistentAction | ServiceAction | LayerAction | VideoAction | VfxAction;
-    type ActionTypes = Values<typeof CharacterActionTypes> | Values<typeof ConditionActionTypes> | Values<typeof ImageActionTypes> | Values<typeof SceneActionTypes> | Values<typeof ScriptActionTypes> | Values<typeof StoryActionTypes> | Values<typeof MenuActionTypes> | Values<typeof SoundActionTypes> | Values<typeof ControlActionTypes> | Values<typeof TextActionTypes> | Values<typeof DisplayableActionTypes> | Values<typeof PersistentActionTypes> | StringKeyOf<ServiceActionContentType> | Values<typeof LayerActionTypes> | Values<typeof VideoActionTypes> | Values<typeof VfxActionTypes>;
-    type ActionContents = CharacterActionContentType & ConditionActionContentType & ImageActionContentType & SceneActionContentType & ScriptActionContentType & StoryActionContentType & MenuActionContentType & SoundActionContentType & ControlActionContentType & TextActionContentType & DisplayableActionContentType & PersistentActionContentType & ServiceActionContentType & LayerActionContentType & VideoActionContentType & VfxActionContentType;
+    type DisplayableElements = Text | Image | Layer | Camera | Puppet | AbstractDisplayable<any, any>;
+    type DisplayableExposed = ExposedStateType.image | ExposedStateType.layer | ExposedStateType.text | ExposedStateType.camera | ExposedStateType.puppet;
+    type GameElement = Character | Scene | Story | Image | Condition | Script | Menu | Sound | Control | Text | Layer | Camera | Puppet | AbstractDisplayable<any, any> | Persistent<any> | ServiceSkeleton | Video | Vfx;
+    type Actions = TypedAction | CharacterAction | ConditionAction | ImageAction | SceneAction | ScriptAction | StoryAction | MenuAction | SoundAction | ControlAction | TextAction | DisplayableAction | PersistentAction | ServiceAction | LayerAction | VideoAction | VfxAction | PuppetAction;
+    type ActionTypes = Values<typeof CharacterActionTypes> | Values<typeof ConditionActionTypes> | Values<typeof ImageActionTypes> | Values<typeof SceneActionTypes> | Values<typeof ScriptActionTypes> | Values<typeof StoryActionTypes> | Values<typeof MenuActionTypes> | Values<typeof SoundActionTypes> | Values<typeof ControlActionTypes> | Values<typeof TextActionTypes> | Values<typeof DisplayableActionTypes> | Values<typeof PersistentActionTypes> | StringKeyOf<ServiceActionContentType> | Values<typeof LayerActionTypes> | Values<typeof VideoActionTypes> | Values<typeof VfxActionTypes> | Values<typeof PuppetActionTypes>;
+    type ActionContents = CharacterActionContentType & ConditionActionContentType & ImageActionContentType & SceneActionContentType & ScriptActionContentType & StoryActionContentType & MenuActionContentType & SoundActionContentType & ControlActionContentType & TextActionContentType & DisplayableActionContentType & PersistentActionContentType & ServiceActionContentType & LayerActionContentType & VideoActionContentType & VfxActionContentType & PuppetActionContentType;
 }
 export type LogicAction = typeof LogicAction;

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

@@ -19,9 +19,12 @@ import { Layer } from "../elements/layer";
 import { Camera } from "../elements/camera";
 import { Video } from "../elements/video";
 import { Vfx } from "../elements/vfx";
+import { Puppet } from "../elements/displayable/puppet";
 import { NVLToken } from "../elements/nvl";
-export { Character, Narrator, Condition, Control, Image, Lambda, Menu, NVLToken, Scene, Script, Sentence, Sound, Story, Transform, Word, Text, Pause, TextEvent, Persistent, Service, Layer, Camera, Video, Vfx, };
+export { Character, Narrator, Condition, Control, Image, Lambda, Menu, NVLToken, Scene, Script, Sentence, Sound, Story, Transform, Word, Text, Pause, TextEvent, Persistent, Service, Layer, Camera, Video, Vfx, Puppet, };
 export type { VfxConfig, VfxBlendMode, VfxFadeOptions } from "../elements/vfx";
+export type { IPuppetUserConfig, PuppetConfig, PuppetCommandOptions, } from "../elements/displayable/puppet";
+export type { PuppetBackend, PuppetDescription, PuppetInstance, PuppetMountContext, PuppetSize, PuppetState, PuppetStatus, } from "../game/puppet/puppetBackend";
 export type { LayeredDefinition, LayerGroupDefinition, LayerResolver, LayerSlot, LayerTagsOf, LayerVariants, } from "../elements/displayable/image";
 export type { SentenceMetadata } from "../elements/character/sentence";
 export type { TextEventAppearance, TextEventConfig, TextEventExpression, } from "../elements/character/textEvent";

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

@@ -4,9 +4,12 @@ import { GameState } from "../../common/game";
 import { LogicAction } from "../../game";
 import type { LiveGameEventToken } from "../../types";
 import { Image } from "../displayable/image";
+import { Puppet } from "../displayable/puppet";
 import { Layer } from "../layer";
 import { DynamicPersistent, Persistent } from "../persistent";
 import { Scene } from "../scene";
+import type { Game } from "../../game";
+import type { PuppetDescription, PuppetState, PuppetStatus } from "../../game/puppet/puppetBackend";
 /** Snapshot of the dialog line currently presented to the player (ADV or NVL). */
 export type DevToolsCurrentDialog = {
     /** Id of the say action that produced the line (static id when assigned). */
@@ -68,6 +71,56 @@ export declare class DevTools {
     static setDisplayableTransformProps(gameState: GameState, displayable: LogicAction.DisplayableElements, props: Record<string, unknown>, options?: {
         merge?: boolean;
     }): void;
+    /**
+     * The current state of a puppet's backend instance.
+     *
+     * `"missing-backend"` is the one an editor host should surface loudly: the element is on stage
+     * and behaving in every other respect, but nothing is drawing it, because the renderer the
+     * project depends on was never registered.
+     */
+    static getPuppetStatus(puppet: Puppet): PuppetStatus;
+    /**
+     * Subscribe to a puppet's status changes. The listener receives the new status.
+     */
+    static onPuppetStatusChange(puppet: Puppet, listener: (status: PuppetStatus) => void): LiveGameEventToken;
+    /**
+     * Ask a puppet's backend to describe its model — the motions, expressions, skins and parameters
+     * it can be driven with.
+     *
+     * This is what keeps model-format parsers out of an editor host: the inspector fills its
+     * dropdowns from the live instance. Returns null when the puppet is not mounted or its backend
+     * does not implement `describe`, in which case a host should fall back to free text.
+     */
+    static describePuppet(gameState: GameState, puppet: Puppet): Promise<PuppetDescription | null>;
+    /**
+     * Read a puppet's persistent state. Returns a copy, `params` and `slots` included, so a host can
+     * hold on to it without aliasing the element.
+     */
+    static getPuppetState(puppet: Puppet): PuppetState;
+    /**
+     * Overwrite a puppet's state and push it to the backend at once, without going through an
+     * action (so nothing lands in the story's history).
+     *
+     * By default the patch is merged over the current state, with `params` and `slots` merged key by
+     * key; with `merge: false` the state is replaced outright. Applying to an unmounted puppet is
+     * valid and does not warn — the state is complete by construction, so it is applied in full the
+     * next time the element mounts.
+     */
+    static setPuppetState(gameState: GameState, puppet: Puppet, patch: Partial<PuppetState>, options?: {
+        merge?: boolean;
+    }): void;
+    /**
+     * Run a named command on a puppet's backend and wait for it.
+     *
+     * The engine never interprets the command; it is the escape hatch for everything the persistent
+     * state deliberately does not model (one-shot motions, hit tests, lip sync). Resolves without
+     * doing anything when the puppet is not mounted.
+     */
+    static runPuppetCommand(gameState: GameState, puppet: Puppet, name: string, payload: unknown): Promise<void>;
+    /**
+     * The names of every puppet backend registered on this game.
+     */
+    static listPuppetBackends(game: Game): string[];
     /**
      * Read the dialog line currently presented to the player, or null when no
      * dialog is on screen. Covers both ADV (tracked via GameState.beginAdvDialog)

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

@@ -1,5 +1,5 @@
-import { Control, Layer } from "narraleaf-react";
-import type { Scene, TransformDefinitions } from "narraleaf-react";
+import { Control, Layer } from "../../common/core";
+import type { Scene, TransformDefinitions } from "../../common/core";
 export type ScreenEffectColor = string | {
     r: number;
     g: number;

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

@@ -11,6 +11,9 @@ import { Chained, Proxied } from "../action/chain";
  * rotation, opacity, filter, ...).
  */
 export type ICameraUserConfig = TransformDefinitions.ImageTransformProps;
+export type CameraDataRaw = {
+    transformState: Record<string, any>;
+};
 /**
  * A stage-wide camera.
  *

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

@@ -1,7 +1,7 @@
 export type PauseConfig = {
     duration?: number;
 };
-export type Pausing = Pause | PausingShortcut;
+export type Pausing = Pause | typeof Pause;
 export declare class Pause {
     /**
      * Create a pause with specific duration (milliseconds) that blocks until it passes.

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

@@ -11,6 +11,9 @@ export type CharacterConfig = {
     avatar?: DialogAvatar | false;
     portraits: (Image | CharacterPortraitConfig)[];
 };
+export type CharacterStateData = {
+    name: string;
+};
 export interface Character {
     (content: string, config?: SentenceUserConfig): Proxied<Character, Chained<LogicAction.Actions>>;
     (content: Sentence): Proxied<Character, Chained<LogicAction.Actions>>;

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

@@ -4,6 +4,19 @@ import { Chained, Proxied } from "../action/chain";
 import { LambdaHandler, ActionStatements } from "../elements/type";
 export declare class Lambda<T = any> {
 }
+export type ConditionData = {
+    If: {
+        condition: Lambda | null;
+        action: LogicAction.Actions[] | null;
+    };
+    ElseIf: {
+        condition: Lambda | null;
+        action: (LogicAction.Actions[]) | null;
+    }[];
+    Else: {
+        action: (LogicAction.Actions[]) | null;
+    };
+};
 export declare class Condition<Closed extends true | false = false> extends Actionable<null, Condition<true | false>> {
     /**
      * Create a new conditional branch that only runs when the condition is true.

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

@@ -1,7 +1,12 @@
 import { Actionable } from "../action/actionable";
+import { LogicAction } from "../action/logicAction";
 import { Awaitable } from "../../../util/data";
+import { Chained, Proxied } from "../action/chain";
 import { ActionStatements, LambdaHandler } from "./type";
 import { Lambda } from "./condition";
+export type ControlConfig = {
+    allowFutureScene: boolean;
+};
 export declare class Control extends Actionable {
     /**
      * Execute actions in order, waiting for each action to complete.
@@ -12,7 +17,7 @@ export declare class Control extends Actionable {
      * Control.do([character.say("hello"), image.char("path.png")]);
      * ```
      */
-    static do(actions: ActionStatements): ChainedControl;
+    static do(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute actions in order without waiting for completion.
      * @param actions - Actions to run sequentially.
@@ -22,7 +27,7 @@ export declare class Control extends Actionable {
      * Control.doAsync([sound.play(), image.char("path.png")]);
      * ```
      */
-    static doAsync(actions: ActionStatements): ChainedControl;
+    static doAsync(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute actions concurrently, resolving once any finishes.
      *
@@ -37,7 +42,7 @@ export declare class Control extends Actionable {
      * Control.any([sound.play(), image.char("happy.png")]);
      * ```
      */
-    static any(actions: ActionStatements): ChainedControl;
+    static any(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute actions concurrently and wait until all finish.
      *
@@ -52,7 +57,7 @@ export declare class Control extends Actionable {
      * Control.all([sound.play(), dialog.show()]);
      * ```
      */
-    static all(actions: ActionStatements): ChainedControl;
+    static all(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute actions concurrently and continue without waiting.
      *
@@ -63,7 +68,7 @@ export declare class Control extends Actionable {
      * @param actions - Actions to fire simultaneously.
      * @chainable
      */
-    static allAsync(actions: ActionStatements): ChainedControl;
+    static allAsync(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute actions multiple times.
      * @param times - How many times to repeat.
@@ -74,26 +79,26 @@ export declare class Control extends Actionable {
      * Control.repeat(3, [character.say("Again!")]);
      * ```
      */
-    static repeat(times: number, actions: ActionStatements): ChainedControl;
+    static repeat(times: number, actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Repeat actions while a condition stays true.
      * @param condition - Lambda to guard the loop.
      * @param actions - Body actions to run each iteration.
      * @chainable
      */
-    static whileLoop(condition: Lambda<boolean> | LambdaHandler<boolean>, actions: ActionStatements): ChainedControl;
+    static whileLoop(condition: Lambda<boolean> | LambdaHandler<boolean>, actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Break out of the nearest repeating loop (repeat or while).
      * Can only be used inside a loop body.
      * @chainable
      */
-    static breakLoop(): ChainedControl;
+    static breakLoop(): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Pause execution for a duration or until an `Awaitable` resolves.
      * @param duration - Milliseconds or awaitable controlling the pause length.
      * @chainable
      */
-    static sleep(duration: number | Awaitable<any> | Promise<any>): ChainedControl;
+    static sleep(duration: number | Awaitable<any> | Promise<any>): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * 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.
@@ -103,7 +108,7 @@ export declare class Control extends Actionable {
      * Control.waitForClick();
      * ```
      */
-    static waitForClick(): ChainedControl;
+    static waitForClick(): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Mark a named point inside the current scene that {@link Control.jump} can jump to.
      * A label is invisible at runtime — it simply passes through to the next action.
@@ -120,7 +125,7 @@ export declare class Control extends Actionable {
      * ]);
      * ```
      */
-    static label(name: string): ChainedControl;
+    static label(name: string): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Jump to a {@link Control.label} elsewhere in the same scene and resume playing from there.
      *
@@ -140,67 +145,67 @@ export declare class Control extends Actionable {
      * ]);
      * ```
      */
-    static jump(name: string): ChainedControl;
+    static jump(name: string): Proxied<Control, Chained<LogicAction.Actions>>;
     constructor(/**@internal */ config?: Partial<ControlConfig>);
     /**
      * Execute actions in order, waiting for each action to complete
      * @chainable
      */
-    do(actions: ActionStatements): ChainedControl;
+    do(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute actions in order, do not wait for this action to complete
      * @chainable
      */
-    doAsync(actions: ActionStatements): ChainedControl;
+    doAsync(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute all actions at the same time, waiting for any one action to complete
      * @chainable
      */
-    any(actions: ActionStatements): ChainedControl;
+    any(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute all actions at the same time, waiting for all actions to complete
      * @chainable
      */
-    all(actions: ActionStatements): ChainedControl;
+    all(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute all actions at the same time, do not wait for all actions to complete
      * @chainable
      */
-    allAsync(actions: ActionStatements): ChainedControl;
+    allAsync(actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute actions multiple times
      * @chainable
      */
-    repeat(times: number, actions: ActionStatements): ChainedControl;
+    repeat(times: number, actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Execute actions while condition is true
      * @chainable
      */
-    whileLoop(condition: Lambda<boolean> | LambdaHandler<boolean>, actions: ActionStatements): ChainedControl;
+    whileLoop(condition: Lambda<boolean> | LambdaHandler<boolean>, actions: ActionStatements): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Break the current loop (repeat/while)
      * Can only be used inside a loop body
      * @chainable
      */
-    breakLoop(): ChainedControl;
+    breakLoop(): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Sleep for a duration
      * @chainable
      */
-    sleep(duration: number | Awaitable<any> | Promise<any>): ChainedControl;
+    sleep(duration: number | Awaitable<any> | Promise<any>): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Wait for user to click the stage (excluding GUI elements)
      * @chainable
      */
-    waitForClick(): ChainedControl;
+    waitForClick(): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Mark a named point inside the current scene that {@link Control.jump} can jump to.
      * @chainable
      */
-    label(name: string): ChainedControl;
+    label(name: string): Proxied<Control, Chained<LogicAction.Actions>>;
     /**
      * Jump to a {@link Control.label} in the same scene and resume playing from there.
      * @chainable
      */
-    jump(name: string): ChainedControl;
+    jump(name: string): Proxied<Control, Chained<LogicAction.Actions>>;
 }

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

@@ -43,6 +43,10 @@ export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGro
      */
     darkness?: number;
 }
+export type ImageDataRaw = {
+    state: Record<string, any>;
+    transformState: Record<string, any>;
+};
 export type TagGroupDefinition = string[][];
 export type TagSrcResolver<T extends TagGroupDefinition> = (...tags: SelectElementFromEach<T>) => string;
 /**