narraleaf-react 0.42.3 → 0.43.0

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

@@ -11,7 +11,18 @@ export type BlindsOrientation = "horizontal" | "vertical";
 export declare function clamp01(value: number): number;
 /** The `mask-image` triplet, mirrored to the `-webkit-` prefix for WebKit. */
 export declare function maskStyle(image: string, size?: string, repeat?: string): CSSProps;
-/** Full-bleed positioning for a synthetic colour overlay layer. */
+/**
+ * Full-bleed positioning for a synthetic colour overlay layer.
+ *
+ * The box reaches {@link OVERLAY_BLEED} past the frame on every side. The stage scales by a
+ * non-integer factor, so the images this covers are laid out at fractional sizes and the browser
+ * draws their outermost row of pixels with partial coverage; a colour box that matches the frame
+ * exactly stops at the whole pixel inside that row and leaves it showing, as a hairline of the
+ * picture along the top or the bottom edge. For a fade *through* a colour - which is meant to
+ * reach a frame of solid colour and hand the images over behind it - that hairline is the one
+ * thing the frame must not have. The layer is synthetic and has no content to distort, so
+ * growing it costs nothing.
+ */
 export declare function overlayBase(color: string): CSSProps;
 /** CSS gradient direction keyword for a wipe travelling toward `direction`. */
 export declare function wipeGradientDir(direction: TransformDefinitions.WipeDirection): string;

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

@@ -433,6 +433,22 @@ export type GameConfig = {
      * @default false
      */
     disableTextScaling: boolean;
+    /**
+     * How long a newly typed character takes to fade in, in milliseconds. `0` turns it off.
+     *
+     * Dialogue text is normally typed at full strength, one character appearing after another. With
+     * a duration here, each character arrives faded and comes up over that time while the typewriter
+     * carries on, so the few newest characters of a line are always part-way in and the line has a
+     * soft edge rather than a hard one.
+     *
+     * The fade never outlasts the gap between two characters by more than a little: a player who
+     * raises the typing speed gets a shorter fade, and one who raises it a long way gets none worth
+     * seeing, which is what asking for fast text means. It applies only to text actually being typed
+     * - a line revealed at once, skipped, or drawn again from a save is not faded in - and a player
+     * whose system asks for reduced motion never sees it.
+     * @default 0
+     */
+    textRevealDuration: number;
     /**
      * Override the default stage
      * @default null

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

@@ -0,0 +1,63 @@
+/**
+ * Text reveal: the soft edge of the typewriter.
+ *
+ * With it on, a character does not appear at full strength — it fades in over a moment while the
+ * typewriter moves on, so a few of the newest characters are always part-way in. The effect is
+ * driven entirely by the typewriter's own cadence: a character's fade starts when its element is
+ * mounted and runs as a one-shot CSS animation, so nothing here schedules anything.
+ *
+ * Two numbers come out of this module, and both exist to keep that cheap:
+ *
+ * - the duration a fade actually runs for, which is the authored one brought down to what fits
+ *   between characters. A fade may last at most {@link MAX_REVEAL_INTERVALS} character intervals,
+ *   so raising the typing speed shortens it rather than piling up half-lit characters;
+ * - how many of the most recently revealed characters are still fading, which is how many of them
+ *   have to be elements of their own. Everything before that is settled text and is drawn as it
+ *   always was — one text node — so the line's markup is bounded whatever its length.
+ *
+ * The count carries one character of margin past the fade's own length, so a character is always
+ * finished fading before it is folded back into the settled text and its element goes away. Losing
+ * that margin is what a half-lit character snapping to full looks like.
+ */
+/**
+ * The longest a fade may run, counted in the gap between two characters.
+ *
+ * It bounds two things at once: how many characters can be fading at any moment (and so how many
+ * extra elements a line carries), and how far behind the typewriter the soft edge can trail before
+ * it stops reading as the same line being typed.
+ */
+export declare const MAX_REVEAL_INTERVALS = 8;
+/** The custom property the container writes the fade's length to. */
+export declare const REVEAL_DURATION_VAR = "--nl-reveal-duration";
+/**
+ * The class a still-fading character carries.
+ *
+ * The animation is declared in the engine's stylesheet against this class rather than written into
+ * each element's `style`: an inline animation shorthand that changed between two renders would be
+ * a new animation on an element that is already running one, and the character would start over.
+ * Reading the length from a custom property on the container leaves every character's own style
+ * untouched for as long as it lives.
+ */
+export declare const REVEAL_CLASS_NAME = "__narraleaf_text_reveal";
+export type RevealTiming = {
+    /** How long one character's fade runs, in ms. `0` when nothing fades. */
+    duration: number;
+    /** How many of the most recently revealed characters are still fading. `0` when nothing does. */
+    inFlight: number;
+};
+/**
+ * What the authored duration comes to at the speed the line is actually being typed at.
+ *
+ * @param authored the game's `textRevealDuration`, in ms
+ * @param cps characters per second, from the player's preferences
+ * @param gameSpeed the speed multiplier, from the player's preferences
+ */
+export declare function resolveRevealTiming(authored: number | undefined, cps: number, gameSpeed: number): RevealTiming;
+/**
+ * How many of a word's trailing characters are still fading.
+ *
+ * The fading characters are the last few of the *line*, so a word only holds some of them, and a
+ * word the typewriter has long passed holds none. `offset` is where the word starts in the line,
+ * counted the way the line counts its own revealed characters.
+ */
+export declare function revealTailFor(timing: RevealTiming, offset: number, length: number, revealed: number): number;

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

@@ -68,9 +68,25 @@ export declare function segmentVerticalText(text: string, maxLength: number): Ve
  */
 export declare function wordBreakStyleFor(): React.CSSProperties;
 /**
- * Renders a word's text with its short runs set upright.
+ * The smallest pieces of a word that may fade in on their own.
  *
- * 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.
+ * A character each, except where the text has already been combined: a tate-chu-yoko run is one
+ * glyph cluster set across the column and has to arrive as one, or it would be laid on its side for
+ * as long as its halves were fading separately. Characters are taken by code point rather than by
+ * code unit so a surrogate pair is never cut in half.
  */
-export declare function renderWordText(text: string, vertical: boolean, tateChuYoko: TateChuYoko | undefined): React.ReactNode;
+export declare function revealAtoms(segments: VerticalTextSegment[]): VerticalTextSegment[];
+/**
+ * Renders a word's text with its short runs set upright, and its newest characters still fading.
+ *
+ * Returns the string itself when nothing would be combined and nothing is fading, so horizontal
+ * text - and vertical text with no Latin in it - is one text node, exactly as before.
+ *
+ * `revealTail` is how many of the word's trailing characters are still fading. Each of those gets
+ * an element of its own so that mounting it starts its animation; everything before them is one
+ * settled run again, which is what keeps the markup of a long line from growing with it. The
+ * elements are `display: inline` - which they are by default, and which is the whole reason this
+ * splits at all: an `inline-block` per character would let the line break between any two of them
+ * and take a Latin word apart. Nothing here may be given a transform for the same reason.
+ */
+export declare function renderWordText(text: string, vertical: boolean, tateChuYoko: TateChuYoko | undefined, revealTail?: number): React.ReactNode;