narraleaf-react 0.35.0 → 0.36.0

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

@@ -9,6 +9,17 @@ export type DarknessOptions = {
     to: number;
     /** Duration in milliseconds. */
     duration: number;
+    /**
+     * Time held at `from` before the brightness starts moving, in milliseconds, taken out of
+     * `duration`. `{from: 1, to: 0, duration: 3000, holdMs: 2000}` is two seconds of black and
+     * then a one-second lift out of it.
+     *
+     * The hold sits at `from` and not at `to` because `from` is where the image swap happens -
+     * the incoming frame is already on screen at the very first tick. That makes this the same
+     * thing {@link ThroughColor} and {@link Exposure} call a hold: the window the swap hides in.
+     * @default 0
+     */
+    holdMs?: number;
     easing?: TransformDefinitions.EasingDefinition;
 };
 /**
@@ -18,11 +29,24 @@ export type DarknessOptions = {
  *
  * 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.
+ *
+ * ⚠ The brightness is only worn for as long as the transition runs. What a
+ * settled element looks like is the element's own business — an image renders at
+ * `Image.state.darkness`, a scene root at nothing at all — so a run ending at a
+ * `to` above zero snaps back to full brightness on its last frame unless
+ * something else is holding that darkness. Ending dark is what a black
+ * background (or {@link ThroughColor} with no uncover) is for; this is a way
+ * *through* a darkness, not a way to sit in one.
+ *
+ * The channel is a linear 0-1 progress and the easing is applied by hand, so
+ * that {@link DarknessOptions.holdMs} can be real time rather than a share of an
+ * eased curve.
  */
 export declare class Darkness extends ImageTransition<AnimationType> {
     private from;
     private to;
     private duration;
+    private holdMs;
     private easing?;
     constructor(options: DarknessOptions);
     createTask(): TransitionTask<HTMLImageElement, AnimationType>;

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

@@ -20,7 +20,20 @@ export type ExposureOptions = {
      * carries the shadows up without touching the frame at rest. @default 0.04
      */
     lift?: number;
-    /** Fraction (0–1) of the duration spent fully blown out. @default 0 */
+    /**
+     * Time spent fully blown out, in milliseconds, taken out of `duration` and split evenly off
+     * the burn and the cool-down. `{duration: 3000, holdMs: 1500}` burns for 750ms, holds white
+     * for a second and a half, and comes back down over the last 750ms.
+     *
+     * Real time, not a share of an eased curve - see {@link ThroughColor} for why the run is
+     * linear. @default 0
+     */
+    holdMs?: number;
+    /**
+     * Fraction (0–1) of the duration spent fully blown out.
+     * @default 0
+     * @deprecated Use {@link holdMs}. Read only when `holdMs` is absent.
+     */
     hold?: number;
     easing?: TransformDefinitions.EasingDefinition;
 };
@@ -44,6 +57,7 @@ export declare class Exposure extends ImageTransition<AnimationType> {
     private ev;
     private lift;
     private hold;
+    private holdMs;
     private easing?;
     constructor(options: ExposureOptions);
     /**

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

@@ -18,7 +18,22 @@ export type ThroughColorOptions = {
     duration: number;
     /** Hold colour. @default "#000000" */
     color?: string;
-    /** Fraction (0–1) of the duration spent fully covered by the colour. @default 0.3 */
+    /**
+     * Time spent fully covered by the colour, in milliseconds, taken out of `duration` and split
+     * evenly off the cover and uncover halves. `{duration: 4000, holdMs: 2000}` is one second in,
+     * two seconds of solid colour, one second out.
+     *
+     * Real time, not a share of an eased curve: see {@link ThroughColor} on why the run is linear.
+     * @default 0.3 × duration
+     */
+    holdMs?: number;
+    /**
+     * Fraction (0–1) of the duration spent fully covered by the colour.
+     * @default 0.3
+     * @deprecated Use {@link holdMs}. A fraction cannot say how long the colour is actually held:
+     * it is a share of the run, so the seconds it buys move whenever the duration does. Read only
+     * when `holdMs` is absent.
+     */
     hold?: number;
     /**
      * The coverage geometry the colour covers the frame through. See
@@ -44,14 +59,22 @@ export type ThroughColorOptions = {
  *
  * The geometry lives entirely in the `pattern` option (see {@link Mask});
  * without one, the colour simply fades in and out (fade-to-black/white, or a
- * flash with `hold: 0`). {@link Reveal} is the direct-cut counterpart that
+ * flash with `holdMs: 0`). {@link Reveal} is the direct-cut counterpart that
  * takes the same patterns. The `uncover` option picks how the second half
  * plays: see {@link ThroughColorUncover}.
+ *
+ * The animation channel is deliberately **linear** and the easing is applied to
+ * each moving half by hand. Easing the whole run would make the hold a band of
+ * *progress* rather than of time, and every eased curve crosses the middle at
+ * its fastest: under the driver's default `easeInOut` a nominal 30% hold plays
+ * as 17.8% of the wall clock. `holdMs` can only mean milliseconds because of
+ * this - see `heldRunCurve`.
  */
 export declare class ThroughColor extends ImageTransition<AnimationType> {
     private duration;
     private color;
     private hold;
+    private holdMs;
     private pattern;
     private inverted;
     private uncover;

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

@@ -17,3 +17,50 @@ export declare function overlayBase(color: string): CSSProps;
 export declare function wipeGradientDir(direction: TransformDefinitions.WipeDirection): string;
 /** Gradient axis for blinds slats of a given orientation. */
 export declare function blindsAxis(orientation: BlindsOrientation): string;
+/**
+ * The curve an {@link TransformDefinitions.EasingDefinition} names, as a plain function.
+ *
+ * A transition that carves a *held* segment out of its run cannot let the animation driver ease the
+ * whole 0-1 progress: the hold would then be a band of eased progress rather than of wall-clock
+ * time, and an eased curve crosses the middle - exactly where the hold sits - at its fastest. Such
+ * a transition asks the driver for a linear channel and eases each moving half itself, which is
+ * what this resolves the curve for.
+ *
+ * The fallback is `easeInOut` and not `linear`, because that is what the driver applies when no
+ * ease is given (motion's keyframes generator defaults to it): a transition easing its own halves
+ * has to land on the same feel as one that does not.
+ */
+export declare function resolveEasing(ease?: TransformDefinitions.EasingDefinition): (t: number) => number;
+/**
+ * How far a cover -> hold -> uncover run has travelled at a given point of a LINEAR run: `0` is
+ * untouched, `1` is at the extreme (fully covered by the colour, fully blown out). Shared by
+ * {@link ThroughColor} and {@link Exposure}, which differ only in what they do with the number.
+ *
+ * The hold is wall-clock time, carved out of `duration` and split evenly off the two moving halves,
+ * so `holdMs: 2000` on a 4s run is two seconds at the extreme with a second either side. That is
+ * only true because the run itself is linear and the easing is applied to each half here. Eased as
+ * a whole - which is what asking the driver for an eased channel does - the hold is a band of
+ * *progress* instead, and the curve crosses it at its fastest: under the default `easeInOut` a
+ * nominal 30% hold plays as 17.8% of the wall clock, and 50% as 30.8%.
+ *
+ * `hold`, the fraction of the duration, is the older spelling and is read only when `holdMs` is
+ * absent.
+ */
+export declare function heldRunCurve(options: {
+    duration: number;
+    hold?: number;
+    holdMs?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+}): (progress: number) => number;
+/**
+ * The share of a run spent held at the extreme: `holdMs` measured against the duration, or the
+ * legacy `hold` fraction when no absolute time is given.
+ *
+ * A zero-length run has no share to measure, so any positive hold takes all of it - the transition
+ * is then a cut to the extreme and back, which is what a zero duration asks for.
+ */
+export declare function holdFraction(options: {
+    duration: number;
+    hold?: number;
+    holdMs?: number;
+}): number;