narraleaf-react 0.14.0 → 0.16.0

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

@@ -3,6 +3,13 @@ import { TransformDefinitions } from "../../../../elements/transform/type";
 import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
 import { GameState } from "../../../../../player/gameState";
 type AnimationType = [TransitionAnimationType.Number, TransitionAnimationType.Number, TransitionAnimationType.Number];
+export type FadeInOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /** Pixel offset the target travels in from, as `[x, y]`. @default [0, 0] */
+    offset?: [xOffset: number, yOffset: number];
+    easing?: TransformDefinitions.EasingDefinition;
+};
 /**
  * A fade in, optionally travelling from a pixel offset to rest.
  *
@@ -16,15 +23,9 @@ type AnimationType = [TransitionAnimationType.Number, TransitionAnimationType.Nu
  */
 export declare class FadeIn extends ImageTransition<AnimationType> {
     private duration;
-    private startPos;
+    private offset;
     private easing?;
-    /**
-     * Fade in the target image with an optional position start position
-     * @param startPos start position offset
-     * @param duration duration in milliseconds
-     * @param easing easing definition or existing easing name
-     */
-    constructor(duration: number, startPos?: [xOffset: number, yOffset: number], easing?: TransformDefinitions.EasingDefinition | undefined);
+    constructor(options: FadeInOptions);
     createTask(gameState: GameState): TransitionTask<HTMLImageElement, AnimationType>;
     copy(): FadeIn;
 }

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

@@ -0,0 +1,162 @@
+import { CSSProps } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { BlindsOrientation } from "../../../../elements/transition/transitions/image/transitionMaskUtils";
+/**
+ * A parametric coverage mask: the geometry vocabulary shared by the two
+ * mask-driven transition engines — {@link Reveal} (direct A→B) and
+ * {@link ThroughColor} (cover with a colour, swap, uncover). Built through the
+ * static factories on {@link Mask} and passed to an engine's `pattern` option.
+ *
+ * Invariants every pattern upholds:
+ * - `mask(0)` is fully transparent and `mask(1)` fully opaque, feather included —
+ *   the soft band is swept completely off both ends of the run.
+ * - The opaque fraction grows monotonically with `t`.
+ * - `mask(t, true)` is the complementary orientation of the same geometry at the
+ *   same coverage: a wipe grows from the opposite side, an iris closes from the
+ *   rim instead of growing from the centre, a clock hand sweeps the other way.
+ *   This is what lets {@link ThroughColor} continue a pattern through the hold
+ *   instead of backing it out.
+ */
+export type MaskPattern = {
+    /**
+     * The CSS mask image whose opaque region covers fraction `t` (0–1) of the
+     * frame. May be a comma-separated multi-layer image list.
+     */
+    mask(t: number, inverted?: boolean): string;
+    /** `mask-size` for tiled patterns. @default "100% 100%" */
+    size?: string;
+    /** `mask-repeat` for tiled patterns. @default "no-repeat" */
+    repeat?: string;
+};
+export type WipePatternOptions = {
+    /**
+     * Direction the covering edge travels toward — a keyword, or any CSS
+     * gradient angle in degrees (`0` = up, `90` = right). @default "left"
+     */
+    direction?: TransformDefinitions.WipeDirection | number;
+    /** Width of the soft edge band, in percent. Use `0` for a hard edge. @default 12 */
+    feather?: number;
+};
+export type BarnDoorPatternOptions = {
+    /** Travel axis of the doors, or any CSS gradient angle in degrees. @default "horizontal" */
+    axis?: "horizontal" | "vertical" | number;
+    /** Width of the soft edge band, in percent. @default 12 */
+    feather?: number;
+};
+export type IrisPatternOptions = {
+    /** Centre of the iris, as a CSS position. @default "50% 50%" */
+    center?: string;
+    /** Width of the soft edge band, in percent. Use `0` for a hard edge. @default 12 */
+    feather?: number;
+    /** Ending shape of the iris. @default "circle" */
+    shape?: "circle" | "ellipse";
+};
+export type ClockPatternOptions = {
+    /** Centre of the sweep, as a CSS position. @default "50% 50%" */
+    center?: string;
+    /** Angle the sweep starts from, in degrees (`0` = up). @default 0 */
+    from?: number;
+    /** Width of the soft leading edge, in degrees. @default 24 */
+    feather?: number;
+    /** Sweep direction of the hand. @default "clockwise" */
+    direction?: "clockwise" | "counterclockwise";
+};
+export type FanPatternOptions = {
+    /** Number of blades sweeping in parallel. @default 4 */
+    blades?: number;
+    /** Centre of the sweep, as a CSS position. @default "50% 50%" */
+    center?: string;
+    /** Angle the sweep starts from, in degrees (`0` = up). @default 0 */
+    from?: number;
+    /** Width of each blade's soft leading edge, in degrees. @default 10 */
+    feather?: number;
+};
+export type BlindsPatternOptions = {
+    /** Slat orientation, or any CSS gradient angle in degrees. @default "horizontal" */
+    orientation?: BlindsOrientation | number;
+    /** Number of slats. @default 8 */
+    slats?: number;
+    /** Width of each slat's soft edge, in percent of the frame. @default 0 (hard slats) */
+    feather?: number;
+};
+export type DotsPatternOptions = {
+    /** Number of tile rows. @default 6 */
+    rows?: number;
+    /** Number of tile columns. @default 10 */
+    cols?: number;
+    /** Width of each dot's soft rim, in percent of its tile. @default 20 */
+    feather?: number;
+    /**
+     * Phase offset (0–1) of a second dot grid anchored on the tile corners,
+     * giving a staggered, checker-like fill instead of a uniform one.
+     * @default 0
+     */
+    stagger?: number;
+};
+/**
+ * The transition-animation vocabulary: static factories building the
+ * {@link MaskPattern} geometries that the transition engines animate.
+ *
+ * Engines are instantiated, patterns are not — a transition reads as
+ * "engine(animation)":
+ * ```ts
+ * new Reveal({duration: 1200, pattern: Mask.clock()})
+ * new ThroughColor({duration: 1800, pattern: Mask.clock(), uncover: "continue"})
+ * ```
+ * {@link Mask.invert} flips a pattern's orientation, and a hand-written
+ * `MaskPattern` object works anywhere a built-in one does.
+ */
+export declare class Mask {
+    private constructor();
+    /** A feathered directional wipe, travelling toward any keyword or angle. */
+    static wipe(options?: WipePatternOptions): MaskPattern;
+    /**
+     * Barn doors: two feathered edges closing from opposite edges toward the
+     * centre. Inverted, a bar grows outward from the centre line instead.
+     */
+    static barnDoor(options?: BarnDoorPatternOptions): MaskPattern;
+    /**
+     * A feathered iris growing from the centre out. Inverted, it covers from
+     * the rim inward — the classic "iris to black" closes with
+     * `new ThroughColor({pattern: Mask.iris(), inverted: true})`.
+     */
+    static iris(options?: IrisPatternOptions): MaskPattern;
+    /**
+     * A clock sweep: one feathered radial edge travelling a full turn around
+     * the centre. The trailing edge at the start angle is hard by nature, as
+     * in a classic clock wipe; only the leading edge is feathered.
+     */
+    static clock(options?: ClockPatternOptions): MaskPattern;
+    /**
+     * A windmill of `blades` clock sweeps running in parallel, each covering
+     * its own sector. The feather compresses over the last few degrees of each
+     * sector so the blades can meet cleanly.
+     */
+    static fan(options?: FanPatternOptions): MaskPattern;
+    /**
+     * Venetian slats widening until they cover the frame. Hard-edged by
+     * default; raise `feather` for soft slats, or pass an angle for slanted
+     * ones.
+     */
+    static blinds(options?: BlindsPatternOptions): MaskPattern;
+    /**
+     * A tiled polka-dot fill: a dot grows inside every cell of a `cols`×`rows`
+     * grid until the cells flood together. With `stagger`, a second grid
+     * anchored on the cell corners runs behind the first for a denser,
+     * checker-like fill. (The staggered variant's inverted form is an
+     * approximation: the layers union, so mid-run coverage errs dark.)
+     */
+    static dots(options?: DotsPatternOptions): MaskPattern;
+    /**
+     * Swap a pattern's orientations: the inverted geometry becomes the natural
+     * one and vice versa (e.g. an iris that reveals rim-in instead of
+     * centre-out).
+     */
+    static invert(pattern: MaskPattern): MaskPattern;
+    /**
+     * The full mask style block for a pattern at coverage `t` — the pattern's
+     * image plus its tiling, mirrored to the `-webkit-` prefixes. For authors
+     * of custom transitions.
+     */
+    static toStyle(pattern: MaskPattern, t: number, inverted?: boolean): CSSProps;
+}

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

@@ -0,0 +1,33 @@
+import { TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
+import { MaskPattern } from "../../../../elements/transition/transitions/image/mask";
+type AnimationType = [TransitionAnimationType.Number];
+export type RevealOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /** The coverage geometry the target is revealed through. See {@link Mask}. */
+    pattern: MaskPattern;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * The direct-cut engine: the target image is revealed over the previous one
+ * through any {@link MaskPattern}, with no colour hold in between — the
+ * "A→B" counterpart of {@link ThroughColor}.
+ *
+ * The geometry lives entirely in the pattern, so the same {@link Mask} factory
+ * moves a scene change between the two families with a one-word edit:
+ * ```ts
+ * new Reveal({duration: 1200, pattern: Mask.clock()})
+ * new ThroughColor({duration: 1800, pattern: Mask.clock()})
+ * ```
+ */
+export declare class Reveal extends ImageTransition<AnimationType> {
+    private duration;
+    private pattern;
+    private easing?;
+    constructor(options: RevealOptions);
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    copy(): Reveal;
+}
+export {};

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

@@ -1,36 +1,40 @@
 import { TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
 import { TransformDefinitions } from "../../../../elements/transform/type";
 import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
-import { BlindsOrientation } from "../../../../elements/transition/transitions/image/transitionMaskUtils";
+import { MaskPattern } from "../../../../elements/transition/transitions/image/mask";
 type AnimationType = [TransitionAnimationType.Number];
-type ThroughColorBaseOptions = {
+/**
+ * How the colour uncovers after the hold:
+ * - `"retreat"` — the cover pattern backs out the way it came (default).
+ * - `"continue"` — the edge keeps travelling in the same direction, so the
+ *   pattern passes *through* the frame (a wipe exits out the far side, an iris
+ *   that closed rim-in reopens centre-out, a clock hand completes a second lap).
+ * - a {@link MaskPattern} — the colour uncovers through an unrelated geometry
+ *   of its own (cover with a clock, uncover with a wipe, ...).
+ */
+export type ThroughColorUncover = "retreat" | "continue" | MaskPattern;
+export type ThroughColorOptions = {
     /** Duration in milliseconds. */
     duration: number;
     /** Hold colour. @default "#000000" */
     color?: string;
     /** Fraction (0–1) of the duration spent fully covered by the colour. @default 0.3 */
     hold?: number;
+    /**
+     * The coverage geometry the colour covers the frame through. See
+     * {@link Mask}. Omit for a plain fade through the colour.
+     */
+    pattern?: MaskPattern;
+    /**
+     * Cover through the pattern's inverted orientation instead — e.g.
+     * `Mask.iris()` covers centre-out by default, and rim-in (the classic
+     * "iris to black") with `inverted: true`. @default false
+     */
+    inverted?: boolean;
+    /** How the colour uncovers after the hold. Ignored without a `pattern`. @default "retreat" */
+    uncover?: ThroughColorUncover;
     easing?: TransformDefinitions.EasingDefinition;
 };
-export type ThroughColorFadeOptions = ThroughColorBaseOptions;
-export type ThroughColorWipeOptions = ThroughColorBaseOptions & {
-    /** Direction the feathered edge travels toward. @default "left" */
-    direction?: TransformDefinitions.WipeDirection;
-    /** Width of the soft edge band, in percent. @default 12 */
-    feather?: number;
-};
-export type ThroughColorBlindsOptions = ThroughColorBaseOptions & {
-    /** Slat orientation. @default "horizontal" */
-    orientation?: BlindsOrientation;
-    /** Number of slats. @default 8 */
-    slats?: number;
-};
-export type ThroughColorIrisOptions = ThroughColorBaseOptions & {
-    /** Centre of the iris, as a CSS position. @default "50% 50%" */
-    center?: string;
-    /** Width of the soft edge band, in percent. @default 12 */
-    feather?: number;
-};
 /**
  * The "through colour" engine. A colour overlay covers the frame using the
  * chosen pattern, holds a solid-colour frame, then uncovers to reveal the
@@ -38,27 +42,21 @@ export type ThroughColorIrisOptions = ThroughColorBaseOptions & {
  * previous/target images simply swap opacity at the midpoint, unseen behind the
  * fully-covered frame.
  *
- * Created through its static factories (mirroring {@link MaskTransition}):
- * - {@link ThroughColor.fade}   — the overlay fades in/out (fade-to-black/white; `hold: 0` = flash).
- * - {@link ThroughColor.wipe}   — a feathered directional edge (soft wipe through the colour).
- * - {@link ThroughColor.blinds} — venetian slats (blinds through the colour).
- * - {@link ThroughColor.iris}   — a circle closing from the rim in (iris to the colour).
+ * The geometry lives entirely in the `pattern` option (see {@link Mask});
+ * without one, the colour simply fades in and out (fade-to-black/white, or a
+ * flash with `hold: 0`). {@link Reveal} is the direct-cut counterpart that
+ * takes the same patterns. The `uncover` option picks how the second half
+ * plays: see {@link ThroughColorUncover}.
  */
 export declare class ThroughColor extends ImageTransition<AnimationType> {
     private duration;
     private color;
     private hold;
-    private coverMask;
+    private pattern;
+    private inverted;
+    private uncover;
     private easing?;
-    private constructor();
-    /** Fade the frame to a solid colour, hold, then fade to the target. */
-    static fade(options: ThroughColorFadeOptions): ThroughColor;
-    /** Cover the frame with a feathered directional edge, hold, then uncover. */
-    static wipe(options: ThroughColorWipeOptions): ThroughColor;
-    /** Cover the frame with venetian slats, hold, then uncover. */
-    static blinds(options: ThroughColorBlindsOptions): ThroughColor;
-    /** Close a circle over the frame from the rim in, hold, then open it. */
-    static iris(options: ThroughColorIrisOptions): ThroughColor;
+    constructor(options: ThroughColorOptions);
     /** Style for the colour overlay at a given coverage (0 = clear, 1 = fully covered). */
     private coverStyle;
     createTask(): TransitionTask<HTMLImageElement, AnimationType>;

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

@@ -1,30 +1,19 @@
 import { CSSProps } from "../../../../elements/transition/type";
 import { TransformDefinitions } from "../../../../elements/transform/type";
 /**
- * Shared, side-effect-free helpers for the mask/gradient driven image
- * transitions ({@link SoftWipe}, {@link Blinds}, {@link SoftIris},
- * {@link ThroughColor}). Kept internal — not exported from the package barrel.
+ * Shared, side-effect-free helpers for the mask-driven transition machinery
+ * ({@link Mask}, {@link ThroughColor}). Kept internal — not exported from the
+ * package barrel.
  */
-/** Orientation of {@link Blinds} slats / {@link ThroughColor} blinds pattern. */
+/** Orientation of the {@link Mask.blinds} slats. */
 export type BlindsOrientation = "horizontal" | "vertical";
 /** Clamp a value into the `[0, 1]` range. */
 export declare function clamp01(value: number): number;
 /** The `mask-image` triplet, mirrored to the `-webkit-` prefix for WebKit. */
-export declare function maskStyle(image: string): CSSProps;
+export declare function maskStyle(image: string, size?: string, repeat?: string): CSSProps;
 /** Full-bleed positioning for a synthetic colour overlay layer. */
 export declare function overlayBase(color: string): CSSProps;
 /** CSS gradient direction keyword for a wipe travelling toward `direction`. */
 export declare function wipeGradientDir(direction: TransformDefinitions.WipeDirection): string;
 /** Gradient axis for blinds slats of a given orientation. */
 export declare function blindsAxis(orientation: BlindsOrientation): string;
-/**
- * Feathered linear wipe mask. `progress` 0 → fully hidden, 1 → fully covered;
- * the opaque edge sweeps with a soft transition band of width `feather` (%).
- */
-export declare function linearWipeMask(direction: TransformDefinitions.WipeDirection, feather: number, progress: number): string;
-/** Venetian slats mask. `progress` 0 → open (hidden), 1 → shut (covered). */
-export declare function blindsCoverMask(orientation: BlindsOrientation, slats: number, progress: number): string;
-/** Iris that *covers* from the rim inward. `progress` 0 → hidden, 1 → covered. */
-export declare function irisCoverMask(center: string, feather: number, progress: number): string;
-/** Iris that *reveals* from the centre out. `progress` 0 → hidden, 1 → shown. */
-export declare function irisRevealMask(center: string, feather: number, progress: number): string;

package/dist/game/nlcore/elements/transition/transitions/text/fontSize.d.ts

@@ -2,11 +2,18 @@ import { TextTransition } from "../../../../elements/transition/transitions/text
 import { TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
 import { TransformDefinitions } from "../../../../elements/transform/type";
 type AnimationType = [TransitionAnimationType.Number];
+export type FontSizeOptions = {
+    /** Font size (px) the text transitions to. */
+    fontSize: number;
+    /** Duration in milliseconds. */
+    duration: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
 export declare class FontSize extends TextTransition<AnimationType> {
-    private textSize;
+    private fontSize;
     private duration;
     private easing?;
-    constructor(textSize: number, duration: number, easing?: TransformDefinitions.EasingDefinition | undefined);
+    constructor(options: FontSizeOptions);
     createTask(): TransitionTask<HTMLSpanElement, AnimationType>;
     copy(): FontSize;
 }

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

@@ -0,0 +1,85 @@
+import { Actionable } from "../action/actionable";
+import type { TransformDefinitions } from "../elements/transform/type";
+/**
+ * How the overlay video is composited onto the stage.
+ *
+ * - `"normal"` — plain overlay for true-alpha material (VP9 `yuva420p` alpha WebM);
+ *   colors stay faithful on any background.
+ * - `"screen"` — additive blend for glow material rendered on a black background
+ *   (light dust, rain, snow, magic sparks); tiny files, hardware decodable, but dark
+ *   pixels get washed out on bright backgrounds.
+ * - `"multiply"` — for shadow material rendered on a white background.
+ */
+export type VfxBlendMode = "normal" | "screen" | "multiply" | "lighten" | "color-dodge" | "overlay";
+export type VfxConfig = {
+    src: string;
+    blendMode: VfxBlendMode;
+    loop: boolean;
+    muted: boolean;
+    opacity: number;
+    playbackRate: number;
+    fit: "cover" | "contain" | "fill";
+    zIndex: number;
+};
+export type VfxFadeOptions = {
+    duration?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * A full-screen looping video overlay for particle and ambience effects
+ * (falling petals, light dust, rain, snow, fog, light flares).
+ *
+ * The effect is a pre-rendered video that plays above the scenes and videos of the
+ * stage; camera transforms apply to it like any other stage content.
+ */
+export declare class Vfx extends Actionable<VfxStateRaw> {
+    /**
+     * Create a video overlay effect.
+     * @param config - Source configuration; `src` is required.
+     * @example
+     * ```ts
+     * // true-alpha material: faithful colors on any background
+     * const petals = new Vfx({src: "/fx/petals-alpha.webm"});
+     *
+     * // black-background glow material + screen blending: tiny files
+     * const dust = new Vfx({src: "/fx/dust-black.webm", blendMode: "screen", opacity: 0.9});
+     * ```
+     */
+    constructor(config: Partial<VfxConfig> & {
+        src: string;
+    });
+    /**
+     * Add the overlay to the stage, fade it in, and start looping playback.
+     *
+     * The action waits for the fade-in to finish. Calling it while the overlay is
+     * already shown is idempotent (the fade-in is re-applied).
+     * @chainable
+     */
+    show(options?: VfxFadeOptions): ChainedVfx;
+    /**
+     * Fade the overlay out, then stop playback and remove it from the stage.
+     *
+     * The action waits for the fade-out to finish. Calling it while the overlay is
+     * not shown is a no-op (a weak warning is logged).
+     * @chainable
+     */
+    hide(options?: VfxFadeOptions): ChainedVfx;
+    /**
+     * Freeze the overlay on its current frame.
+     * @chainable
+     */
+    pause(): ChainedVfx;
+    /**
+     * Continue playback from the current frame.
+     * @chainable
+     */
+    resume(): ChainedVfx;
+    /**
+     * Adjust the playback speed (e.g. `0.5` for slow drifting).
+     *
+     * Runtime rate changes are not persisted; after loading a saved game the rate
+     * returns to `config.playbackRate`.
+     * @chainable
+     */
+    setPlaybackRate(rate: number): ChainedVfx;
+}

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

@@ -32,4 +32,30 @@ export declare class Video extends Actionable<VideoStateRaw> {
      * ```
      */
     play(): ChainedVideo;
+    /**
+     * Pause the video, keeping its current position.
+     * @chainable
+     */
+    pause(): ChainedVideo;
+    /**
+     * Resume playback from the current position.
+     *
+     * Unlike {@link play}, this does not wait for the video to finish.
+     * @chainable
+     */
+    resume(): ChainedVideo;
+    /**
+     * Stop the video: pause it and end any pending {@link play} so the story continues.
+     * @chainable
+     */
+    stop(): ChainedVideo;
+    /**
+     * Seek to a specific time (in seconds).
+     * @chainable
+     * @example
+     * ```ts
+     * video.seek(3);
+     * ```
+     */
+    seek(time: number): ChainedVideo;
 }

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

@@ -8,7 +8,7 @@ import { LiveGameEventHandler, LiveGameEventToken } from "../types";
 import { EventDispatcher } from "../../../util/data";
 import { GameState } from "../../player/gameState";
 import { GameHistory } from "../action/gameHistory";
-import { StackModel } from "../action/stackModel";
+import { StackModel, StackSnapshot } from "../action/stackModel";
 export declare class LiveGame {
     static DefaultNamespaces: {
         game: {};
@@ -19,6 +19,7 @@ export declare class LiveGame {
     static EventTypes: {
         readonly "event:character.prompt": "event:character.prompt";
         readonly "event:menu.choose": "event:menu.choose";
+        readonly "event:action.current": "event:action.current";
     };
     game: Game;
     events: EventDispatcher<LiveGameEvent>;
@@ -104,16 +105,29 @@ export declare class LiveGame {
      * ```
      *
      * @param options.until - `"menu"` (default) stops at the next menu; `"end"` runs until the
-     *                         story finishes.
+     *                         story finishes; `{ actionId }` runs until that action surfaces as
+     *                         the next thing to execute and stops **just before** running it
+     *                         (so the play head is positioned at that line). A menu that blocks
+     *                         the path, the stack draining, or the step cap all stop early — the
+     *                         result then reports `reachedTarget: false` so the caller can tell an
+     *                         unreachable / already-passed id from a successful jump.
      * @param options.maxSteps - safety bound on the number of advance steps (defaults to the
      *                           `maxStackModelLoop` config).
-     * @returns why it stopped: `"menu"`, `"end"` (the stack drained), or `"maxSteps"`.
+     * @returns why it stopped: `"action"` (reached `until.actionId`), `"menu"`, `"end"` (the stack
+     *          drained), or `"maxSteps"`. When an `actionId` target was requested, `reachedTarget`
+     *          is also set (`true` only for reason `"action"`).
+     *
+     * Note: only the root execution stack is scanned for the target — an id buried inside an
+     * in-flight parallel (`Control.all`/`any`) or async branch is not a stop point.
      */
     fastForward(options?: {
-        until?: "menu" | "end";
+        until?: "menu" | "end" | {
+            actionId: string;
+        };
         maxSteps?: number;
     }): Promise<{
-        reason: "menu" | "end" | "maxSteps";
+        reason: "menu" | "end" | "maxSteps" | "action";
+        reachedTarget?: boolean;
     }>;
     private assertScreenshot;
     /**
@@ -148,6 +162,31 @@ export declare class LiveGame {
      * When a player chooses a menu
      */
     onMenuChoose(fc: LiveGameEventHandler<LiveGameEvent["event:menu.choose"]>): LiveGameEventToken;
+    /**
+     * **Experimental.** Subscribe to the current-action-id stream: fires each time an action
+     * begins executing, carrying its id and type. Intended for an external play head (e.g. the
+     * Studio timeline) to follow along. Fires for branch/async actions too — filter by your own
+     * id set if you only track top-level lines.
+     *
+     * @returns a token; call `token.cancel()` to unsubscribe.
+     */
+    onCurrentActionChange(fc: LiveGameEventHandler<LiveGameEvent["event:action.current"]>): LiveGameEventToken;
+    /**
+     * **Experimental.** The id of the most recently executed action, or null before the first
+     * action runs. A pull-based companion to {@link onCurrentActionChange}.
+     */
+    getCurrentActionId(): string | null;
+    /**
+     * **Experimental, read-only.** A top-first snapshot of the current execution stacks for a
+     * call-stack / debug view: the root stack plus any in-flight async stacks (`Control.doAsync`
+     * / `Control.allAsync`). The shape is a convenience projection, not a stability contract — do
+     * not serialize it (use {@link serialize} for saves). Returns empty frames before the game
+     * starts.
+     */
+    getStackSnapshot(): {
+        root: StackSnapshot;
+        async: StackSnapshot[];
+    };
     /**
      * Start a new game
      */

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

@@ -3,18 +3,19 @@ import type { GameState } from "../../gameState";
 import { Sentence } from "../../../nlcore/elements/character/sentence";
 import { Word } from "../../../nlcore/elements/character/word";
 import { Pausing } from "../../../nlcore/elements/character/pause";
+import { TextEvent } from "../../../nlcore/elements/character/textEvent";
 import { Chosen } from "../../type";
 export interface MenuElementProps {
     prompt: Sentence | null;
     choices: Choice[];
     afterChoose: (choice: Chosen) => void;
     state: GameState;
-    words: Word<Pausing | string>[] | null;
+    words: Word<Pausing | string | TextEvent>[] | null;
     renderPrompt?: boolean;
 }
 export interface IUserMenuProps {
     items: number[];
 }
 export type ChoiceEvaluated = Choice & {
-    words: Word<Pausing | string>[];
+    words: Word<Pausing | string | TextEvent>[];
 };

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

@@ -2,13 +2,14 @@ import type { GameState, NvlDialogEntry, NvlState } from "../../gameState";
 import type { TransformDefinitions } from "../../../nlcore/elements/transform/type";
 import type { Word } from "../../../nlcore/elements/character/word";
 import type { Pausing } from "../../../nlcore/elements/character/pause";
+import type { TextEvent } from "../../../nlcore/elements/character/textEvent";
 import React from "react";
 export type NvlDialogProxy = {
     entry: NvlDialogEntry;
     index: number;
     isActive: boolean;
     gameState: GameState;
-    words: Word<Pausing | string>[];
+    words: Word<Pausing | string | TextEvent>[];
     useTypeEffect: boolean;
 };
 export interface INvlContainerProps {

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

@@ -3,10 +3,11 @@ import { GameState } from "../../gameState";
 import type { NvlDialogEntry } from "../../gameState";
 import type { Word } from "../../../nlcore/elements/character/word";
 import type { Pausing } from "../../../nlcore/elements/character/pause";
+import type { TextEvent } from "../../../nlcore/elements/character/textEvent";
 type UseNvlDialogStateParams = {
     entry: NvlDialogEntry;
     gameState: GameState;
-    words: Word<Pausing | string>[];
+    words: Word<Pausing | string | TextEvent>[];
     isActive: boolean;
     useTypeEffect: boolean;
 };

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

@@ -0,0 +1 @@
+export {};