narraleaf-react 0.14.0 → 0.16.0

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

@@ -15,6 +15,7 @@ import type { FadeOptions } from "../elements/type";
 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";
 export declare const DisplayableActionTypes: {
     readonly action: "displayable:action";
     readonly applyTransform: "displayable:applyTransform";
@@ -112,9 +113,11 @@ export declare const ControlActionTypes: {
     readonly break: "control:break";
     readonly sleep: "control:sleep";
     readonly waitForClick: "control:waitForClick";
+    readonly label: "control:label";
+    readonly jump: "control:jump";
 };
 export type ControlActionContentType = {
-    [K in typeof ControlActionTypes[keyof typeof ControlActionTypes]]: K extends "control:do" ? [LogicAction.Actions[]] : K extends "control:doAsync" ? [LogicAction.Actions[]] : K extends "control:any" ? [LogicAction.Actions[]] : K extends "control:all" ? [LogicAction.Actions[]] : K extends "control:parallel" ? [LogicAction.Actions[]] : K extends "control:allAsync" ? [LogicAction.Actions[]] : K extends "control:repeat" ? [LogicAction.Actions[], number] : K extends "control:while" ? [LogicAction.Actions[], Lambda<boolean>] : K extends "control:break" ? [] : K extends "control:sleep" ? [LogicAction.Actions[], number | Awaitable<any> | Promise<any>] : K extends "control:waitForClick" ? [] : any;
+    [K in typeof ControlActionTypes[keyof typeof ControlActionTypes]]: K extends "control:do" ? [LogicAction.Actions[]] : K extends "control:doAsync" ? [LogicAction.Actions[]] : K extends "control:any" ? [LogicAction.Actions[]] : K extends "control:all" ? [LogicAction.Actions[]] : K extends "control:parallel" ? [LogicAction.Actions[]] : K extends "control:allAsync" ? [LogicAction.Actions[]] : K extends "control:repeat" ? [LogicAction.Actions[], number] : K extends "control:while" ? [LogicAction.Actions[], Lambda<boolean>] : K extends "control:break" ? [] : K extends "control:sleep" ? [LogicAction.Actions[], number | Awaitable<any> | Promise<any>] : K extends "control:waitForClick" ? [] : K extends "control:label" ? [string] : K extends "control:jump" ? [string] : any;
 };
 export declare const TextActionTypes: {
     readonly action: "text:action";
@@ -150,5 +153,16 @@ export declare const VideoActionTypes: {
     readonly seek: "video:seek";
 };
 export type VideoActionContentType = {
-    [K in typeof VideoActionTypes[keyof typeof VideoActionTypes]]: K extends "video:action" ? any : K extends "video:show" | "video:hide" | "video:play" | "video:pause" | "video:stop" ? [] : K extends "video:seek" ? [number] : any;
+    [K in typeof VideoActionTypes[keyof typeof VideoActionTypes]]: K extends "video:action" ? any : K extends "video:show" | "video:hide" | "video:play" | "video:pause" | "video:stop" | "video:resume" ? [] : K extends "video:seek" ? [number] : any;
+};
+export declare const VfxActionTypes: {
+    readonly action: "vfx:action";
+    readonly show: "vfx:show";
+    readonly hide: "vfx:hide";
+    readonly pause: "vfx:pause";
+    readonly resume: "vfx:resume";
+    readonly setRate: "vfx:setRate";
+};
+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;
 };

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

@@ -20,6 +20,8 @@ export declare class ControlAction<T extends typeof ControlActionTypes[keyof typ
         readonly break: "control:break";
         readonly sleep: "control:sleep";
         readonly waitForClick: "control:waitForClick";
+        readonly label: "control:label";
+        readonly jump: "control:jump";
     };
     static executeActionsAsync(gameState: GameState, action: LogicAction.Actions): Awaitable<void>;
     checkActionChain(actions: LogicAction.Actions[]): LogicAction.Actions[];

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

@@ -0,0 +1,24 @@
+import { VfxActionContentType, VfxActionTypes } from "../../action/actionTypes";
+import { TypedAction } from "../../action/actions";
+import { Vfx } from "../../elements/vfx";
+import { GameState } from "../../../player/gameState";
+import { Awaitable, Values } from "../../../../util/data";
+import type { CalledActionResult } from "../../gameTypes";
+import { ActionExecutionInjection } from "../../action/action";
+import { LogicAction } from "../../action/logicAction";
+import { Story } from "../../elements/story";
+export declare class VfxAction<T extends Values<typeof VfxActionTypes> = Values<typeof VfxActionTypes>> extends TypedAction<VfxActionContentType, T, Vfx> {
+    static ActionTypes: {
+        readonly action: "vfx:action";
+        readonly show: "vfx:show";
+        readonly hide: "vfx:hide";
+        readonly pause: "vfx:pause";
+        readonly resume: "vfx:resume";
+        readonly setRate: "vfx:setRate";
+    };
+    executeAction(gameState: GameState, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
+    private changeStateBase;
+    private changeState;
+    private changeStateAsync;
+    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, VideoActionContentType, VideoActionTypes } from "../action/actionTypes";
+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 type { CharacterAction } from "../action/actions/characterAction";
 import type { SceneAction } from "../action/actions/sceneAction";
 import type { StoryAction } from "../action/actions/storyAction";
@@ -29,24 +29,27 @@ import type { ServiceSkeleton } from "../elements/service";
 import type { ServiceAction, ServiceActionContentType } from "../action/serviceAction";
 import type { Layer } from "../elements/layer";
 import type { LayerAction } from "../action/actions/layerAction";
+import type { Camera } from "../elements/camera";
 import type { ExposedStateType } from "../../player/type";
 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";
 export interface LogicActionInterface {
-    DisplayableElements: Text | Image | Layer | AbstractDisplayable<any, any>;
-    DisplayableExposed: ExposedStateType.image | ExposedStateType.layer | ExposedStateType.text;
-    GameElement: Character | Scene | Story | Image | Condition | Script | Menu | Sound | Control | Text | AbstractDisplayable<any, any> | Persistent<any> | ServiceSkeleton | Video;
-    Actions: TypedAction | CharacterAction | ConditionAction | ImageAction | SceneAction | ScriptAction | StoryAction | MenuAction | SoundAction | ControlAction | TextAction | DisplayableAction | PersistentAction | ServiceAction | LayerAction | VideoAction;
-    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>;
-    ActionContents: CharacterActionContentType & ConditionActionContentType & ImageActionContentType & SceneActionContentType & ScriptActionContentType & StoryActionContentType & MenuActionContentType & SoundActionContentType & ControlActionContentType & TextActionContentType & DisplayableActionContentType & PersistentActionContentType & ServiceActionContentType & LayerActionContentType & VideoActionContentType;
+    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;
 }
 export declare const LogicAction: {};
 export declare namespace LogicAction {
-    type DisplayableElements = Text | Image | Layer | AbstractDisplayable<any, any>;
-    type DisplayableExposed = ExposedStateType.image | ExposedStateType.layer | ExposedStateType.text;
-    type GameElement = Character | Scene | Story | Image | Condition | Script | Menu | Sound | Control | Text | AbstractDisplayable<any, any> | Persistent<any> | ServiceSkeleton | Video;
-    type Actions = TypedAction | CharacterAction | ConditionAction | ImageAction | SceneAction | ScriptAction | StoryAction | MenuAction | SoundAction | ControlAction | TextAction | DisplayableAction | PersistentAction | ServiceAction | LayerAction | VideoAction;
-    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>;
-    type ActionContents = CharacterActionContentType & ConditionActionContentType & ImageActionContentType & SceneActionContentType & ScriptActionContentType & StoryActionContentType & MenuActionContentType & SoundActionContentType & ControlActionContentType & TextActionContentType & DisplayableActionContentType & PersistentActionContentType & ServiceActionContentType & LayerActionContentType & VideoActionContentType;
+    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;
 }
 export type LogicAction = typeof LogicAction;

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

@@ -61,6 +61,34 @@ export type StackModelRawData = {
     items: StackModelItemData[];
     loop?: StackModelLoopRawData;
 };
+/**
+ * One frame of a read-only {@link StackModel.snapshot} — an action currently on the execution
+ * stack. A frame that is a concurrent group ({@link Control.all}/{@link Control.any}) also lists
+ * its branches (each a top-to-bottom frame list).
+ *
+ * **Experimental / read-only.** For tooling (Studio's call-stack view). The exact shape is not a
+ * stable contract and may change; do not serialize it or drive game logic from it.
+ */
+export type StackFrameSnapshot = {
+    actionId: string | null;
+    actionType: string | null;
+    branchWaitType?: StackModelWaiting["type"];
+    branches?: StackFrameSnapshot[][];
+};
+/**
+ * Read-only view of a StackModel's execution stack. `frames` are ordered top-first (the frame
+ * currently executing is `frames[0]`). See {@link StackFrameSnapshot} — experimental.
+ */
+export type StackSnapshot = {
+    tag?: string;
+    frames: StackFrameSnapshot[];
+    loop?: {
+        type: StackModelLoopType;
+        counter: number;
+        limit?: number;
+        broken: boolean;
+    };
+};
 export declare class StackModel {
     private liveGame;
     __tag: string | undefined;

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

@@ -12,12 +12,17 @@ import { Sentence } from "../elements/character/sentence";
 import { Word } from "../elements/character/word";
 import { Text } from "../elements/displayable/text";
 import { Pause } from "../elements/character/pause";
+import { TextEvent } from "../elements/character/textEvent";
 import { Persistent } from "../elements/persistent";
 import { Service } from "../elements/service";
 import { Layer } from "../elements/layer";
+import { Camera } from "../elements/camera";
 import { Video } from "../elements/video";
+import { Vfx } from "../elements/vfx";
 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 { 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 type { VfxConfig, VfxBlendMode, VfxFadeOptions } from "../elements/vfx";
 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";
 export type { CharacterPortraitConfig, DialogAvatar, DialogAvatarResolver, DialogAvatarResolverContext, DialogAvatarResolution, DialogAvatarSource, } from "../elements/character/avatar";

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

@@ -4,6 +4,7 @@ import { Storable, Namespace } from "../elements/persistent/storable";
 import { LiveGame } from "../game/liveGame";
 import { Preference } from "../game/preference";
 import type { SavedGame } from "../gameTypes";
+import type { StackSnapshot, StackFrameSnapshot } from "../action/stackModel";
 import { KeyMap } from "../game/keyMap";
 export { LiveGame, GameState, Game, Storable, Namespace, Preference, KeyMap, };
-export type { SavedGame, };
+export type { SavedGame, StackSnapshot, StackFrameSnapshot, };

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

@@ -1,20 +1,19 @@
 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";
-import { SoftWipe } from "../elements/transition/transitions/image/softWipe";
-import { Blinds } from "../elements/transition/transitions/image/blinds";
-import { SoftIris } from "../elements/transition/transitions/image/softIris";
 import { BlurDissolve } from "../elements/transition/transitions/image/blurDissolve";
 import { Push } from "../elements/transition/transitions/image/push";
 import { ThroughColor } from "../elements/transition/transitions/image/throughColor";
-export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, MaskTransition, SoftWipe, Blinds, SoftIris, BlurDissolve, Push, ThroughColor, };
-export type { SoftWipeOptions } from "../elements/transition/transitions/image/softWipe";
-export type { BlindsOptions } from "../elements/transition/transitions/image/blinds";
-export type { SoftIrisOptions } from "../elements/transition/transitions/image/softIris";
+import { Reveal } from "../elements/transition/transitions/image/reveal";
+import { Mask } from "../elements/transition/transitions/image/mask";
+export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, BlurDissolve, Push, ThroughColor, Reveal, Mask, };
+export type { DissolveOptions } from "../elements/transition/transitions/image/dissolve";
+export type { FadeInOptions } from "../elements/transition/transitions/image/fadeIn";
 export type { BlurDissolveOptions } from "../elements/transition/transitions/image/blurDissolve";
 export type { PushOptions } from "../elements/transition/transitions/image/push";
-export type { ThroughColorFadeOptions, ThroughColorWipeOptions, ThroughColorBlindsOptions, ThroughColorIrisOptions, } from "../elements/transition/transitions/image/throughColor";
+export type { ThroughColorOptions, ThroughColorUncover, } from "../elements/transition/transitions/image/throughColor";
+export type { RevealOptions } from "../elements/transition/transitions/image/reveal";
+export type { MaskPattern, WipePatternOptions, BarnDoorPatternOptions, IrisPatternOptions, ClockPatternOptions, FanPatternOptions, BlindsPatternOptions, DotsPatternOptions, } from "../elements/transition/transitions/image/mask";
 export type { BlindsOrientation } from "../elements/transition/transitions/image/transitionMaskUtils";

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

@@ -0,0 +1,71 @@
+import { LogicAction } from "../action/logicAction";
+import { TransformDefinitions } from "../elements/transform/type";
+import { Displayable } from "../elements/displayable/displayable";
+import { EventfulDisplayable } from "../../player/elements/displayable/type";
+import { Chained, Proxied } from "../action/chain";
+/**
+ * The public constructor config for a {@link Camera}.
+ *
+ * A camera is transformed exactly like any other displayable, so its initial pose is described
+ * with the same {@link TransformDefinitions.ImageTransformProps} fields (position, zoom, scale,
+ * rotation, opacity, filter, ...).
+ */
+export type ICameraUserConfig = TransformDefinitions.ImageTransformProps;
+/**
+ * A stage-wide camera.
+ *
+ * The camera applies a {@link Transform} (pan / zoom / rotate / scale / opacity) and a
+ * darken/color-grade to the **whole stage as a single unit** — every scene, its backgrounds and
+ * sprites, and videos move together, while the dialog box, menus and NVL layer stay fixed.
+ *
+ * A story always has one default camera, reachable as {@link Story.camera}; you rarely construct
+ * one yourself. Camera actions are authored like any other displayable action:
+ *
+ * @example
+ * ```ts
+ * scene.action([
+ *     story.camera.zoom(2, 800, "easeInOut"),  // zoom the whole stage in
+ *     story.camera.pan({ xalign: 0.3 }, 800),  // slide the view left
+ *     story.camera.darken(0.6, 500),           // dim the stage
+ *     jS`It's getting dark...`,
+ *     story.camera.reset(600),                 // return to the neutral pose
+ * ]);
+ * ```
+ */
+export declare class Camera extends Displayable<CameraDataRaw, Camera, TransformDefinitions.ImageTransformProps> implements EventfulDisplayable {
+    /**
+     * Create a camera. A story already owns a default one ({@link Story.camera}); construct your
+     * own only to override the initial pose via the story config.
+     * @param config - Optional initial pose (zoom, position, rotation, ...).
+     * @example
+     * ```ts
+     * const camera = new Camera({ zoom: 1.2 });
+     * const story = new Story("entry", { camera });
+     * ```
+     */
+    constructor(config?: Partial<ICameraUserConfig>);
+    /**
+     * Pan the camera so the given position sits at the centre of the view.
+     *
+     * Alias of {@link Displayable.pos} with camera-oriented naming.
+     * @chainable
+     */
+    pan(position: TransformDefinitions.ImageTransformProps["position"], duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions>>;
+    /**
+     * Darken the whole stage.
+     *
+     * Uses the same mechanism as {@link Image.darken}: it drives the camera's CSS `filter` to
+     * `brightness(1 - darkness)`. Because darken shares the single `filter` channel, combining it
+     * with other filters (e.g. `blur`) means writing the full filter string yourself via
+     * {@link Displayable.filter}.
+     * @param darkness - How dark, between `0` (normal) and `1` (black).
+     * @chainable
+     */
+    darken(darkness: number, duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
+    /**
+     * Return the camera to its neutral pose: centred, zoom `1`, no rotation, fully opaque and no
+     * filter (which also clears {@link Camera.darken}).
+     * @chainable
+     */
+    reset(duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
+}

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

@@ -1,5 +1,6 @@
 import type { Character } from "../../elements/character";
 import { Pausing } from "../../elements/character/pause";
+import { TextEvent } from "../../elements/character/textEvent";
 import { Word } from "../../elements/character/word";
 import type { ScriptCtx } from "../../elements/script";
 import { Sound } from "../../elements/sound";
@@ -26,7 +27,7 @@ export type SentenceUserConfig = Partial<Omit<SentenceConfig, "voice"> & {
 }>;
 export type DynamicWord = (ctx: ScriptCtx) => DynamicWordResult;
 export type DynamicWordResult = string | Word | Pausing | (string | Word | Pausing)[];
-export type StaticWord<T extends string | DynamicWord | Pausing = string | DynamicWord | Pausing> = string | Pausing | Word<T>;
+export type StaticWord<T extends string | DynamicWord | Pausing | TextEvent = string | DynamicWord | Pausing | TextEvent> = string | Pausing | TextEvent | Word<T>;
 export type SingleWord = StaticWord | DynamicWord;
 export type SentencePrompt = SingleWord[] | SingleWord;
 export declare class Sentence {

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

@@ -0,0 +1,67 @@
+import type { Color, ImageSrc } from "../../types";
+import type { Image } from "../../elements/displayable/image";
+import type { Sound } from "../../elements/sound";
+/**
+ * The appearance a text-event may switch a character/image to when the typewriter reaches it.
+ * Mirrors the runtime forms {@link Image.char} accepts: a tag list (array), or a static
+ * `src`/`Color`. A bare string is treated as a `src` (as with `char`), so tag switches must be an
+ * array (e.g. `["happy"]`).
+ */
+export type TextEventAppearance = ImageSrc | Color | string[];
+/**
+ * A character-expression effect: switch `image` to `appearance` (no transition — the swap is
+ * instant, applied directly to the element the moment the typewriter reveals this point).
+ */
+export type TextEventExpression = {
+    image: Image;
+    appearance: TextEventAppearance;
+};
+/**
+ * The (deliberately restricted) closed set of effects a first-version text-event may carry:
+ * a character-expression switch and/or a sound effect. It is NOT a general action escape hatch —
+ * the effect is applied directly to element state, never pushed onto the execution stack.
+ */
+export type TextEventConfig = {
+    expression?: TextEventExpression;
+    sound?: Sound;
+};
+/**
+ * An inline dialogue token that fires a restricted side effect when the typewriter reveals it —
+ * the text analogue of {@link Pause}. Unlike a normal {@link Word} it renders nothing; unlike an
+ * action it never enters the stack model, so it adds no save burden. Its effect rides on the
+ * ordinary element state (which IS serialized) and re-fires naturally when the owning `say` action
+ * is re-evaluated.
+ *
+ * First version carries a closed set: a character-expression switch and/or a sound effect.
+ *
+ * @example
+ * ```ts
+ * // switch Alice's portrait to "angry" the moment the typewriter reaches this point
+ * character.say(["Don't ", TextEvent.expression(alice, ["angry"]), "test me."]);
+ * // play a sting, no expression change
+ * character.say(["...", TextEvent.sound(sting)]);
+ * ```
+ */
+export declare class TextEvent {
+    /**
+     * Build a text-event that switches an image's appearance (a character portrait/expression)
+     * when the typewriter reveals it, optionally alongside a sound effect.
+     * @param image - The image whose appearance is switched.
+     * @param appearance - Tag list (e.g. `["happy"]`) or a static `src`/`Color`.
+     * @param options - Optional extras; `sound` plays a sound effect at the same point.
+     */
+    static expression(image: Image, appearance: TextEventAppearance, options?: {
+        sound?: Sound;
+    }): TextEvent;
+    /**
+     * Build a text-event that only plays a sound effect when the typewriter reveals it.
+     * @param sound - The sound effect to play.
+     */
+    static sound(sound: Sound): TextEvent;
+    /**
+     * Build a text-event from an explicit effect descriptor. Prefer the {@link TextEvent.expression}
+     * / {@link TextEvent.sound} factories for the common cases.
+     * @param config - The closed-set effect descriptor.
+     */
+    constructor(config: TextEventConfig);
+}

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

@@ -1,6 +1,7 @@
 import { Color, Font } from "../../types";
 import { DynamicWord } from "../../elements/character/sentence";
 import { Pausing } from "../../elements/character/pause";
+import { TextEvent } from "../../elements/character/textEvent";
 export type WordConfig = {
     className: string;
     ruby: string;
@@ -8,7 +9,7 @@ export type WordConfig = {
     pause: boolean;
     cps?: number;
 } & Font;
-export declare class Word<T extends string | DynamicWord | Pausing = string | DynamicWord | Pausing> {
+export declare class Word<T extends string | DynamicWord | Pausing | TextEvent = string | DynamicWord | Pausing | TextEvent> {
     static isWord(obj: any): obj is Word;
     /**
      * Create a word with an explicit color or re-color an existing word.

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

@@ -25,6 +25,11 @@ export declare class Control extends Actionable {
     static doAsync(actions: ActionStatements): ChainedControl;
     /**
      * Execute actions concurrently, resolving once any finishes.
+     *
+     * Each entry runs as its own parallel branch, so a single chained statement (e.g.
+     * `image.pos(a).pos(b)`) is split into multiple branches and they will conflict when
+     * they target the same element. Wrap sequential steps in `Control.do([...])` to keep
+     * them in one branch.
      * @param actions - Actions to run in parallel.
      * @chainable
      * @example
@@ -35,6 +40,11 @@ export declare class Control extends Actionable {
     static any(actions: ActionStatements): ChainedControl;
     /**
      * Execute actions concurrently and wait until all finish.
+     *
+     * Each entry runs as its own parallel branch, so a single chained statement (e.g.
+     * `image.pos(a).pos(b)`) is split into multiple branches and they will conflict when
+     * they target the same element. Wrap sequential steps in `Control.do([...])` to keep
+     * them in one branch.
      * @param actions - Actions to run at the same time.
      * @chainable
      * @example
@@ -45,6 +55,11 @@ export declare class Control extends Actionable {
     static all(actions: ActionStatements): ChainedControl;
     /**
      * Execute actions concurrently and continue without waiting.
+     *
+     * Each entry runs as its own parallel branch, so a single chained statement (e.g.
+     * `image.pos(a).pos(b)`) is split into multiple branches and they will conflict when
+     * they target the same element. Wrap sequential steps in `Control.do([...])` to keep
+     * them in one branch.
      * @param actions - Actions to fire simultaneously.
      * @chainable
      */
@@ -89,6 +104,43 @@ export declare class Control extends Actionable {
      * ```
      */
     static waitForClick(): ChainedControl;
+    /**
+     * 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.
+     *
+     * Label names are scoped to the scene they are declared in, so the same name may be
+     * reused across different scenes. Declaring the same name twice in one scene is an error.
+     * @param name - The label name, unique within its scene.
+     * @chainable
+     * @example
+     * ```ts
+     * scene.action([
+     *     Control.label("intro"),
+     *     character.say("Let's begin."),
+     * ]);
+     * ```
+     */
+    static label(name: string): ChainedControl;
+    /**
+     * Jump to a {@link Control.label} elsewhere in the same scene and resume playing from there.
+     *
+     * Unlike {@link Scene.jumpTo}, this stays inside the current scene — no scene is unloaded or
+     * re-initialized, only the play head moves. The jump target must be a label declared in the
+     * same scene, otherwise the story fails to build.
+     * @param name - The name of the target label, declared in the same scene.
+     * @chainable
+     * @example
+     * ```ts
+     * scene.action([
+     *     Control.label("start"),
+     *     menu("Again?", [
+     *         choice("Yes", [Control.jump("start")]),
+     *         choice("No", []),
+     *     ]),
+     * ]);
+     * ```
+     */
+    static jump(name: string): ChainedControl;
     constructor(/**@internal */ config?: Partial<ControlConfig>);
     /**
      * Execute actions in order, waiting for each action to complete
@@ -141,4 +193,14 @@ export declare class Control extends Actionable {
      * @chainable
      */
     waitForClick(): ChainedControl;
+    /**
+     * Mark a named point inside the current scene that {@link Control.jump} can jump to.
+     * @chainable
+     */
+    label(name: string): ChainedControl;
+    /**
+     * Jump to a {@link Control.label} in the same scene and resume playing from there.
+     * @chainable
+     */
+    jump(name: string): ChainedControl;
 }

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

@@ -104,11 +104,11 @@ export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefi
      * - Static image: the src will be a string or StaticImageData
      * @example
      * ```ts
-     * image.char("path/to/image.png", new Dissolve(1000));
+     * image.char("path/to/image.png", new Dissolve({duration: 1000}));
      * ```
      * @example
      * ```ts
-     * image.char(["happy", "t-shirt", "shorts"], new Dissolve(1000));
+     * image.char(["happy", "t-shirt", "shorts"], new Dissolve({duration: 1000}));
      * ```
      * @chainable
      */

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

@@ -51,7 +51,7 @@ export declare class Scene extends Constructable<LogicAction.Actions, Scene> {
      * @example
      * ```ts
      * scene.action([
-     *     scene.setBackground("#000", new FadeIn(1000))
+     *     scene.setBackground("#000", new FadeIn({duration: 1000}))
      * ]);
      * ```
      */
@@ -66,7 +66,7 @@ export declare class Scene extends Constructable<LogicAction.Actions, Scene> {
      * @example
      * ```ts
      * scene.action([
-     *     scene.jumpTo(nextScene, new FadeIn(800))
+     *     scene.jumpTo(nextScene, new FadeIn({duration: 800}))
      * ]);
      * ```
      */

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

@@ -3,6 +3,7 @@ import { Scene } from "../elements/scene";
 import { SceneAction } from "../action/actions/sceneAction";
 import { Persistent, PersistentContent } from "../elements/persistent";
 import { Service } from "../elements/service";
+import { Camera } from "../elements/camera";
 export declare enum Origins {
     topLeft = "top left",
     topRight = "top right",
@@ -11,9 +12,28 @@ export declare enum Origins {
 }
 export interface IStoryConfig {
     origin: Origins;
+    /**
+     * The story's stage {@link Camera}. Omit to use a default camera; provide one only to set the
+     * initial pose. There is exactly one camera per story.
+     */
+    camera?: Camera;
 }
 export declare class Story extends Constructable<SceneAction<"scene:action">, Story> {
-    constructor(name: string, config?: IStoryConfig);
+    constructor(name: string, config?: Partial<IStoryConfig>);
+    /**
+     * The story's stage camera.
+     *
+     * A single {@link Camera} that applies a transform and darken/color-grade to the whole stage
+     * as one unit, persisting across scene changes. Author camera actions like any other element:
+     * @example
+     * ```ts
+     * scene.action([
+     *     story.camera.zoom(1.5, 600),
+     *     story.camera.darken(0.5, 400),
+     * ]);
+     * ```
+     */
+    get camera(): Camera;
     /**
      * Set the entry scene of the story
      * @example

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

@@ -2,18 +2,25 @@ import { TransitionAnimationType, TransitionTask } from "../../../../elements/tr
 import { TransformDefinitions } from "../../../../elements/transform/type";
 import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
 type AnimationType = [TransitionAnimationType.Number];
+export type DarknessOptions = {
+    /** Darkness (0–1) the image starts from. */
+    from: number;
+    /** Darkness (0–1) the image ends at. */
+    to: number;
+    /** Duration in milliseconds. */
+    duration: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * Darken the original image and fade in the target image at the same time.
+ * Internal: drives `image.darken(x, duration)`.
+ */
 export declare class Darkness extends ImageTransition<AnimationType> {
-    private prevDarkness;
-    private targetDarkness;
+    private from;
+    private to;
     private duration;
     private easing?;
-    /**
-     * Darken the original image and fade in the target image at the same time.
-     * @param darkness darkness of the image, between 0 and 1
-     * @param duration duration in milliseconds
-     * @param easing easing definition or existing easing name
-     */
-    constructor(prevDarkness: number, targetDarkness: number, duration: number, easing?: TransformDefinitions.EasingDefinition | undefined);
+    constructor(options: DarknessOptions);
     createTask(): TransitionTask<HTMLImageElement, AnimationType>;
     copy(): Darkness;
 }

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

@@ -2,15 +2,18 @@ import { TransitionAnimationType, TransitionTask } from "../../../../elements/tr
 import { TransformDefinitions } from "../../../../elements/transform/type";
 import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
 type AnimationType = [TransitionAnimationType.Number];
+export type DissolveOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * Fade out the original image and fade in the target image at the same time.
+ */
 export declare class Dissolve extends ImageTransition<AnimationType> {
     private duration;
     private easing?;
-    /**
-     * Fade out the original image and fade in the target image at the same time.
-     * @param duration duration in milliseconds
-     * @param easing easing definition or existing easing name
-     */
-    constructor(duration: number, easing?: TransformDefinitions.EasingDefinition | undefined);
+    constructor(options: DissolveOptions);
     createTask(): TransitionTask<HTMLImageElement, AnimationType>;
     copy(): Dissolve;
 }