narraleaf-react 0.25.0 → 0.26.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/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/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.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/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.

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

@@ -366,6 +366,18 @@ export declare class GameState {
     createElementSnapshot(element: PlayerStateElement): PlayerStateElementSnapshot;
     fromElementSnapshot(snapshot: PlayerStateElementSnapshot): PlayerStateElement;
     private removeElements;
+    /**
+     * Leaving a scene returns everything the scene put on stage to the pose its constructor config
+     * describes — the displayables on each layer, and the layers themselves, which are mutable at
+     * runtime and would otherwise carry a slide or a fade into the next scene.
+     *
+     * The story camera is the one displayable that deliberately outlives a scene (a story owns
+     * exactly one, and it frames the whole stage across scene changes), so it is skipped here.
+     * Nothing in the engine's own pipeline can put it on a layer — only images, texts and puppets
+     * emit `displayable:init`, which is what registers an element into the layer map — but a host
+     * may register any displayable by hand through `DevTools.registerDisplayable`, so the camera is
+     * excluded explicitly rather than by trusting that route to stay closed.
+     */
     private resetLayers;
     private syncNvlDerivedState;
     private emitNvlStateChange;

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

@@ -0,0 +1,58 @@
+/**
+ * Vertical typesetting helpers shared by the typewriter and the preview renderer.
+ *
+ * A vertical box is set the way a Japanese novel is: glyphs stand upright in a column that reads
+ * top to bottom, and the next column starts to the left. Two things in that layout are not free,
+ * and both are about text that is not Japanese:
+ *
+ * - A Latin word must stay whole. `word-break: break-all`, which the horizontal renderer wants so
+ *   that CJK wraps anywhere, will otherwise split "Prologue" across two columns, one glyph at a
+ *   time, sideways.
+ * - A short run - a two-digit number, an initialism - reads better set upright across the column
+ *   than laid on its side. That is tate-chu-yoko (縦中横), and CSS spells it
+ *   `text-combine-upright: all` on a wrapper around exactly that run.
+ */
+import React from "react";
+export type TextWritingMode = "horizontal-tb" | "vertical-rl" | "vertical-lr";
+export type TextGlyphOrientation = "mixed" | "upright" | "sideways";
+/**
+ * Tate-chu-yoko setting: `true` uses the typographic default of two characters, a number sets the
+ * longest run to combine, and `false` turns it off.
+ */
+export type TateChuYoko = boolean | number;
+export declare const DEFAULT_TATE_CHU_YOKO_MAX_LENGTH = 2;
+export declare function isVerticalWritingMode(mode: TextWritingMode | undefined): boolean;
+/** The longest run to combine, or 0 when tate-chu-yoko is off. */
+export declare function resolveTateChuYokoMaxLength(setting: TateChuYoko | undefined): number;
+/**
+ * The writing-mode half of the text container's style.
+ *
+ * `text-orientation` is only written while vertical, where it means something; in a horizontal box
+ * it would sit in the inline style doing nothing.
+ */
+export declare function verticalContainerStyle(mode: TextWritingMode | undefined, orientation: TextGlyphOrientation | undefined): React.CSSProperties;
+export type VerticalTextSegment = {
+    text: string;
+    combineUpright: boolean;
+};
+/**
+ * Splits text into the runs tate-chu-yoko combines and the text around them.
+ *
+ * A run longer than `maxLength` is left in the surrounding segment rather than cut down to fit:
+ * a long English word belongs on its side, which is what the writing mode does with it anyway.
+ */
+export declare function segmentVerticalText(text: string, maxLength: number): VerticalTextSegment[];
+/**
+ * How a word's own box breaks.
+ *
+ * Vertical text keeps `word-break: normal`, which still breaks between CJK characters - that rule
+ * has never needed `break-all` - while leaving Latin words whole.
+ */
+export declare function wordBreakStyleFor(vertical: boolean): React.CSSProperties;
+/**
+ * Renders a word's text with its short runs set upright.
+ *
+ * Returns the string itself when nothing would be combined, so horizontal text - and vertical text
+ * with no Latin in it - is one text node, exactly as before.
+ */
+export declare function renderWordText(text: string, vertical: boolean, tateChuYoko: TateChuYoko | undefined): React.ReactNode;

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

@@ -23,6 +23,14 @@ import { NvlDialogList, DefaultNvlDialogItem } from "./elements/nvl/NvlDialogLis
 import { NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible } from "./elements/nvl/NvlContext";
 export type { DialogAvatarContext } from "./elements/say/Avatar";
 export type { BaseTextsProps, EntryTextsProps, RawTextsProps, TextAppearanceProps, TextsPreviewInput, TextsPreviewLoop, TextsPreviewProps, TextsProps, } from "./elements/say/Sentence";
+/**
+ * The vocabulary of the vertical-text props on `TextAppearanceProps`.
+ *
+ * Exported because a value has to be named somewhere other than the JSX attribute: an application
+ * that keeps its typography in a settings object, or hands the mode down through its own props,
+ * had no way to type either without restating the unions.
+ */
+export type { TateChuYoko, TextGlyphOrientation, TextWritingMode, } from "./lib/verticalText";
 export type { NametagProps } from "./elements/say/Nametag";
 export type { ItemProps } from "./elements/menu/UIMenu/Item";
 export type { ChoiceEvaluated } from "./elements/menu/type";