narraleaf-react 0.15.0 → 0.16.1

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 {};

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

@@ -1,4 +1,5 @@
 import { Pausing } from "../../../nlcore/elements/character/pause";
+import { TextEvent } from "../../../nlcore/elements/character/textEvent";
 import { Sentence, type StaticWord } from "../../../nlcore/elements/character/sentence";
 import { Word } from "../../../nlcore/elements/character/word";
 import { GameState } from "../../../../game/nlcore/common/game";
@@ -47,7 +48,7 @@ export interface TextsPreviewProps extends Omit<React.HTMLAttributes<HTMLDivElem
     /**
      * Already-evaluated words, useful when previewing dynamic sentence content.
      */
-    words?: Word<Pausing | string>[];
+    words?: Word<Pausing | string | TextEvent>[];
     /**
      * Whether the preview should use the rolling type effect.
      * @default true
@@ -92,7 +93,7 @@ export interface TextsPreviewProps extends Omit<React.HTMLAttributes<HTMLDivElem
 export type EntryTextsProps = BaseTextsProps & {
     entry: NvlDialogEntry;
     gameState: GameState;
-    words: Word<Pausing | string>[];
+    words: Word<Pausing | string | TextEvent>[];
     useTypeEffect: boolean;
     isActive: boolean;
 };

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

@@ -1,4 +1,5 @@
 import { Pausing } from "../../../nlcore/elements/character/pause";
+import { TextEvent } from "../../../nlcore/elements/character/textEvent";
 import { Word } from "../../../nlcore/elements/character/word";
 import { GameState } from "../../../../game/nlcore/common/game";
 import { EventDispatcher, EventToken } from "../../../../util/data";
@@ -14,9 +15,16 @@ type DialogEvents = {
 type DialogStateConfig = {
     useTypeEffect: boolean;
     action: DialogAction;
-    evaluatedWords: Word<Pausing | string>[];
+    evaluatedWords: Word<Pausing | string | TextEvent>[];
     gameState: GameState;
     suppressInitialAnimation?: boolean;
+    /**
+     * Persistent per-reveal text-event fire guard. When supplied (NVL entries pass the set stored on
+     * their long-lived {@link NvlDialogEntry}), a re-mount of the same line reuses it and so replays
+     * neither the sound effects nor the stale expression. Left undefined for ADV, whose dialog state
+     * is already memoized per action and falls back to a per-run set.
+     */
+    firedTextEvents?: Set<TextEvent>;
 };
 export declare class DialogState {
     static Events: {

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

@@ -0,0 +1,33 @@
+import type { GameState } from "../../gameState";
+import type { TextEvent } from "../../../nlcore/elements/character/textEvent";
+import type { Word } from "../../../nlcore/elements/character/word";
+import type { Pausing } from "../../../nlcore/elements/character/pause";
+/**
+ * Apply a {@link TextEvent}'s effect directly to element state — no transition, no action history,
+ * no stack model. This is the "reveal semantics" seam: the typewriter calls it the moment it
+ * uncovers a token. Because the effect lands on ordinary element state (which IS serialized) and
+ * never enters the stack model, it adds no save burden and re-fires naturally when the owning
+ * `say` action is re-evaluated.
+ *
+ * Mirrors {@link ImageAction}'s non-transition branch for the repaint (layered image → `flush`,
+ * otherwise → `updateStyleSync`).
+ */
+export declare function dispatchTextEvent(event: TextEvent, state: GameState): void;
+/**
+ * Fire a {@link TextEvent} at most once for a given typewriter run. `fired` is the per-run guard
+ * (contract 5): a render re-entry that re-visits the same token is a no-op, but a fresh run —
+ * a replay of the same `say` — starts with an empty set and fires again (contract 4).
+ */
+export declare function fireTextEventOnce(event: TextEvent, fired: Set<TextEvent>, state: GameState): void;
+/**
+ * Land the final state of an instantly-revealed sentence: every {@link TextEvent} token in `words`
+ * fires once, in source order — the same "final state" a typewriter skip produces (contract 3).
+ *
+ * `fired` is the persistent per-reveal guard. Pass the SAME set across re-mounts of one dialog line
+ * (e.g. an NVL entry re-keyed on a phase/active change, or the whole container re-mounting) so the
+ * re-mount replays neither the sound effects nor the — now stale — expression writes. A genuinely
+ * fresh reveal (a new line, or a `say` re-evaluated on load) passes its own empty set and fires
+ * again, preserving replay safety (contract 4). Returns the tokens that actually fired this call
+ * (empty on a guarded re-mount), for tests.
+ */
+export declare function fireInstantRevealEvents(words: readonly Word<string | Pausing | TextEvent>[], fired: Set<TextEvent>, state: GameState): TextEvent[];

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

@@ -3,13 +3,14 @@ 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 React from "react";
 import type { HTMLMotionProps } from "motion/react";
 export interface SayElementProps {
     action: {
         sentence: Sentence | null;
         character: Character | null;
-        words: Word<Pausing | string>[] | null;
+        words: Word<Pausing | string | TextEvent>[] | null;
         id?: string;
     };
     /**
@@ -43,13 +44,13 @@ export interface DialogContext {
     action: {
         sentence: Sentence | null;
         character: Character | null;
-        words: Word<Pausing | string>[] | null;
+        words: Word<Pausing | string | TextEvent>[] | null;
     };
     state: DialogStateType;
 }
 export type DialogAction = {
     sentence: Sentence | null;
     character: Character | null;
-    words: Word<Pausing | string>[] | null;
+    words: Word<Pausing | string | TextEvent>[] | null;
     id?: string;
 };

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

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

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

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

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

@@ -10,6 +10,7 @@ import { Storable } from "../nlcore/elements/persistent/storable";
 import { Game } from "../nlcore/game";
 import { Clickable, MenuElement, TextElement } from "./gameState.type";
 import { Sentence } from "../nlcore/elements/character/sentence";
+import type { TextEvent } from "../nlcore/elements/character/textEvent";
 import { type SceneSnapshot } from "../nlcore/action/actions/sceneAction";
 import { Logger } from "../../util/logger";
 import { Story } from "../nlcore/elements/story";
@@ -21,6 +22,7 @@ import { GameStateGuard } from "./guard";
 import { LiveGameEventToken } from "../nlcore/types";
 import * as htmlToImage from "html-to-image";
 import { Video, VideoStateRaw } from "../nlcore/elements/video";
+import { Vfx, VfxStateRaw } from "../nlcore/elements/vfx";
 import { Timelines } from "./Tasks";
 import { Notification, NotificationManager } from "./lib/notification";
 import { ActionHistoryManager } from "../../game/nlcore/action/actionHistory";
@@ -35,6 +37,13 @@ export type NvlDialogEntry = {
     character: Character | null;
     sentence: Sentence;
     text: string;
+    /**
+     * Runtime-only, per-line text-event fire guard. Lives on the long-lived entry (not the React
+     * dialog state, which is re-created on every re-mount) so the tokens a line reveals fire once and
+     * a re-mount replays nothing. Absent from {@link NvlDialogEntryData}, so a load starts a fresh
+     * reveal that fires again (replay safety). See {@link fireInstantRevealEvents}.
+     */
+    firedTextEvents?: Set<TextEvent>;
 };
 export type NvlDialogPhase = "idle" | "typing" | "awaitAdvance";
 /**
@@ -71,6 +80,7 @@ type ScheduleHandle = {
 export type PlayerState = {
     sounds: Sound[];
     videos: Video[];
+    vfx: Vfx[];
     srcManagers: SrcManager[];
     elements: PlayerStateElement[];
 };
@@ -113,6 +123,8 @@ export type PlayerStateData = {
     }[];
     audio: AudioManagerDataRaw;
     videos: [videoId: string, videoState: VideoStateRaw][];
+    /** Absent in saves created before 0.16.0; readers must tolerate the missing key. */
+    vfx?: [vfxId: string, vfxState: VfxStateRaw][];
     nvlState?: NvlStateData;
 };
 export type PresentationSnapshot = {
@@ -185,6 +197,10 @@ export declare class GameState {
     removeVideo(video: Video): this;
     isVideoAdded(video: Video): boolean;
     getVideos(): Video[];
+    addVfx(vfx: Vfx): this;
+    removeVfx(vfx: Vfx): this;
+    isVfxAdded(vfx: Vfx): boolean;
+    getVfx(): Vfx[];
     findElementByScene(scene: Scene): PlayerStateElement | null;
     findElementByDisplayable(displayable: LogicAction.DisplayableElements, layer?: Layer | null): PlayerStateElement | null;
     getLiveGame(): LiveGame;

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

@@ -5,11 +5,13 @@ import { ImageEvents } from "./elements/image/Image";
 import { Transform } from "../nlcore/elements/transform/transform";
 import { Transition } from "../nlcore/elements/transition/transition";
 import { Layer } from "../nlcore/elements/layer";
+import { Camera } from "../nlcore/elements/camera";
 import { Text } from "../nlcore/elements/displayable/text";
 import { Displayable } from "../nlcore/elements/displayable/displayable";
 import { Scene } from "../nlcore/elements/scene";
 import { Sound } from "../nlcore/elements/sound";
 import { Video } from "../nlcore/elements/video";
+import { Vfx, VfxFadeOptions } from "../nlcore/elements/vfx";
 import { Timeline } from "./Tasks";
 export * from "./elements/type";
 export type Chosen = Choice & {
@@ -20,7 +22,9 @@ export declare enum ExposedStateType {
     text = "narraleaf:text",
     layer = "narraleaf:layer",
     scene = "narraleaf:scene",
-    video = "narraleaf:video"
+    video = "narraleaf:video",
+    vfx = "narraleaf:vfx",
+    camera = "narraleaf:camera"
 }
 export type ExposedState = {
     [ExposedStateType.image]: {
@@ -46,6 +50,12 @@ export type ExposedState = {
         applyTransition: (transition: Transition<any>, onResolve: () => void) => Timeline;
         updateStyleSync: () => void;
     };
+    [ExposedStateType.camera]: {
+        initDisplayable: (onResolve: () => void) => Timeline;
+        applyTransform: (transform: Transform, onResolve: () => void) => Timeline;
+        applyTransition: (transition: Transition<any>, onResolve: () => void) => Timeline;
+        updateStyleSync: () => void;
+    };
     [ExposedStateType.scene]: {
         setBackgroundMusic: (music: Sound | null, fade: number) => Promise<void>;
     };
@@ -58,12 +68,21 @@ export type ExposedState = {
         stop: () => void;
         seek: (time: number) => void;
     };
+    [ExposedStateType.vfx]: {
+        show: (options?: VfxFadeOptions) => Promise<void>;
+        hide: (options?: VfxFadeOptions) => Promise<void>;
+        pause: () => void;
+        resume: () => void;
+        setRate: (rate: number) => void;
+    };
 };
 export type ExposedKeys = {
     [ExposedStateType.image]: Image | Displayable<any, any>;
     [ExposedStateType.text]: Text | Displayable<any, any>;
     [ExposedStateType.layer]: Layer | Displayable<any, any>;
+    [ExposedStateType.camera]: Camera | Displayable<any, any>;
     [ExposedStateType.scene]: Scene;
     [ExposedStateType.video]: Video;
+    [ExposedStateType.vfx]: Vfx;
 };
 export type { INotificationsProps } from "./elements/notification/type";