narraleaf-react 0.29.1 → 0.31.0

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

@@ -22,9 +22,10 @@ export declare const DisplayableActionTypes: {
     readonly applyTransform: "displayable:applyTransform";
     readonly applyTransition: "displayable:applyTransition";
     readonly init: "displayable:init";
+    readonly bringToFront: "displayable:bringToFront";
 };
 export type DisplayableActionContentType<TransitionType extends Transition = Transition> = {
-    [K in typeof DisplayableActionTypes[keyof typeof DisplayableActionTypes]]: K extends "displayable:applyTransform" ? [Transform] : K extends "displayable:applyTransition" ? [TransitionType, ((transition: TransitionType) => TransitionType)?] : K extends "displayable:init" ? [scene: Scene | null, layer: Layer | null, isElement?: boolean] : any;
+    [K in typeof DisplayableActionTypes[keyof typeof DisplayableActionTypes]]: K extends "displayable:applyTransform" ? [Transform] : K extends "displayable:applyTransition" ? [TransitionType, ((transition: TransitionType) => TransitionType)?] : K extends "displayable:init" ? [scene: Scene | null, layer: Layer | null, isElement?: boolean] : K extends "displayable:bringToFront" ? [] : any;
 };
 export declare const CharacterActionTypes: {
     readonly say: "character:say";

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

@@ -17,10 +17,26 @@ export declare class DisplayableAction<T extends Values<typeof DisplayableAction
         readonly applyTransform: "displayable:applyTransform";
         readonly applyTransition: "displayable:applyTransition";
         readonly init: "displayable:init";
+        readonly bringToFront: "displayable:bringToFront";
     };
     executeAction(gameState: GameState, injection: ActionExecutionInjection): ExecutedActionResult;
     applyTransform(state: GameState, element: Displayable<any, any>, transform: Transform, injection: ActionExecutionInjection, onFinished?: () => void): Awaitable<CalledActionResult, CalledActionResult>;
     applyTransition(state: GameState, element: Displayable<any, any>, transition: TransitionType, injection: ActionExecutionInjection, onFinished?: () => void): Awaitable<CalledActionResult, CalledActionResult>;
     initDisplayable(state: GameState, scene: Scene | null, element: Displayable<any, any>, layer: Layer | null, isElement: boolean | undefined, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
+    /**
+     * Move the element to the end of the array its layer draws from.
+     *
+     * A layer renders its elements in array order, so the last entry is the one drawn on top; there
+     * is no per-element depth number to set. Reordering the array rather than introducing one is
+     * what keeps this saveable for free — {@link GameState.toData} writes each layer out as a list
+     * of ids in exactly this order, and loading rebuilds the array from it.
+     *
+     * Nothing is tweened, so the returned awaitable is settled before it is handed back.
+     */
+    bringToFront(state: GameState, element: Displayable<any, any>, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
+    /**
+     * The array of the scene's layer that currently holds this element, or null if none does.
+     */
+    private static getLayerElements;
     stringify(_story: Story, _seen: Set<LogicAction.Actions>, _strict: boolean): string;
 }

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

@@ -9,8 +9,9 @@ import { Darkness } from "../elements/transition/transitions/image/darkness";
 import { Exposure } from "../elements/transition/transitions/image/exposure";
 import { ThroughColor } from "../elements/transition/transitions/image/throughColor";
 import { Reveal } from "../elements/transition/transitions/image/reveal";
+import { RuleReveal } from "../elements/transition/transitions/image/ruleReveal";
 import { Mask } from "../elements/transition/transitions/image/mask";
-export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, BlurDissolve, Push, Darkness, Exposure, ThroughColor, Reveal, Mask, };
+export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, BlurDissolve, Push, Darkness, Exposure, ThroughColor, Reveal, RuleReveal, 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";
@@ -19,5 +20,6 @@ export type { DarknessOptions } from "../elements/transition/transitions/image/d
 export type { ExposureOptions } from "../elements/transition/transitions/image/exposure";
 export type { ThroughColorOptions, ThroughColorUncover, } from "../elements/transition/transitions/image/throughColor";
 export type { RevealOptions } from "../elements/transition/transitions/image/reveal";
+export type { RuleRevealOptions } from "../elements/transition/transitions/image/ruleReveal";
 export type { MaskPattern, WipePatternOptions, BarnDoorPatternOptions, IrisPatternOptions, ClockPatternOptions, FanPatternOptions, BlindsPatternOptions, DotsPatternOptions, } from "../elements/transition/transitions/image/mask";
 export type { BlindsOrientation } from "../elements/transition/transitions/image/transitionMaskUtils";

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

@@ -8,9 +8,10 @@ import { Chained, Proxied } from "../action/chain";
  *
  * A camera is transformed exactly like any other displayable, so its initial pose is described
  * with the same {@link TransformDefinitions.ImageTransformProps} fields (position, zoom, scale,
- * rotation, opacity, filter, ...).
+ * rotation, opacity, filter, ...), plus the lens channels
+ * ({@link TransformDefinitions.CameraLensProps}) only a camera has.
  */
-export type ICameraUserConfig = TransformDefinitions.ImageTransformProps;
+export type ICameraUserConfig = TransformDefinitions.CameraTransformProps;
 export type CameraDataRaw = {
     transformState: Record<string, any>;
 };
@@ -35,7 +36,7 @@ export type CameraDataRaw = {
  * ]);
  * ```
  */
-export declare class Camera extends Displayable<CameraDataRaw, Camera, TransformDefinitions.ImageTransformProps> implements EventfulDisplayable {
+export declare class Camera extends Displayable<CameraDataRaw, Camera, TransformDefinitions.CameraTransformProps> implements EventfulDisplayable {
     /**
      * Create a camera. A story already owns a default one ({@link Story.camera}); construct your
      * own only to override the initial pose via the story config.
@@ -66,8 +67,64 @@ export declare class Camera extends Displayable<CameraDataRaw, Camera, Transform
      */
     darken(darkness: number, duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
     /**
-     * Return the camera to its neutral pose: centred, zoom `1`, no rotation, fully opaque and no
-     * filter (which also clears {@link Camera.darken}).
+     * Close or open the shutter: two blades that meet in the middle of the frame.
+     *
+     * `1` is fully shut and `0` fully open, and everything between is a partial cover — which makes
+     * a small standing value a letterbox rather than a blink, `0.12` being about a cinematic matte.
+     * A blink is this driven to `1` and back; the timing of one is the story's to choose, so the
+     * engine offers the channel rather than a named routine.
+     *
+     * @param shutter - Coverage between `0` (open) and `1` (shut). Out-of-range values are clamped.
+     * @chainable
+     * @example
+     * ```ts
+     * scene.action([
+     *     story.camera.shutter(1, 180, "easeInOut"),
+     *     story.camera.shutter(0, 220, "easeInOut"),
+     * ]);
+     * ```
+     */
+    shutter(shutter: number, duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
+    /**
+     * Darken the corners of the frame.
+     *
+     * Unlike {@link Camera.darken}, which is a filter over the picture, this is a plate over the
+     * *view*: it does not move with the camera, so a vignette holds still while the stage
+     * underneath it zooms, pans and rotates. Adjust its falloff with {@link Camera.lens}.
+     *
+     * @param vignette - Strength between `0` (none) and `1`. Out-of-range values are clamped.
+     * @chainable
+     * @example
+     * ```ts
+     * scene.action([
+     *     story.camera.vignette(0.72, 300, "easeInOut"),
+     *     jS`Everything narrowed to the middle of the room.`,
+     *     story.camera.vignette(0, 300, "easeInOut"),
+     * ]);
+     * ```
+     */
+    vignette(vignette: number, duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
+    /**
+     * Set any of the lens channels at once — the two strengths and the colour and falloff geometry
+     * they are drawn with.
+     *
+     * The geometry fields take effect the next time the strength they belong to is above `0`, so
+     * they are usually set as a cut before the effect is faded in.
+     *
+     * @chainable
+     * @example
+     * ```ts
+     * scene.action([
+     *     story.camera.lens({vignetteColor: "#1a0b2e", vignetteInner: "20%", vignetteOuter: "95%"}),
+     *     story.camera.vignette(0.9, 400),
+     * ]);
+     * ```
+     */
+    lens(lens: TransformDefinitions.CameraLensProps, options?: TransformDefinitions.VisualEffectOptions): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
+    /**
+     * Return the camera to its neutral pose: centred, zoom `1`, no rotation, fully opaque, no
+     * filter (which also clears {@link Camera.darken}) and no lens effect — the shutter opens and
+     * the vignette lifts.
      *
      * 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
@@ -82,4 +139,20 @@ export declare class Camera extends Displayable<CameraDataRaw, Camera, Transform
      * ```
      */
     resetCamera(duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
+    /**
+     * Not available on a camera: a camera has no front or back to be moved to.
+     *
+     * `bringToFront` reorders the list of elements a layer draws, and the camera is in no such list
+     * — it is the thing those lists are drawn *inside*. Every layer of every scene moves with it as
+     * one unit, which is the whole point of it, and there is therefore no sprite it could be put in
+     * front of. This is not a matter of the camera not being on stage yet, which is what the
+     * inherited error would have said: waiting changes nothing, because the camera never enters a
+     * layer at all.
+     *
+     * Reach for a transform instead — `zoom`, or {@link Camera.pan} — if the goal was to
+     * bring something into view.
+     *
+     * @throws RuntimeGameError - always
+     */
+    bringToFront(): never;
 }

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

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

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

@@ -179,6 +179,29 @@ export declare abstract class Displayable<StateData extends Record<string, any>,
      * ```
      */
     transform(transform: Transform<TransformType>): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Bring the Displayable to the front of the layer it is on.
+     *
+     * Within one layer the order elements are shown in is the order they were added in, so the one
+     * added last is drawn over the others. This moves the element to the end of that order, and
+     * nothing else about it changes — it stays on the same layer, keeps its transform, and the move
+     * is instant.
+     *
+     * Depth *between* layers is a separate thing, decided by each layer's z-index; this cannot lift
+     * an element above one that sits on a higher layer.
+     *
+     * The new order is part of the saved game, so a save taken afterwards restores it.
+     *
+     * @chainable
+     * @example
+     * ```ts
+     * scene.action([
+     *     yukoSprite.bringToFront(),
+     *     yuko.say`It was me, all along.`,
+     * ]);
+     * ```
+     */
+    bringToFront(): Proxied<Self, Chained<LogicAction.Actions, Self>>;
     private registerEffectSrc;
     private static toCSSUrl;
     private static extractCSSUrls;

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

@@ -44,4 +44,15 @@ export declare class Layer extends Displayable<LayerDataRaw, Layer, TransformDef
      * @chainable
      */
     setZIndex(zIndex: number): Proxied<Layer, Chained<LogicAction.Actions>>;
+    /**
+     * Not available on a layer: depth between layers is the z-index.
+     *
+     * `bringToFront` moves an element to the end of the list its layer draws, and a layer is not
+     * in any such list — it *is* one. Accepting the call would mean accepting a story that reads as
+     * if it raised the layer and plays as if the line were not there, which is the failure the
+     * throw exists to prevent. Use {@link Layer.setZIndex} instead.
+     *
+     * @throws RuntimeGameError - always
+     */
+    bringToFront(): never;
 }

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

@@ -1,3 +1,4 @@
+import React from "react";
 import { TransformDefinitions } from "./type";
 import { CSSProps } from "../../elements/transition/type";
 type OverwriteMap = {
@@ -7,6 +8,30 @@ export type OverwriteDefinition = {
     [K in keyof OverwriteMap]?: OverwriteHandler<OverwriteMap[K]>;
 };
 type OverwriteHandler<T> = (value: Partial<TransformDefinitions.Types>) => T;
+/**
+ * An element that is animated *alongside* the transform's own element, from the same transform
+ * state, in the same `motion` sequence.
+ *
+ * The transform pipeline drives exactly one element, and its style is built by
+ * {@link Transform.constructStyle} — a literal, so a prop it does not know about goes nowhere. A
+ * companion is the escape hatch for props whose picture belongs to a *different* element than the
+ * one being transformed: the camera's lens overlay, which must not inherit the camera's transform,
+ * is the case this exists for.
+ *
+ * `project` turns the accumulated state of a segment into that element's style for that segment.
+ */
+export type TransformCompanion = {
+    el: Element;
+    project: (props: Partial<TransformDefinitions.Types>) => CSSProps;
+};
+/**
+ * The same thing before the elements are known — what a React host holds, resolved to
+ * {@link TransformCompanion} at the moment the animation is built.
+ */
+export type TransformCompanionRef = {
+    ref: React.RefObject<HTMLElement | null>;
+    project: (props: Partial<TransformDefinitions.Types>) => CSSProps;
+};
 export declare class Transform<T extends TransformDefinitions.Types = TransformDefinitions.Types> {
     /**
      * Apply transform immediately
@@ -127,6 +152,19 @@ export declare class Transform<T extends TransformDefinitions.Types = TransformD
      * Set visual effect fields in the current staging sequence.
      */
     effect(effect: TransformDefinitions.VisualEffectTransformProps): this;
+    /**
+     * Set camera lens fields in the current staging sequence.
+     *
+     * Only a {@link Camera} draws these; on any other displayable they are carried in the state and
+     * never painted.
+     * @example
+     * ```ts
+     * Transform.create<TransformDefinitions.CameraTransformProps>()
+     *     .lens({shutter: 1}).commit({duration: 180, ease: "easeInOut"})
+     *     .lens({shutter: 0}).commit({duration: 220, ease: "easeInOut"});
+     * ```
+     */
+    lens(lens: TransformDefinitions.CameraLensProps): this;
     /**
      * Set the CSS mask image of the current staging sequence.
      */

package/dist/game/nlcore/elements/transform/type.d.ts

@@ -29,6 +29,50 @@ export declare namespace TransformDefinitions {
         backdropFilter?: React.CSSProperties["backdropFilter"];
         mixBlendMode?: React.CSSProperties["mixBlendMode"];
     };
+    /**
+     * The camera's lens channels.
+     *
+     * These describe things a *lens* does, not things the picture does, which is why they are not
+     * part of {@link VisualEffectTransformProps} and never reach an element's own style: they are
+     * drawn by an overlay pinned to the viewport, outside the camera's transform, so a vignette
+     * stays put while the camera it belongs to zooms, pans and rotates underneath it.
+     */
+    type CameraLensProps = {
+        /**
+         * How far the shutter is closed, between `0` (open) and `1` (shut).
+         *
+         * Two blades close symmetrically from the top and bottom of the frame, so at `1` each
+         * covers half of it. Small values are a letterbox rather than a blink: `0.12` is a
+         * cinematic matte.
+         * @default 0
+         */
+        shutter?: number;
+        /**
+         * Colour of the shutter blades.
+         * @default "#000"
+         */
+        shutterColor?: string;
+        /**
+         * Strength of the vignette, between `0` (none) and `1` (opaque at the edges).
+         * @default 0
+         */
+        vignette?: number;
+        /**
+         * Colour of the vignette.
+         * @default "#000"
+         */
+        vignetteColor?: string;
+        /**
+         * Radius at which the vignette starts, as a CSS length or percentage of the frame.
+         * @default "44%"
+         */
+        vignetteInner?: string;
+        /**
+         * Radius at which the vignette reaches full strength.
+         * @default "78%"
+         */
+        vignetteOuter?: string;
+    };
     type VisualEffectOptions = Partial<CommonTransformProps>;
     type MaskOptions = VisualEffectOptions & Pick<VisualEffectTransformProps, "maskSize" | "maskPosition" | "maskRepeat" | "maskMode">;
     type WipeDirection = "left" | "right" | "top" | "bottom";
@@ -49,7 +93,16 @@ export declare namespace TransformDefinitions {
     type TextTransformProps = CommonDisplayableConfig & {
         fontColor?: Color;
     } & VisualEffectTransformProps;
-    type Types = CommonDisplayableConfig & ImageTransformProps & TextTransformProps;
+    /**
+     * What a camera can be transformed by: everything an image can, plus the lens channels.
+     */
+    type CameraTransformProps = ImageTransformProps & CameraLensProps;
+    /**
+     * The closed set of keys a {@link Transform} can stage a change for. Every prop any displayable
+     * understands has to appear here, camera-only ones included, or the chainable setters cannot
+     * name it.
+     */
+    type Types = CommonDisplayableConfig & ImageTransformProps & TextTransformProps & CameraLensProps;
     type SequenceProps<T> = Partial<T>;
     type SequenceOptions = Partial<CommonTransformProps>;
     type Sequence<T> = {

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

@@ -0,0 +1,102 @@
+import { AnimationController, AnimationTaskMapArray, TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
+import { ImageSrc } from "../../../../types";
+type AnimationType = [TransitionAnimationType.Number];
+export type RuleRevealOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /**
+     * The rule image: a greyscale picture whose brightness at each point says *when* that point
+     * changes over. Dark changes first, bright last, so a rule painted as a spiral wipes as a
+     * spiral. Stretched to the frame, so paint it at the stage's aspect ratio.
+     */
+    rule: ImageSrc;
+    /**
+     * Width of the soft edge, as a fraction of the rule's brightness range. `0.12` puts roughly an
+     * eighth of the rule's tonal range in transition at any moment; smaller is a crisper edge.
+     * @default 0.12
+     */
+    feather?: number;
+    /** Change the bright areas over first instead of the dark ones. @default false */
+    inverted?: boolean;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * The **rule-image** engine: the target is revealed over the previous frame in the order a
+ * greyscale picture dictates, rather than through a geometric pattern.
+ *
+ * This is the transition form commercial visual novels are authored against — a pack of rule
+ * images (spirals, shatters, brush strokes, drifting cloud fronts) and one engine that plays any of
+ * them. {@link Reveal} covers the geometric half of the same job with {@link Mask} patterns, which
+ * are CSS gradients and therefore limited to shapes that can be *described*; a rule image is
+ * per-pixel data and can be any shape at all, which is why it is its own engine rather than another
+ * `MaskPattern`.
+ *
+ * ```ts
+ * scene.jumpTo(next, new RuleReveal({duration: 1200, rule: "/rules/spiral.png"}))
+ * ```
+ *
+ * ### How it works, and the one thing worth knowing
+ *
+ * At progress `t` a point changes over once the sweep has passed its brightness:
+ *
+ * ```text
+ * alpha = clamp01((T - luminance) / feather),  T sweeping 0 .. 1 + feather
+ * ```
+ *
+ * That is computed by an SVG filter — `feImage` reads the rule, `feColorMatrix` turns its
+ * brightness into coverage, and one `feComposite` does the comparison — so the whole sweep is one
+ * GPU pass over the frame and costs the same as no filter at all in practice.
+ *
+ * The filter runs in **sRGB**, deliberately: filters default to linearRGB, under which a rule's
+ * mid-grey would land at 0.21 rather than half way, and every rule in a pack would play with its
+ * timing bent. Nothing about that failure looks like an error, so it is pinned here rather than
+ * left to a default.
+ */
+export declare class RuleReveal extends ImageTransition<AnimationType> {
+    private duration;
+    private rule;
+    private feather;
+    private inverted;
+    private easing?;
+    /**@package */
+    private filterId;
+    /**@package */
+    private host;
+    /**@package */
+    private cut;
+    constructor(options: RuleRevealOptions);
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    /**
+     * Tear the scaffold down when the run ends, however it ends.
+     *
+     * Both drivers call this, and the controller they get back outlives the React element — a
+     * transition whose element unmounts mid-run still completes its value animation — so this is
+     * the one place that sees every ending. {@link styleAt} also drops it on the settled frame, so
+     * the normal path never waits for this.
+     * @package
+     */
+    requestAnimations(tasks: AnimationTaskMapArray<AnimationType>): AnimationController<AnimationType>;
+    copy(): RuleReveal;
+    /**
+     * The style for one frame — and the side of this class that has to stay honest about the DOM.
+     *
+     * The settled frame carries no filter at all rather than a filter wound to its end: a filter
+     * left on a scene root keeps that subtree rasterised as one layer, and the settled pose resets
+     * `filter` on the assumption that a finished transition owns nothing.
+     * @package
+     */
+    private styleAt;
+    /**
+     * Build the filter once, on first use, and hand back the id to point `filter` at.
+     *
+     * Not built in `createTask`: that method is documented as free of side effects, and it is
+     * called by callers that only want to read what a transition would write.
+     * @package
+     */
+    private ensureScaffold;
+    /**@package */
+    private dispose;
+}
+export {};