narraleaf-react 0.25.0 → 0.27.0

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

@@ -30,6 +30,14 @@ export declare class ActionHistoryManager {
     push<T extends Array<any> = Array<any>>(props: ActionHistoryPushOptions, onUndo?: (...args: T) => void, args?: T): {
         id: string;
     };
+    /**
+     * Whether this stack still holds the entry with the given id — i.e. whether the game can be
+     * stepped back to it in place, rather than by restoring its snapshot.
+     *
+     * The two go by the same name: a backlog entry's token *is* the id of the action-history entry
+     * pushed for the same line.
+     */
+    has(id: string): boolean;
     /**
      * Undo all actions until the given id
      *

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/action/baseElement.d.ts

@@ -1,2 +1,16 @@
 export declare class BaseElement {
+    /**
+     * Tell the engine this element's state has been written to, so the next save carries it.
+     *
+     * The engine marks an element itself whenever an action runs against it, which covers everything
+     * a story does. This is for a host that reaches past the story and writes element state
+     * directly — an editor moving a sprite, say. Without it the write is invisible to the save: the
+     * element is skipped, and loading brings back the state the script wrote, with nothing reporting
+     * that anything was lost. Debug builds do notice, and warn (see
+     * {@link Story.findUnmarkedElements}).
+     *
+     * Marking an element that turns out not to have changed is free — what decides whether an
+     * element reaches a save is the comparison against its authored state, not this flag.
+     */
+    markDirty(): this;
 }

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

@@ -36,23 +36,70 @@ export type GameHistory = GameHistoryAction & {
     snapshot?: SerializedGameState | null;
 };
 export declare class GameHistoryManager {
+    /**
+     * Every line this playthrough has reached, in order — including the ones ahead of the play head
+     * after a rewind. What separates the two is {@link GameHistoryManager.cursor}.
+     */
     private history;
+    /**
+     * Index of the line the game is on. Everything up to and including it is the backlog; everything
+     * after it is a future the player has already read once and can step forward into again.
+     * `-1` when nothing has been reached yet.
+     */
+    private cursor;
+    /**
+     * Set when the play head is moved by a rewind, cleared by the first line pushed afterwards.
+     *
+     * A line's snapshot is taken as the line is reached, so resuming from it re-runs it: the first
+     * push after a rewind is the current line again, not the next one. Without knowing that, a
+     * retrace looks like the story diverging and the lines ahead are thrown away.
+     */
+    private resumingAtCursor;
     private actionHistoryMgr;
     constructor(actionHistoryMgr: ActionHistoryManager);
-    push(action: GameHistory): this;
+    /**
+     * Record the line the game has just reached.
+     *
+     * After a rewind the play head sits behind lines that were already read, and what happens to
+     * them depends on whether play is retracing its steps or leaving them behind. Reaching the same
+     * action again is a retrace — the lines ahead are kept, so a player who stepped back three lines
+     * and read forward again can still step forward through the rest. Reaching a different action
+     * means the story went somewhere else (the other side of a choice, most often), and a future
+     * that no longer follows from the present is dropped.
+     *
+     * There are two shapes of retrace, because a line's snapshot is taken as it is *reached*, before
+     * it runs. So resuming from a restored line re-runs that very line — the first entry pushed
+     * after a rewind is the current one coming round again — and only the ones after it arrive as
+     * the line ahead.
+     *
+     * A retraced line keeps the token it had. A caller holding one is holding a reference to a line
+     * of the story, and reading past it a second time should not quietly break that reference.
+     */
+    push(entry: GameHistory): this;
+    /**
+     * The backlog: everything read up to and including the current line.
+     *
+     * Lines ahead of the play head after a rewind are deliberately not here — a backlog showing the
+     * future would be reporting what has not happened yet. Ask {@link GameHistoryManager.getFuture}
+     * for those.
+     */
     getHistory(): GameHistory[];
-    getByToken(token: string): GameHistory | null;
     /**
-     * Serialize the whole backlog for persistence (save format v2).
+     * The lines ahead of the play head — read once, rewound past, and steppable into again.
      */
-    serialize(): SerializedGameHistory[];
+    getFuture(): GameHistory[];
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Searches the whole timeline, so a line ahead of the play head can be named too. */
+    getByToken(token: string): GameHistory | null;
     /**
-     * Serialize the backlog up to and including the entry with the given token.
+     * Serialize the backlog for persistence.
      *
-     * Used by restore-to-history to trim the backlog back to the restored line.
-     * Returns an empty array if the token is not found.
+     * Only up to the play head: a save written after rewinding is a save of that moment, and the
+     * lines the player had read beyond it are not part of it. Loading such a save therefore opens
+     * with nothing to step forward into, which is what saving in the past means.
      */
-    serializeUntil(token: string): SerializedGameHistory[];
+    serialize(): SerializedGameHistory[];
     /**
      * Rebuild the backlog from persisted entries.
      *

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/camera.d.ts

@@ -31,7 +31,7 @@ export type CameraDataRaw = {
  *     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
+ *     story.camera.resetCamera(600),           // return to the neutral pose
  * ]);
  * ```
  */
@@ -68,7 +68,18 @@ export declare class Camera extends Displayable<CameraDataRaw, Camera, Transform
     /**
      * Return the camera to its neutral pose: centred, zoom `1`, no rotation, fully opaque and no
      * filter (which also clears {@link Camera.darken}).
+     *
+     * Named `resetCamera` rather than `reset` because every element already owns an internal
+     * `reset()` lifecycle hook — the one the engine calls when a new game starts — and an authoring
+     * helper of the same name would quietly stand in for it.
      * @chainable
+     * @example
+     * ```ts
+     * scene.action([
+     *     story.camera.zoom(2, 800),
+     *     story.camera.resetCamera(600),
+     * ]);
+     * ```
      */
-    reset(duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
+    resetCamera(duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
 }

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/character.d.ts

@@ -11,8 +11,15 @@ export type CharacterConfig = {
     avatar?: DialogAvatar | false;
     portraits: (Image | CharacterPortraitConfig)[];
 };
-export type CharacterStateData = {
-    name: string;
+/**
+ * What a save carries for one character.
+ *
+ * Named and shaped like every other element's save payload ({@link import("../elements/sound").SoundDataRaw},
+ * `LayerDataRaw`, `ImageDataRaw`) so that the section a serializer owns stays one level down and
+ * there is somewhere to put anything a character comes to carry besides its state.
+ */
+export type CharacterDataRaw = {
+    state: Record<string, any>;
 };
 export interface Character {
     (content: string, config?: SentenceUserConfig): Proxied<Character, Chained<LogicAction.Actions>>;
@@ -20,7 +27,7 @@ export interface Character {
     (content: SentencePrompt, config?: SentenceUserConfig): Proxied<Character, Chained<LogicAction.Actions>>;
     (texts: TemplateStringsArray, ...words: SingleWord[]): Proxied<Character, Chained<LogicAction.Actions>>;
 }
-export declare class Character extends Actionable<CharacterStateData, Character> {
+export declare class Character extends Actionable<CharacterDataRaw, Character> {
     constructor(name: string | null, config?: DeepPartial<CharacterConfig>);
     /**
      * Say something

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/game/liveGame.d.ts

@@ -90,33 +90,64 @@ export declare class LiveGame {
      */
     deserialize(savedGame: SavedGame): void;
     /**
-     * Get the history of the game
+     * The backlog: every line read up to and including the one the game is on.
      *
-     * The history is a list of element actions that have been executed
-     * For example, when a character says something, the history will record the sentence and voice
+     * After stepping back, the lines beyond the play head are not here — they are a future the
+     * player can step into again with {@link redo}, and a backlog listing them would be showing what
+     * has not happened yet. {@link getFuture} returns those.
      *
-     * You can use the id to undo the action by using `liveGame.undo(id)`
-     *
-     * This method is an utility method for creating a backlog
+     * Each entry carries a `token`, which is how {@link restoreToHistory} names a line. A token
+     * keeps naming its line across saves and rewinds.
      */
     getHistory(): GameHistory[];
     /**
-     * Undo the action
+     * The lines ahead of the play head: read once, stepped back past, and reachable again.
+     *
+     * Empty during ordinary play, and empty right after loading a save — a save written in the past
+     * carries no future, because saving after stepping back saves that moment and not the lines that
+     * had been read beyond it.
+     */
+    getFuture(): GameHistory[];
+    /** Whether there is a line before this one to step back to. */
+    canUndo(): boolean;
+    /** Whether a line stepped back past is waiting ahead. */
+    canRedo(): boolean;
+    /**
+     * Step back one line.
+     *
+     * Backward and forward are one mechanism: each line recorded a self-contained snapshot of the
+     * game when it was reached, and moving in either direction restores the snapshot of the line
+     * being moved to. That is what lets this work after loading a save, which the undo stack of
+     * live closures it replaced could not — those closures cannot be written to a file, so before
+     * this, loading a save left the player with a backlog they could not step back into.
+     *
+     * The line stepped back from is not discarded; see {@link redo}.
+     *
+     * @returns `true` if the game moved, `false` if this is already the first line or that line
+     *          carries no snapshot.
+     */
+    undo(): boolean;
+    /**
+     * Step forward one line, into a line stepped back past.
+     *
+     * Only reaches lines the player has already read: this replays the recorded future rather than
+     * running the story on. Reading forward normally after stepping back keeps that future while the
+     * story retraces the same lines, and drops it the moment the story goes somewhere else — a
+     * different branch of a choice has a different future, and the old one no longer follows.
      *
-     * - If the id is provided, it will undo the action **by id**
-     * - If the id is not provided, it will undo **the last action**
+     * @returns `true` if the game moved, `false` if there is nothing ahead or it carries no
+     *          snapshot.
      */
-    undo(id?: string): void;
+    redo(): boolean;
     /**
-     * Restore the game to a past backlog line.
+     * Move the game to a recorded line, named by its token.
      *
-     * Unlike {@link undo}, this works **after loading a save**: it does not rely on the
-     * (non-serializable) undo stack. Every backlog entry carries a self-contained state snapshot,
-     * so restoring re-applies that snapshot and trims the backlog back to that line.
+     * The same mechanism as {@link undo} and {@link redo}, and it reaches in either direction: a
+     * token from {@link getHistory} steps back, one from {@link getFuture} steps forward.
      *
-     * @param token - the backlog entry token (as returned by {@link getHistory})
-     * @returns `true` if the line was restored, `false` if the token is unknown or the entry has
-     *          no restore snapshot.
+     * @param token - the token of the line to move to
+     * @returns `true` if the line was restored, `false` if the token is unknown or the line carries
+     *          no snapshot.
      */
     restoreToHistory(token: string): boolean;
     /**

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

@@ -17,8 +17,13 @@ import type { AudioBusDeclaration } from "./game/audioBus";
  * - v1 (undefined on the save): core resume state only, no backlog history.
  * - v2: adds `game.history`, a full backlog where every entry carries a self-contained
  *   restore snapshot, so loading a save keeps the backlog and any past line can be restored.
+ * - v3: `elementStates` lists only the elements whose state differs from what the script wrote.
+ *   Restoring resets every element first, so an absent element means "as authored" rather than
+ *   "unchanged". Older engines read a v3 save without resetting, and would leave elements holding
+ *   whatever the running session put in them; newer engines read v1/v2 saves unchanged, since a
+ *   list of every element is just a list that happens to name them all.
  */
-export declare const SAVE_FORMAT_VERSION = 2;
+export declare const SAVE_FORMAT_VERSION = 3;
 export interface SavedGameMetaData {
     /**
      * The timestamp of when the game was created
@@ -76,6 +81,15 @@ export interface SerializedGameState {
  * self-contained snapshot that restores the game to exactly this line.
  */
 export interface SerializedGameHistory {
+    /**
+     * The entry's backlog token, kept so that it survives a load.
+     *
+     * A token is how a backlog UI names a line — it is what {@link LiveGame.restoreToHistory} takes.
+     * Rebuilding the backlog with fresh tokens would invalidate every token a caller was holding the
+     * moment a save is loaded or a line restored, so restoring to the same line twice would fail.
+     * Absent on saves written before this was persisted; those entries are given fresh tokens.
+     */
+    token?: string;
     /**
      * Stable action id anchor (`action.getId()`). Used to re-bind the entry to the live story on
      * load; entries whose action no longer exists (script changed) are dropped from the backlog.
@@ -298,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/Sentence.d.ts

@@ -7,6 +7,7 @@ import { Color } from "../../../../game/nlcore/types";
 import React from "react";
 import { DialogState } from "./UIDialog";
 import type { NvlDialogEntry } from "../../gameState";
+import { type TateChuYoko, type TextGlyphOrientation, type TextWritingMode } from "../../lib/verticalText";
 export type TextAppearanceProps = {
     /**
      * The default color of the text
@@ -16,6 +17,25 @@ export type TextAppearanceProps = {
     fontWeight?: React.CSSProperties["fontWeight"];
     fontWeightBold?: React.CSSProperties["fontWeight"];
     fontFamily?: React.CSSProperties["fontFamily"];
+    /**
+     * Block flow of the text box. `vertical-rl` is the classic Japanese novel setting: columns
+     * read top to bottom and advance leftwards.
+     * @default "horizontal-tb"
+     */
+    writingMode?: TextWritingMode;
+    /**
+     * How glyphs sit inside a vertical column. `mixed` keeps CJK upright and lays Latin on its
+     * side; ignored while the box is horizontal.
+     * @default "mixed"
+     */
+    textOrientation?: TextGlyphOrientation;
+    /**
+     * Tate-chu-yoko (縦中横): sets a short Latin or digit run upright across the column instead of
+     * on its side. `true` combines runs of up to two characters; a number sets the limit.
+     * Ignored while the box is horizontal.
+     * @default true
+     */
+    tateChuYoko?: TateChuYoko;
 };
 export type BaseTextsProps = TextAppearanceProps & {
     className?: string;
@@ -88,6 +108,9 @@ export interface TextsPreviewProps extends Omit<React.HTMLAttributes<HTMLDivElem
     fontWeight?: React.CSSProperties["fontWeight"];
     fontWeightBold?: React.CSSProperties["fontWeight"];
     fontFamily?: React.CSSProperties["fontFamily"];
+    writingMode?: TextWritingMode;
+    textOrientation?: TextGlyphOrientation;
+    tateChuYoko?: TateChuYoko;
     onCompleted?: () => void;
 }
 export type EntryTextsProps = BaseTextsProps & {
@@ -97,7 +120,7 @@ export type EntryTextsProps = BaseTextsProps & {
     useTypeEffect: boolean;
     isActive: boolean;
 };
-export declare function TextsPreview({ text, sentence, words, useTypeEffect, loop, restartDelay, cps, gameSpeed, pauseDuration, defaultColor, className, style, fontSize, fontWeight, fontWeightBold, fontFamily, onCompleted, ...props }: TextsPreviewProps): React.JSX.Element;
+export declare function TextsPreview({ text, sentence, words, useTypeEffect, loop, restartDelay, cps, gameSpeed, pauseDuration, defaultColor, className, style, fontSize, fontWeight, fontWeightBold, fontFamily, writingMode, textOrientation, tateChuYoko, onCompleted, ...props }: TextsPreviewProps): React.JSX.Element;
 export type RawTextsProps = BaseTextsProps;
 export declare function RawTexts(props: BaseTextsProps): React.JSX.Element;
 /**

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;