narraleaf-react 0.30.0 → 0.31.1

package/dist/game/nlcore/elements/built-in/screenEffects.d.ts

@@ -27,5 +27,15 @@ export type VignetteOptions = {
     easing?: TransformDefinitions.EasingDefinition;
 };
 export declare function effectLayer(scene: Scene, options?: EffectLayerOptions): Layer;
+/**
+ * @deprecated Superseded by the camera lens in 0.31.0. This draws into a scene-level layer,
+ * which sits inside the camera transform, so it scales and rotates with the camera; it is also
+ * tied to a scene while the camera is tied to the story. Use `Camera.shutter()` instead.
+ */
 export declare function blink(scene: Scene, options?: BlinkOptions): ReturnType<typeof Control.do>;
+/**
+ * @deprecated Superseded by the camera lens in 0.31.0. This draws into a scene-level layer,
+ * which sits inside the camera transform, so it scales and rotates with the camera; it is also
+ * tied to a scene while the camera is tied to the story. Use `Camera.vignette()` instead.
+ */
 export declare function vignette(scene: Scene, options?: VignetteOptions): ReturnType<typeof Control.do>;

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

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

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

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> = {