narraleaf-react 0.16.0 → 0.16.1

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

@@ -5,14 +5,16 @@ import { ImageTransition } from "../elements/transition/transitions/image/imageT
 import { TextTransition } from "../elements/transition/transitions/text/textTransition";
 import { BlurDissolve } from "../elements/transition/transitions/image/blurDissolve";
 import { Push } from "../elements/transition/transitions/image/push";
+import { Darkness } from "../elements/transition/transitions/image/darkness";
 import { ThroughColor } from "../elements/transition/transitions/image/throughColor";
 import { Reveal } from "../elements/transition/transitions/image/reveal";
 import { Mask } from "../elements/transition/transitions/image/mask";
-export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, BlurDissolve, Push, ThroughColor, Reveal, Mask, };
+export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, BlurDissolve, Push, Darkness, ThroughColor, Reveal, Mask, };
 export type { DissolveOptions } from "../elements/transition/transitions/image/dissolve";
 export type { FadeInOptions } from "../elements/transition/transitions/image/fadeIn";
 export type { BlurDissolveOptions } from "../elements/transition/transitions/image/blurDissolve";
 export type { PushOptions } from "../elements/transition/transitions/image/push";
+export type { DarknessOptions } from "../elements/transition/transitions/image/darkness";
 export type { ThroughColorOptions, ThroughColorUncover, } from "../elements/transition/transitions/image/throughColor";
 export type { RevealOptions } from "../elements/transition/transitions/image/reveal";
 export type { MaskPattern, WipePatternOptions, BarnDoorPatternOptions, IrisPatternOptions, ClockPatternOptions, FanPatternOptions, BlindsPatternOptions, DotsPatternOptions, } from "../elements/transition/transitions/image/mask";

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

@@ -34,6 +34,14 @@ export type TextEventConfig = {
  *
  * First version carries a closed set: a character-expression switch and/or a sound effect.
  *
+ * **Skip / instant reveal semantics.** Skipping the typewriter — or an instant, non-type-effect
+ * reveal that uncovers the whole sentence at once — does not drop the tokens it flies past. Every
+ * crossed token fires exactly once, in source order, so the outcome is identical to letting the
+ * typewriter reach each one in turn: the image ends in the appearance the *last* crossed token
+ * specifies, and each crossed sound effect plays once. Re-visiting an already-fired token within the
+ * same reveal is a no-op — it never double-plays a sound effect nor re-writes the expression — which
+ * is what keeps a re-mount of an already-revealed line from replaying its effects.
+ *
  * @example
  * ```ts
  * // switch Alice's portrait to "angry" the moment the typewriter reaches this point

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

@@ -12,8 +12,12 @@ export type DarknessOptions = {
     easing?: TransformDefinitions.EasingDefinition;
 };
 /**
- * Darken the original image and fade in the target image at the same time.
- * Internal: drives `image.darken(x, duration)`.
+ * A brightness-dim transition: swaps to the incoming image and animates its
+ * brightness from `1 - from` to `1 - to` (darkness `0` leaves it untouched, `1`
+ * drives it fully black), replacing the outgoing image at once.
+ *
+ * This is what backs `image.darken(amount, duration)` — darkening an image in
+ * place is expressed as a transition from its current darkness to the new one.
  */
 export declare class Darkness extends ImageTransition<AnimationType> {
     private from;

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

@@ -14,16 +14,25 @@ export type PushOptions = {
  * image slides out the opposite way, as if the camera panned.
  *
  * The offset is applied via the independent CSS `translate` property (not
- * `transform`) in viewport units. That composes additively with the layer's
- * base positioning instead of overriding it, and is the identity at offset `0`,
- * so neither image jumps at the start/end of the slide.
+ * `transform`) in **percentages of the layer's own size**. That composes
+ * additively with the layer's base positioning instead of overriding it, and is
+ * the identity at offset `0`, so neither image jumps at the start/end of the slide.
+ *
+ * Percentages — not viewport units — matter here: whichever element this drives
+ * lives inside the letterboxed stage box. On the layered render path that element
+ * is the transition stack wrapper (`inset: 0`, see `Image.tsx` `stackStyle`); on the
+ * non-layered path the style is applied to the `<img>` itself. A `100vw`/`100vh`
+ * travel is measured against the *window*, so whenever the window aspect differs
+ * from the design aspect the slide overshoots the stage and exposes the backdrop
+ * mid-transition. `100%` is measured against that element, so either way a full
+ * slide lands exactly one stage width/height away regardless of window shape.
  */
 export declare class Push extends ImageTransition<AnimationType> {
     private duration;
     private direction;
     private easing?;
     constructor(options: PushOptions);
-    private axisUnit;
+    private axisSign;
     private translate;
     createTask(): TransitionTask<HTMLImageElement, AnimationType>;
     copy(): Push;

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

@@ -18,6 +18,13 @@ type DialogStateConfig = {
     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

@@ -1,5 +1,7 @@
 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
@@ -17,3 +19,15 @@ export declare function dispatchTextEvent(event: TextEvent, state: GameState): v
  * 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/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";
@@ -36,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";
 /**