narraleaf-react 0.26.0 → 0.27.0

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

@@ -52,7 +52,7 @@ export type NvlBlockOptions = {
     hideTransition?: Partial<TransformDefinitions.CommonTransformProps>;
 };
 export type SceneActionContentType = {
-    [K in typeof SceneActionTypes[keyof typeof SceneActionTypes]]: K extends typeof SceneActionTypes["action"] ? Scene : K extends typeof SceneActionTypes["init"] ? [Scene] : K extends typeof SceneActionTypes["exit"] ? [] : K extends typeof SceneActionTypes["jumpTo"] ? [Scene] : K extends typeof SceneActionTypes["setBackgroundMusic"] ? [Sound | null, number?] : K extends typeof SceneActionTypes["preUnmount"] ? [] : K extends typeof SceneActionTypes["transitionToScene"] ? [ImageTransition, Scene | undefined, ImageSrc | Color | undefined] : K extends typeof SceneActionTypes["nvlBlock"] ? [LogicAction.Actions[], NvlBlockOptions] : K extends typeof SceneActionTypes["nvlShow"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlHide"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlEnd"] ? [NvlBlockOptions?] : any;
+    [K in typeof SceneActionTypes[keyof typeof SceneActionTypes]]: K extends typeof SceneActionTypes["action"] ? Scene : K extends typeof SceneActionTypes["init"] ? [Scene] : K extends typeof SceneActionTypes["exit"] ? [] : K extends typeof SceneActionTypes["jumpTo"] ? [Scene] : K extends typeof SceneActionTypes["setBackgroundMusic"] ? [Sound | null, number?] : K extends typeof SceneActionTypes["preUnmount"] ? [] : K extends typeof SceneActionTypes["transitionToScene"] ? [Transition, Scene] : K extends typeof SceneActionTypes["nvlBlock"] ? [LogicAction.Actions[], NvlBlockOptions] : K extends typeof SceneActionTypes["nvlShow"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlHide"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlEnd"] ? [NvlBlockOptions?] : any;
 };
 export declare const StoryActionTypes: {
     readonly action: "story:action";

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

@@ -7,7 +7,7 @@ import { ContentNode } from "../../action/tree/actionTree";
 import { LogicAction } from "../../action/logicAction";
 import { TypedAction } from "../../action/actions";
 import { Story } from "../../elements/story";
-import { ImageTransition } from "../../elements/transition/transitions/image/imageTransition";
+import type { Transition } from "../../elements/transition/transition";
 import { ActionSearchOptions } from "../../types";
 import { ExposedState, ExposedStateType } from "../../../player/type";
 import type { TransformDefinitions } from "../../elements/transform/type";
@@ -46,7 +46,14 @@ export declare class SceneAction<T extends typeof SceneActionTypes[keyof typeof
     static initBackgroundMusic(scene: Scene, exposed: ExposedState[ExposedStateType.scene]): Promise<void>;
     static createSceneSnapshot(scene: Scene, state: GameState): SceneSnapshot;
     static restoreSceneSnapshot(snapshot: SceneSnapshot, state: GameState): void;
-    applyTransition(gameState: GameState, transition: ImageTransition, injection: ActionExecutionInjection): Awaitable<CalledActionResult, CalledActionResult>;
+    /**
+     * Play `transition` across the whole stage while jumping from this scene to `target`.
+     *
+     * Both scenes are mounted at this point — `scene:init` added the incoming one and
+     * `scene:exit` has not yet removed this one — so the transition drives the two live scene
+     * subtrees rather than swapping one image's source underneath them.
+     */
+    applyStageTransition(gameState: GameState, transition: Transition, target: Scene, injection: ActionExecutionInjection): Awaitable<CalledActionResult, CalledActionResult>;
     exit(state: GameState): void;
     applyNvlVisibility(gameState: GameState, visible: boolean, options: Partial<TransformDefinitions.CommonTransformProps> | undefined, injection: ActionExecutionInjection): CalledActionResult | Awaitable<CalledActionResult, CalledActionResult>;
     executeAction(gameState: GameState, injection: ActionExecutionInjection): ExecutedActionResult;

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

@@ -29,3 +29,4 @@ export type { LayeredDefinition, LayerGroupDefinition, LayerResolver, LayerSlot,
 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";
+export type { WordConfig, WordRenderProps, WordRenderer, } from "../elements/character/word";

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

@@ -2,12 +2,63 @@ import { Color, Font } from "../../types";
 import { DynamicWord } from "../../elements/character/sentence";
 import { Pausing } from "../../elements/character/pause";
 import { TextEvent } from "../../elements/character/textEvent";
+import type React from "react";
+/**
+ * What a custom word renderer receives.
+ *
+ * A custom-rendered word is still an ordinary text word — it goes into the backlog, the read-text
+ * record and the voice pipeline as its plain text, and it is typed out character by character like
+ * any other. The renderer only decides what the revealed characters look like and what happens when
+ * they are interacted with.
+ */
+export type WordRenderProps<T = unknown> = {
+    /**
+     * The word's text as the engine has already laid it out — ruby, vertical writing mode and
+     * tate-chu-yoko are applied here. Render this rather than {@link WordRenderProps.text}, or those
+     * settings are silently dropped.
+     */
+    children: React.ReactNode;
+    /** The characters revealed so far. Equal to `fullText` once the typewriter has passed the word. */
+    text: string;
+    /** The whole word, revealed or not. */
+    fullText: string;
+    /** Whether every character of this word has been revealed. */
+    revealed: boolean;
+    /** Whether the whole line has finished revealing. */
+    done: boolean;
+    /**
+     * The resolved style chain for this word (engine defaults, then the dialog's text props, then
+     * the sentence, then the word). Already applied to the element wrapping the renderer; passed in
+     * so the renderer can measure against it or carry it into a portal.
+     */
+    style: Readonly<React.CSSProperties>;
+    /** The word's own config, as given to {@link Word}. */
+    config: Readonly<Partial<WordConfig>>;
+    /** The payload passed as `data` when the word was created. */
+    data: T;
+};
+/**
+ * A component to render a word with, or the id of one registered with `registerWordRenderer`.
+ *
+ * Pass a component in code; pass an id when the word comes from data (a story file, a plugin) and
+ * cannot carry a function. An id that resolves to nothing renders as plain text.
+ */
+export type WordRenderer<T = any> = string | React.ComponentType<WordRenderProps<T>>;
 export type WordConfig = {
     className: string;
     ruby: string;
     color: Color;
     pause: boolean;
     cps?: number;
+    /**
+     * Renders this word's revealed characters. See {@link Word.custom}.
+     */
+    render?: WordRenderer;
+    /**
+     * Arbitrary payload handed to {@link WordConfig.render} as `data`. Never merged or cloned — the
+     * renderer receives the very value given here.
+     */
+    data?: unknown;
 } & Font;
 export declare class Word<T extends string | DynamicWord | Pausing | TextEvent = string | DynamicWord | Pausing | TextEvent> {
     static isWord(obj: any): obj is Word;
@@ -31,6 +82,51 @@ export declare class Word<T extends string | DynamicWord | Pausing | TextEvent =
      * @param text - The text or word to italicize.
      */
     static italic(text: string | Word): Word;
+    /**
+     * Render a word with a component of your own — an inline glossary term that opens a definition
+     * popup, a name that links into an in-game encyclopedia, anything the dialogue box cannot say
+     * with color and weight alone.
+     *
+     * The word stays a text word in every other respect: it is typed out character by character, it
+     * reaches the backlog and the read-text record as its plain text, and it is never serialized —
+     * the renderer is re-attached when the `say` action is evaluated again, so a save carries no
+     * trace of it.
+     *
+     * The renderer sits *inside* the element the engine styles, so the style chain (engine defaults
+     * → the dialog's text props → the sentence → the word) already applies to it; anything the
+     * renderer sets wins, being last. `render` propagates to plain strings a dynamic word returns,
+     * the same way `className` does.
+     *
+     * While a custom word is still being typed, a click on it advances the line as a click anywhere
+     * else would. Once revealed, the word takes its own clicks — the line does not advance behind
+     * the renderer's back.
+     *
+     * @param text - The word's text, or an existing word to re-render.
+     * @param render - A component, or the id of one registered with `registerWordRenderer`.
+     * @param config - Optional styling, plus the `data` payload handed to the renderer.
+     * @example
+     * ```tsx
+     * function GlossaryTerm({children, revealed, data}: WordRenderProps<{entry: string}>) {
+     *     const [open, setOpen] = useState(false);
+     *     return (
+     *         <span className="underline decoration-dotted"
+     *               onClick={() => revealed && setOpen(v => !v)}>
+     *             {children}
+     *             {open && <span className="absolute">{lookUp(data.entry)}</span>}
+     *         </span>
+     *     );
+     * }
+     *
+     * character.say([
+     *     "今天的",
+     *     Word.custom("以太浓度", GlossaryTerm, {data: {entry: "aether"}}),
+     *     "高得反常。",
+     * ]);
+     * ```
+     */
+    static custom<T = unknown>(text: string | Word, render: WordRenderer<T>, config?: Partial<Omit<WordConfig, "render" | "data">> & {
+        data?: T;
+    }): Word;
     /**
      * Wrap raw data (string, dynamic function, or pause) into a `Word` for sentences.
      * @param text - The payload shown in dialogue, which may be static, dynamic, or a pause.

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

@@ -10,6 +10,7 @@ import { NVLToken } from "./nvl";
 import type { TransformDefinitions } from "../elements/transform/type";
 import type { ActionStatements } from "../elements/type";
 import type { Persistent } from "../elements/persistent";
+import { Transition } from "../elements/transition/transition";
 export interface ISceneUserConfig {
     /**
      * Background music
@@ -33,7 +34,15 @@ export interface ISceneUserConfig {
     layers: Layer[];
 }
 export type JumpConfig = {
-    transition: ImageTransition;
+    /**
+     * Played across the whole stage while the scenes swap: the outgoing scene drives the
+     * transition's outgoing half and the incoming scene its incoming half, so sprites, text and
+     * every other layer take part rather than only the background.
+     *
+     * The dialogue box is deliberately not part of it — it is rendered outside the stage and is
+     * expected to be gone by the time a scene ends.
+     */
+    transition: Transition;
 };
 type ChainableAction = Proxied<LogicAction.GameElement, Chained<LogicAction.Actions>> | LogicAction.Actions;
 type ChainedScene = Proxied<Scene, Chained<LogicAction.Actions>>;
@@ -65,6 +74,9 @@ export declare class Scene extends Constructable<LogicAction.Actions, Scene> {
      * Jump to another scene and discard the current one.
      *
      * After the jump the calling scene is unloaded and any actions that follow are ignored.
+     *
+     * A `transition` plays across the whole stage rather than across the background alone; see
+     * {@link JumpConfig.transition}.
      * @param scene - The destination scene instance.
      * @param config - Optional transition config (or transition object).
      * @chainable

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

@@ -9,9 +9,23 @@ export declare abstract class ImageTransition<T extends TransitionAnimationType[
     /**@package */
     private _currentSrc;
     /**@package */
+    private _detached;
+    /**@package */
     private _prevLayers;
     /**@package */
     private _targetLayers;
+    /**
+     * Detach the transition from any image source.
+     *
+     * A detached transition drives an element that owns its own content — the stage transition
+     * driver points the two halves at whole scene subtrees — so there is no src for the
+     * resolvers to carry, and `asPrev`/`asTarget` must contribute style only. Without this the
+     * src injection below throws, because "no src" is otherwise a genuine authoring error.
+     * @package
+     */
+    _setDetached(detached: boolean): this;
+    /**@package */
+    _isDetached(): boolean;
     /**@package */
     _setPrevLayers(layers: (string | null)[]): this;
     /**@package */

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

@@ -312,10 +312,11 @@ export type GameConfig = {
      */
     allowSkipBackgroundTransform: boolean;
     /**
-     * If true, when you press [GameConfig.player.skipKey], the game will skip the background transition
-     * @default false
+     * If true, when you press [GameConfig.player.skipKey], the game will skip the transition
+     * played between scenes by {@link Scene.jumpTo}
+     * @default true
      */
-    allowSkipBackgroundTransition: boolean;
+    allowSkipSceneTransition: boolean;
     /**
      * If true, when you press [GameConfig.player.skipKey], the game will skip the text transform
      * @default true

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

@@ -0,0 +1,52 @@
+import React from "react";
+/**
+ * A rectangle in the overlay's own coordinates — the dialog box drawn at its authored size, before
+ * the stage scales it to the window.
+ */
+export type DialogOverlayRect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+};
+export type DialogOverlay = {
+    /**
+     * Renders its children above the dialog, still inside the scaled stage, so a popup keeps the
+     * dialog's own scale and is not clipped by the text box it belongs to.
+     */
+    Portal: React.FC<{
+        children?: React.ReactNode;
+    }>;
+    /**
+     * Where an element sits in the overlay's coordinates. Feed the result straight to `left`/`top`
+     * on a child of {@link DialogOverlay.Portal}.
+     */
+    measure: (element: Element | null) => DialogOverlayRect | null;
+    /** The overlay element, or `null` outside a dialog. */
+    container: HTMLElement | null;
+};
+/**
+ * Somewhere to draw things that belong to a line but must not live inside it — the definition popup
+ * of an inline glossary word, a tooltip on a name.
+ *
+ * The overlay covers the dialog and sits above it, inside the same scaled stage, so a popup is
+ * drawn at the dialog's own scale and escapes the text box's clipping. It lets clicks through
+ * everywhere its children do not paint; give the popup itself `pointer-events: auto`.
+ *
+ * @example
+ * ```tsx
+ * const overlay = useDialogOverlay();
+ * const rect = overlay.measure(anchorRef.current);
+ *
+ * return rect && (
+ *     <overlay.Portal>
+ *         <div style={{position: "absolute", left: rect.left, top: rect.top, pointerEvents: "auto"}}>
+ *             …
+ *         </div>
+ *     </overlay.Portal>
+ * );
+ * ```
+ */
+export declare function useDialogOverlay(): DialogOverlay;

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

@@ -0,0 +1,29 @@
+import type { WordRenderProps } from "../../../nlcore/elements/character/word";
+import type React from "react";
+/**
+ * Register a component that words may name by id.
+ *
+ * Registering the same id again replaces the component; lines already on screen pick the new one up
+ * on their next render.
+ *
+ * @param id - The id words refer to, e.g. `"glossary"`.
+ * @param component - The component to render those words with.
+ * @returns A function that unregisters it again.
+ * @example
+ * ```tsx
+ * registerWordRenderer("glossary", GlossaryTerm);
+ * // a word compiled from story data can now ask for it by name
+ * new Word("以太浓度", {render: "glossary", data: {entry: "aether"}});
+ * ```
+ */
+export declare function registerWordRenderer<T = unknown>(id: string, component: React.ComponentType<WordRenderProps<T>>): () => void;
+/**
+ * Drop a registration made by {@link registerWordRenderer}.
+ * @param id - The id to forget.
+ */
+export declare function unregisterWordRenderer(id: string): void;
+/**
+ * The component registered under an id, or `null`.
+ * @param id - The id to look up.
+ */
+export declare function getWordRenderer(id: string): React.ComponentType<WordRenderProps<any>> | null;

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

@@ -0,0 +1,47 @@
+import type { Scene } from "../../../nlcore/elements/scene";
+import type { CSSProps } from "../../../nlcore/elements/transition/type";
+/**
+ * Which scene each half of a stage transition drives.
+ *
+ * A transition task's resolvers are already split by {@link Transition.asPrev} / {@link
+ * Transition.asTarget}; this is what those two roles mean at the stage level.
+ */
+export type StageTransitionRoles = {
+    /** The scene being left. Driven by the `asPrev` resolvers. */
+    from: Scene;
+    /** The scene being entered. Driven by the `asTarget` resolvers. */
+    to: Scene;
+};
+/**
+ * What a scene root paints when no transition owns it.
+ *
+ * This must name **every** property any transition writes to a scene half. A property left out
+ * is not neutral — it keeps whatever the last frame put there. That is survivable for the
+ * outgoing scene (it is unmounted moments later) but not for the incoming one, which lives on:
+ * a `Reveal` leaves a fully-opaque `mask-image` behind, and the scene would then carry that mask
+ * for the rest of its life. Cancellation is worse still — it stops mid-flight with no final
+ * frame, so a half-way value would stick forever on both halves.
+ *
+ * `stageSettledStyle.test.ts` pins this list against what the built-in transitions actually
+ * write, so a transition cannot start writing a property without this naming it.
+ */
+export declare function stageSettledStyle(): CSSProps;
+/**
+ * What the scene a transition moved away from paints once the transition is over: nothing.
+ *
+ * The transition finishing is not what removes the outgoing scene — `scene:exit` is a separate
+ * action, so the scene stays mounted for a moment afterwards, and during that moment it must not be
+ * on screen. Leaving that to the stacking order does not work: settling gives the incoming scene
+ * `z-index: auto` while the outgoing one still carries an explicit `0`, and those are the same
+ * stacking level, so document order decides — and the outgoing scene is the later node. It comes to
+ * the front, at whatever opacity its half of the transition left it at.
+ *
+ * A `Dissolve` hides that, because its outgoing half ends at zero opacity. A `Reveal` does not: its
+ * outgoing half is `{}`, never touched at all, because the effect is entirely the incoming scene
+ * being uncovered on top of it. So the scene the player just left reappears, at full opacity, in
+ * front — for as many frames as `scene:exit` takes to arrive.
+ *
+ * Hiding it is also what the per-element path has always done: `useDisplayable` discards the
+ * element that played the outgoing half the moment the transition completes.
+ */
+export declare function stageRetiredStyle(): CSSProps;

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

@@ -193,6 +193,7 @@ export declare class GameState {
     readonly gameHistory: GameHistoryManager;
     pageRouter: null;
     private stageClickBuffer;
+    private readonly advanceSuspensions;
     private readonly nvlAdvanceWaiters;
     private advDialogState;
     private _fastForwarding;
@@ -318,6 +319,24 @@ export declare class GameState {
     settleAdvDialog(dialogId: string): this;
     getAdvDialogState(): AdvDialogState | null;
     recordStageClick(): this;
+    /**
+     * Hold the line where it is: while at least one suspension is out, clicking the stage and
+     * pressing the advance or skip key do nothing.
+     *
+     * Anything that opens on top of a line and wants the player's next keystroke needs this — a
+     * definition popup on an inline word, a term the player is reading. Without it a popup opens and
+     * the very next space bar advances the line behind it, which is the one thing the popup exists
+     * to prevent.
+     *
+     * Suspensions nest: the line resumes once every one of them has been released.
+     *
+     * @returns A function that releases this suspension. Safe to call more than once.
+     */
+    suspendAdvance(): () => void;
+    /**
+     * Whether anything is currently holding the line — see {@link GameState.suspendAdvance}.
+     */
+    isAdvanceSuspended(): boolean;
     consumeStageClick(maxAgeMs?: number): boolean;
     createDisplayable(displayable: LogicAction.DisplayableElements, scene?: Scene | null, layer?: Layer | null): this;
     disposeDisplayable(displayable: LogicAction.DisplayableElements, scene?: Scene | null, layer?: Layer | null): this;

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * Hold the line while something of yours is open.
+ *
+ * A popup drawn over a line — a definition of an inline word, a term the player is reading — has to
+ * stop the line advancing underneath it, or the space bar that should dismiss the popup skips to
+ * the next line instead. Pass `true` while it is open and the stage click, the advance key and the
+ * skip key all stop reaching the dialog; the hold is released on `false`, and on unmount, so a
+ * popup that disappears can never leave the game stuck.
+ *
+ * Several holds may be out at once; the line resumes when the last one is released.
+ *
+ * @param active - Whether to hold the line right now.
+ * @example
+ * ```tsx
+ * function GlossaryTerm({children, revealed, data}: WordRenderProps<{entry: string}>) {
+ *     const [open, setOpen] = useState(false);
+ *     useSuspendAdvance(open);
+ *     return <span onClick={() => revealed && setOpen(v => !v)}>{children}</span>;
+ * }
+ * ```
+ */
+export declare function useSuspendAdvance(active: boolean): void;

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

@@ -21,6 +21,9 @@ import { NvlContainer } from "./elements/nvl/NvlContainer";
 import { DefaultNvlContainer } from "./elements/nvl/DefaultNvlContainer";
 import { NvlDialogList, DefaultNvlDialogItem } from "./elements/nvl/NvlDialogList";
 import { NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible } from "./elements/nvl/NvlContext";
+import { getWordRenderer, registerWordRenderer, unregisterWordRenderer } from "./elements/say/wordRenderer";
+import { useDialogOverlay } from "./elements/say/dialogOverlay";
+import { useSuspendAdvance } from "./lib/useSuspendAdvance";
 export type { DialogAvatarContext } from "./elements/say/Avatar";
 export type { BaseTextsProps, EntryTextsProps, RawTextsProps, TextAppearanceProps, TextsPreviewInput, TextsPreviewLoop, TextsPreviewProps, TextsProps, } from "./elements/say/Sentence";
 /**
@@ -31,7 +34,8 @@ export type { BaseTextsProps, EntryTextsProps, RawTextsProps, TextAppearanceProp
  * had no way to type either without restating the unions.
  */
 export type { TateChuYoko, TextGlyphOrientation, TextWritingMode, } from "./lib/verticalText";
+export type { DialogOverlay, DialogOverlayRect } from "./elements/say/dialogOverlay";
 export type { NametagProps } from "./elements/say/Nametag";
 export type { ItemProps } from "./elements/menu/UIMenu/Item";
 export type { ChoiceEvaluated } from "./elements/menu/type";
-export { Isolated, usePreference, Stage, GameMenu, Item, useUIMenuContext, Notifications, Texts, TextsPreview, Nametag, Dialog, Avatar, useAvatar, useDialog, useVoiceState, Page, Layout, LayoutRouterProvider, PageInjectContext, RootPath, FixedAspectRatioContainer, useKeyBinding, useLiveGame, NvlContainer, DefaultNvlContainer, NvlDialogList, DefaultNvlDialogItem, NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible, };
+export { Isolated, usePreference, Stage, GameMenu, Item, useUIMenuContext, Notifications, Texts, TextsPreview, Nametag, Dialog, Avatar, useAvatar, useDialog, useDialogOverlay, useSuspendAdvance, registerWordRenderer, unregisterWordRenderer, getWordRenderer, useVoiceState, Page, Layout, LayoutRouterProvider, PageInjectContext, RootPath, FixedAspectRatioContainer, useKeyBinding, useLiveGame, NvlContainer, DefaultNvlContainer, NvlDialogList, DefaultNvlDialogItem, NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible, };