flet-box 1.1.0 → 1.1.1

package/src/animations/MatrixRain.js

@@ -12,6 +12,8 @@
  * @module animations/MatrixRain
  */
 
+import { prefersReducedMotion } from "./motion.js";
+
 /**
  * Creates and starts a Matrix-rain animation on a `<canvas>` element.
  *
@@ -203,7 +205,11 @@ export const MatrixRain = (props = {}) => {
       drops[i] += speed + Math.random() * speed;
     }
 
-    animationId = requestAnimationFrame(draw);
+    // Reduced motion stops the rain rather than slowing it: the field is painted
+    // once and left, because a decorative texture that scrolls forever is the
+    // exact pattern the preference was invented for. The check sits on the
+    // re-arm, so the OS setting flipping mid-session stops it within a frame.
+    animationId = prefersReducedMotion() ? null : requestAnimationFrame(draw);
   };
 
   // Initialize canvas and start animation

package/src/animations/ParallaxBox.js

@@ -14,7 +14,7 @@
  * @module animations/ParallaxBox
  */
 import { WidgetFactory } from "../widget-factory/index.js";
-import { AnimatedBox } from "../animations/AnimatedBox.js";
+import { prefersReducedMotion } from "./motion.js";
 
 /**
  * Creates a parallax-effect container.
@@ -65,10 +65,6 @@ export const ParallaxBox = (props = {}) => {
 
   let containerRef = null;
   let animationFrame = null;
-  let currentX = 0;
-  let currentY = 0;
-  let targetX = 0;
-  let targetY = 0;
   let animatedContent = null;
   let initialTimer = null;
   const transitionTimers = new Set();
@@ -100,6 +96,18 @@ export const ParallaxBox = (props = {}) => {
   const applyTransform = (x, y, animate = true) => {
     if (disabled) return;
 
+    // A layer that shifts under the reader's own scroll is the motion
+    // `prefers-reduced-motion` exists to stop, and the check belongs here rather
+    // than in the handlers: the OS setting can flip while the screen is open, and
+    // the next scroll frame is the moment that has to notice.
+    if (prefersReducedMotion()) {
+      if (animatedContent && animatedContent.style.transform) {
+        animatedContent.style.transform = "translateX(0) translateY(0)";
+        animatedContent.style.transition = "none";
+      }
+      return;
+    }
+
     let moveX = x;
     let moveY = y;
 
@@ -114,9 +122,6 @@ export const ParallaxBox = (props = {}) => {
     moveX = Math.max(-maxOffset, Math.min(maxOffset, moveX));
     moveY = Math.max(-maxOffset, Math.min(maxOffset, moveY));
 
-    targetX = moveX;
-    targetY = moveY;
-
     if (onParallaxMove) onParallaxMove({ x: moveX, y: moveY });
 
     if (animatedContent) {
@@ -144,8 +149,6 @@ export const ParallaxBox = (props = {}) => {
    * @returns {void}
    */
   const resetTransform = (animate = true) => {
-    targetX = 0;
-    targetY = 0;
     if (animatedContent) {
       animatedContent.style.transform = "translateX(0) translateY(0)";
       if (animate) {

package/src/animations/animate.js

@@ -19,14 +19,28 @@
  * @module animations/animate
  */
 
+import { toREM } from "../utils/units.js";
+import { isColor, mixColor } from "./color.js";
+import { motionDuration } from "./motion.js";
+import { resolveEasing, spring as springCurve } from "./easings.js";
+
 // ========== INTERPOLATION HELPERS ==========
 
 /**
  * Interpolates between two values at a given progress point.
- * Handles three value types:
+ * Handles four value shapes:
  * - `number → number`: straight numeric lerp.
- * - `"#rrggbb" → string`: delegates to {@link interpolateColor}.
- * - `"16px" → string`: parses the numeric part, lerps it, re-attaches the unit.
+ * - `#rrggbb` / `rgb()` / `rgba()`: the shared mixer in `color.js`.
+ * - `"16px" → anything numeric`: parses the numeric part, lerps it, re-attaches
+ *   the starting value's unit.
+ * - anything else (a named color, `hidden`/`visible`, a font stack): a cut at the
+ *   end of the loop.
+ *
+ * The last case is the one worth naming: the unit branch used to run `parseFloat`
+ * on values with no number in them and write `"NaNpx"` on every frame. The browser
+ * drops a declaration it cannot parse, so the animation looked like it ran and
+ * changed nothing at all — the same silent failure the transform registry fixed
+ * for `translateY`.
  *
  * @param {number|string} from     - Starting value.
  * @param {number|string} to       - Ending value.
@@ -38,103 +52,202 @@ const interpolate = (from, to, progress) => {
   if (typeof from === "number" && typeof to === "number") {
     return from + (to - from) * progress;
   }
-  // Color to color (hex → rgb)
-  if (typeof from === "string" && from.startsWith("#")) {
-    return interpolateColor(from, to, progress);
+  // Color to color — hex, rgb() and rgba() all blend
+  if (isColor(from) && isColor(to)) {
+    return mixColor(from, to, progress);
   }
   // String with units (e.g., "16px", "2rem")
   if (typeof from === "string") {
     const fromNum = parseFloat(from);
     const toNum = parseFloat(to);
-    const unit = from.replace(fromNum.toString(), "");
-    return fromNum + (toNum - fromNum) * progress + unit;
+    if (Number.isFinite(fromNum) && Number.isFinite(toNum)) {
+      const unit = from.replace(fromNum.toString(), "");
+      return fromNum + (toNum - fromNum) * progress + unit;
+    }
   }
-  return to;
+  // Not a number, not a length, not a color: arrive at the end, don't pretend.
+  if (from === to) return from;
+  return progress >= 1 ? to : from;
 };
 
+// ========== EASING FUNCTIONS ==========
+
 /**
- * Linearly interpolates between two hex color values, returning an `rgb()` string.
+ * Applies a named easing curve to a linear progress value.
+ *
+ * The curves live in `easings.js` so the imperative engine, the presets and a
+ * `spring()` all read the same table. A function is accepted as the curve, which
+ * is how a caller passes one that is not in the vocabulary.
  *
- * @param {string} color1   - Starting color as a hex string (e.g. `"#ff0000"`).
- * @param {string} color2   - Ending color as a hex string.
- * @param {number} progress - Interpolation factor in [0, 1].
- * @returns {string} Interpolated color as `"rgb(r, g, b)"`.
+ * @param {string|((t: number) => number)} type - Easing name or curve.
+ * @param {number} t - Raw linear progress in [0, 1].
+ * @returns {number} Eased progress; outside `[0, 1]` for the overshoot curves.
  */
-const interpolateColor = (color1, color2, progress) => {
-  const rgb1 = hexToRgb(color1);
-  const rgb2 = hexToRgb(color2);
-  const r = Math.round(rgb1.r + (rgb2.r - rgb1.r) * progress);
-  const g = Math.round(rgb1.g + (rgb2.g - rgb1.g) * progress);
-  const b = Math.round(rgb1.b + (rgb2.b - rgb1.b) * progress);
-  return `rgb(${r}, ${g}, ${b})`;
-};
+const getEasing = (type, t) => resolveEasing(type)(t);
 
 /**
- * Parses a hex color string into its red, green, and blue components.
+ * Transform functions the engine can animate, with the kind of value each one
+ * takes and the value that means "no effect" — the value an animation with no
+ * explicit `from` starts from.
  *
- * @param {string} hex - Hex color string (with or without leading `#`).
- * @returns {{ r: number, g: number, b: number }} RGB components in [0, 255].
- *   Returns `{ r: 0, g: 0, b: 0 }` if the string cannot be parsed.
+ * `translateX`/`rotate`/`skewY` are not properties of `CSSStyleDeclaration`, so
+ * the generic write path used to land them on the widget object as a harmless JS
+ * field: `animate(row, "translateY", 24, 0)` ran a full animation loop and moved
+ * nothing, which is why the skill had to tell you to reach for `scale` even for a
+ * slide. They are now composed into one `transform` string.
+ *
+ * A `length` function takes framework units, not pixels: the bare `24` a caller
+ * writes becomes `1.5rem`, the same way every routed prop does, so a slide grows
+ * with the reader's font instead of staying a pixel while the row it belongs to
+ * got taller. `angle` functions take degrees and `number` functions are scalars.
+ *
+ * @type {Object<string, { kind: "length"|"angle"|"number", neutral: number }>}
  */
-const hexToRgb = (hex) => {
-  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
-  return result
-    ? {
-        r: parseInt(result[1], 16),
-        g: parseInt(result[2], 16),
-        b: parseInt(result[3], 16),
-      }
-    : { r: 0, g: 0, b: 0 };
+const TRANSFORM_FUNCTIONS = {
+  translateX: { kind: "length", neutral: 0 },
+  translateY: { kind: "length", neutral: 0 },
+  translateZ: { kind: "length", neutral: 0 },
+  rotate: { kind: "angle", neutral: 0 },
+  rotateX: { kind: "angle", neutral: 0 },
+  rotateY: { kind: "angle", neutral: 0 },
+  rotateZ: { kind: "angle", neutral: 0 },
+  skewX: { kind: "angle", neutral: 0 },
+  skewY: { kind: "angle", neutral: 0 },
+  scale: { kind: "number", neutral: 1 },
+  scaleX: { kind: "number", neutral: 1 },
+  scaleY: { kind: "number", neutral: 1 },
 };
 
-// ========== EASING FUNCTIONS ==========
+/**
+ * The order the parts are written in. CSS transforms apply left to right, so
+ * translate first, then rotate, then scale keeps a rotation spinning about the
+ * element's own centre instead of the page's.
+ * @type {string[]}
+ */
+const TRANSFORM_ORDER = Object.keys(TRANSFORM_FUNCTIONS);
 
 /**
- * Applies a named easing curve to a linear progress value.
- * Falls back to linear if `type` is not recognized.
+ * Live transform parts per widget, so two loops on one element (a slide and a
+ * scale) each own a function rather than overwriting the whole string.
+ * @type {WeakMap<object, Map<string, number|string>>}
+ */
+const transformParts = new WeakMap();
+
+/**
+ * Merges one transform function into the widget's `transform` string.
  *
- * @param {"linear"|"easeIn"|"easeOut"|"easeInOut"} type - Easing curve name.
- * @param {number} t - Raw linear progress in [0, 1].
- * @returns {number} Eased progress value in [0, 1].
+ * @param {HTMLElement} widget   - The element to write on.
+ * @param {string}      property - A key of {@link TRANSFORM_FUNCTIONS}.
+ * @param {number|string} value  - A bare number gets the unit that function needs.
+ * @returns {void}
  */
-const getEasing = (type, t) => {
-  const easings = {
-    linear: (t) => t,
-    easeIn: (t) => t * t,
-    easeOut: (t) => t * (2 - t),
-    easeInOut: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
-  };
-  return easings[type]?.(t) ?? t;
+const writeTransformPart = (widget, property, value) => {
+  let parts = transformParts.get(widget);
+  if (!parts) {
+    parts = new Map();
+    transformParts.set(widget, parts);
+  }
+  parts.set(property, formatTransformValue(property, value));
+  widget.style.transform = TRANSFORM_ORDER.filter((name) => parts.has(name))
+    .map((name) => `${name}(${parts.get(name)})`)
+    .join(" ");
+};
+
+/**
+ * The CSS value of one transform function.
+ *
+ * A string already carries its unit and is passed through; a bare number is a
+ * framework unit for a `length`, degrees for an `angle`, and a plain scalar for a
+ * `number`.
+ *
+ * @param {string}             property - A key of {@link TRANSFORM_FUNCTIONS}.
+ * @param {number|string}      value
+ * @returns {string}
+ */
+const formatTransformValue = (property, value) => {
+  if (typeof value !== "number") return String(value);
+  const { kind } = TRANSFORM_FUNCTIONS[property];
+  if (kind === "length") return toREM(value);
+  if (kind === "angle") return `${value}deg`;
+  return String(value);
 };
 
 /**
  * Reads the current animated value of a property from a widget.
- * For `"scale"`, returns `1` as a safe default since scale is stored
- * inside a `transform` string rather than as a standalone property.
+ * Transform functions live inside a `transform` string rather than as
+ * standalone properties, so a transform with no part stored yet reads neutral
+ * (`1` for `scale`, `0` for the rest).
  *
  * @param {HTMLElement|object} widget   - The target widget or DOM element.
  * @param {string}             property - The property to read.
- * @returns {number|string} The current value, or `1` for `"scale"`.
+ * @returns {number|string} The current value, or the property's neutral value.
  */
 const readAnimatedValue = (widget, property) => {
-  if (property === "scale") return 1;
+  if (TRANSFORM_FUNCTIONS[property]) {
+    const stored = transformParts.get(widget)?.get(property);
+    if (stored !== undefined) return stored;
+    return TRANSFORM_FUNCTIONS[property].neutral;
+  }
   if (widget?.style && property in widget.style) {
     const inline = widget.style[property];
     // An inline-unset property reads as "" and `interpolate` turns that into the
     // string "NaN", which the browser silently drops — so `animate(el, "opacity",
     // undefined, 1, 300)` (the documented API) wrote "NaN" every frame and never
-    // animated anything. Fall back to the property's neutral value.
+    // animated anything. What the element actually looks like is the next place to
+    // ask, because a widget styled through a class or a stylesheet has an empty
+    // inline value and a real one: `fadeOut` of a card the theme set to 0.8 must
+    // start at 0.8, not at the neutral guess below.
     if (inline !== "" && inline !== null && inline !== undefined) return inline;
+    const computed = readComputedStyle(widget, property);
+    if (computed !== undefined) return computed;
     return property === "opacity" ? 1 : 0;
   }
   return widget?.[property];
 };
 
+/**
+ * The value a real element shows right now, from its computed style.
+ *
+ * Read once when a loop starts, never per frame. A plain object passed by a caller
+ * (a widget-shaped mock) has no computed style, and asking is what a `null` answer
+ * means here.
+ *
+ * @param {HTMLElement|object} widget
+ * @param {string} property
+ * @returns {string|undefined}
+ */
+const readComputedStyle = (widget, property) => {
+  if (typeof getComputedStyle !== "function") return undefined;
+  if (!(widget instanceof Element)) return undefined;
+  const value = getComputedStyle(widget)[property];
+  return value === "" || value === undefined ? undefined : value;
+};
+
+/**
+ * Style properties a bare number must NOT get a length unit on.
+ *
+ * The same exemptions the factory's `toCSSValue` keeps, listed here because the
+ * animation engine writes styles directly and cannot ask the prop registry.
+ * @type {Set<string>}
+ */
+const UNITLESS_STYLE_PROPS = new Set([
+  "opacity",
+  "zIndex",
+  "order",
+  "flex",
+  "flexGrow",
+  "flexShrink",
+  "fontWeight",
+  "lineHeight",
+  "aspectRatio",
+]);
+
 /**
  * Writes an animated value to a widget property.
- * - `"scale"` is written as `transform: scale(value)`.
- * - Numeric values for style properties that require a unit get `"px"` appended
- *   (unitless properties such as `opacity`, `zIndex`, etc. are exempt).
+ * - Transform functions merge into `transform` (see {@link writeTransformPart}).
+ * - A bare number on any other length is a framework unit and becomes rem, the way
+ *   a routed prop does — `animate(el, "width", 100, 300)` grows with the reader's
+ *   font instead of staying a pixel while the card around it got taller.
  * - Falls back to setting the property directly on the widget object for
  *   non-style properties.
  *
@@ -145,22 +258,15 @@ const readAnimatedValue = (widget, property) => {
  */
 const writeAnimatedValue = (widget, property, value) => {
   if (!widget) return;
-  if (property === "scale") {
-    widget.style.transform = `scale(${value})`;
+  if (TRANSFORM_FUNCTIONS[property]) {
+    if (!widget.style) return;
+    writeTransformPart(widget, property, value);
     return;
   }
   if (widget.style && property in widget.style) {
-    const unitlessProperties = new Set([
-      "opacity",
-      "zIndex",
-      "fontWeight",
-      "lineHeight",
-      "flexGrow",
-      "flexShrink",
-    ]);
     widget.style[property] =
-      typeof value === "number" && !unitlessProperties.has(property)
-        ? `${value}px`
+      typeof value === "number" && !UNITLESS_STYLE_PROPS.has(property)
+        ? toREM(value)
         : value;
     return;
   }
@@ -240,16 +346,13 @@ export const stopAnimation = (widget, property) => {
  * @param {number} duration
  * @param {string} easing
  * @param {(progress: number) => number|string} [valueAt] - Custom value curve,
- *   receiving eased progress in `[0, 1]`. Used by `pulse` to keep the whole
- *   up-and-down gesture inside a single cancelable loop.
- * @param {(progress: number) => number|string} [valueAt] - Custom value curve,
- *   receiving eased progress in `[0, 1]`. Used by `pulse` to keep the whole
- *   up-and-down gesture inside a single cancelable loop.
+ *   receiving eased progress in `[0, 1]`. Used by `pulse` and the named
+ *   transitions to keep a multi-phase gesture inside a single cancelable loop.
  * @param {(widget: HTMLElement|object) => void} [onDone] - Called when the loop
  *   ends — also when it is cancelled or replaced, so awaiting code never hangs.
  * @returns {() => boolean} Cancel function; true when it stopped a live loop.
  */
-const runAnimation = (
+export const runAnimation = (
   widget,
   property,
   from,
@@ -263,7 +366,9 @@ const runAnimation = (
   // never reaches 1 and the loop re-arms forever (and `animateAsync` never
   // resolves). Clamping the progress is not enough — it just sits at 0 and
   // `0 < 1` stays true — so sanitise the duration itself. `0` collapses to one frame.
-  const safeDuration = Math.max(0, Number(duration) || 0);
+  // Reduced motion goes through the same door: one frame that writes the end
+  // value, so the state still lands and an `await` still resolves.
+  const safeDuration = motionDuration(duration);
   const startValue = from !== undefined ? from : readAnimatedValue(widget, property);
 
   // Replace the loop already animating this property instead of racing it.
@@ -325,7 +430,8 @@ const runAnimation = (
  *   value is read from the widget via {@link readAnimatedValue}.
  * @param {number|string}      to            - Ending value.
  * @param {number}             [duration=300] - Animation duration in milliseconds.
- * @param {string}             [easing="linear"] - Easing curve name (see {@link getEasing}).
+ * @param {string|((t: number) => number)} [easing="linear"] - Easing curve name
+ *   from `EASING_NAMES`, or a curve (`spring().easing`, `cubicBezier(…)`).
  * @returns {() => boolean} Cancel function — true if it stopped a loop still running.
  *   The animation also stops on its own when a new animation takes the same property,
  *   or via {@link stopAnimation}.
@@ -352,7 +458,8 @@ export const animate = (
  *   value is read from the widget via {@link readAnimatedValue}.
  * @param {number|string}      to            - Ending value.
  * @param {number}             [duration=300] - Animation duration in milliseconds.
- * @param {string}             [easing="linear"] - Easing curve name (see {@link getEasing}).
+ * @param {string|((t: number) => number)} [easing="linear"] - Easing curve name
+ *   from `EASING_NAMES`, or a curve (`spring().easing`, `cubicBezier(…)`).
  * @returns {Promise<HTMLElement|object>} Resolves with `widget` when the animation
  *   finishes — or as soon as it is cancelled or replaced, so `await` never hangs.
  */
@@ -370,22 +477,75 @@ export const animateAsync = (
     runAnimation(widget, property, from, to, duration, easing, null, resolve);
   });
 
+/**
+ * Animates a property the way a physical object settles: overshoot, then stop.
+ *
+ * There is no duration to choose — a spring runs until its envelope has decayed
+ * inside `epsilon`, and `spring()` works that number out. Which is why this is a
+ * separate call instead of another easing name: passing `spring().duration` by
+ * hand is the same result, this only saves the arithmetic.
+ *
+ * @param {HTMLElement|object} widget   - The target widget or DOM element.
+ * @param {string}             property - The CSS property (or `"scale"`) to animate.
+ * @param {number|string}      from     - Starting value; reads the widget when `undefined`.
+ * @param {number|string}      to       - Ending value.
+ * @param {object}             [options] - Spring parameters (`stiffness`,
+ *   `damping`, `mass`, `initialVelocity`, `epsilon`, `maxDuration`); see {@link spring}.
+ * @returns {() => boolean} Cancel function (see {@link animate}).
+ */
+export const animateSpring = (widget, property, from, to, options = {}) => {
+  const { duration, easing } = springCurve(options);
+  return animate(widget, property, from, to, duration, easing ?? "linear");
+};
+
+/**
+ * The awaitable form of {@link animateSpring}.
+ *
+ * @param {HTMLElement|object} widget   - The target widget or DOM element.
+ * @param {string}             property - The CSS property (or `"scale"`) to animate.
+ * @param {number|string}      from     - Starting value.
+ * @param {number|string}      to       - Ending value.
+ * @param {object}             [options] - Spring parameters (see {@link animateSpring}).
+ * @returns {Promise<HTMLElement|object>} Resolves with `widget` when the spring
+ *   settles — or as soon as it is cancelled or replaced.
+ */
+export const animateSpringAsync = (widget, property, from, to, options = {}) => {
+  const { duration, easing } = springCurve(options);
+  return animateAsync(widget, property, from, to, duration, easing ?? "linear");
+};
+
 // ========== HELPER FUNCTIONS (Fire and Forget) ==========
 
 /**
- * Fades a widget out by animating its `opacity` from `1` to `0`.
- * Fire-and-forget — does not return a Promise.
+ * The scale a pulse is at, given eased progress.
+ *
+ * Up for the first half of the gesture and back down for the second, inside one
+ * loop: a pulse is one cancelable movement, not an animation plus a timer that
+ * starts the second half on a widget someone already unmounted.
+ *
+ * @param {number} progress - Progress through the pulse in `[0, 1]`.
+ * @returns {number} The scale to write.
+ */
+const pulseScale = (progress) =>
+  interpolate(1, 1.1, progress < 0.5 ? progress * 2 : 2 - progress * 2);
+
+/**
+ * Fades a widget out by animating its `opacity` to `0`.
+ *
+ * It starts from wherever the widget actually is — the element's own value, then
+ * its computed style — so a card the theme set to `0.8` fades from `0.8` instead
+ * of first jumping to fully opaque.
  *
  * @param {HTMLElement|object} widget        - The target widget.
  * @param {number}             [duration=300] - Fade duration in milliseconds.
  * @returns {() => boolean} Cancel function (see {@link animate}).
  */
 export const fadeOut = (widget, duration = 300) => {
-  return animate(widget, "opacity", 1, 0, duration);
+  return animate(widget, "opacity", undefined, 0, duration);
 };
 
 /**
- * Fades a widget in by animating its `opacity` from `0` to `1`.
+ * Fades a widget in by animating its `opacity` to `1`.
  * Fire-and-forget — does not return a Promise.
  *
  * @param {HTMLElement|object} widget        - The target widget.
@@ -393,7 +553,7 @@ export const fadeOut = (widget, duration = 300) => {
  * @returns {() => boolean} Cancel function (see {@link animate}).
  */
 export const fadeIn = (widget, duration = 300) => {
-  return animate(widget, "opacity", 0, 1, duration);
+  return animate(widget, "opacity", undefined, 1, duration);
 };
 
 /**
@@ -407,23 +567,12 @@ export const fadeIn = (widget, duration = 300) => {
  * @returns {() => boolean} Cancel function (see {@link animate}).
  */
 export const pulse = (widget, duration = 300) =>
-  runAnimation(
-    widget,
-    "scale",
-    1,
-    1,
-    duration,
-    "linear",
-    // One loop with a triangular curve instead of an animation plus a
-    // `setTimeout`: the timer used to start phase two on a widget that had
-    // already been removed from the DOM, and nothing could cancel it.
-    (progress) => interpolate(1, 1.1, progress < 0.5 ? progress * 2 : 2 - progress * 2),
-  );
+  runAnimation(widget, "scale", 1, 1, duration, "linear", pulseScale);
 
 // ========== ASYNC HELPER FUNCTIONS (Returns Promise) ==========
 
 /**
- * Fades a widget out by animating its `opacity` from `1` to `0`.
+ * Fades a widget out by animating its `opacity` to `0`.
  * Returns a Promise that resolves when the fade completes.
  *
  * @param {HTMLElement|object} widget        - The target widget.
@@ -431,11 +580,11 @@ export const pulse = (widget, duration = 300) =>
  * @returns {Promise<HTMLElement|object>} Resolves with `widget` on completion.
  */
 export const fadeOutAsync = (widget, duration = 300) => {
-  return animateAsync(widget, "opacity", 1, 0, duration);
+  return animateAsync(widget, "opacity", undefined, 0, duration);
 };
 
 /**
- * Fades a widget in by animating its `opacity` from `0` to `1`.
+ * Fades a widget in by animating its `opacity` to `1`.
  * Returns a Promise that resolves when the fade completes.
  *
  * @param {HTMLElement|object} widget        - The target widget.
@@ -443,19 +592,33 @@ export const fadeOutAsync = (widget, duration = 300) => {
  * @returns {Promise<HTMLElement|object>} Resolves with `widget` on completion.
  */
 export const fadeInAsync = (widget, duration = 300) => {
-  return animateAsync(widget, "opacity", 0, 1, duration);
+  return animateAsync(widget, "opacity", undefined, 1, duration);
 };
 
 /**
- * Scales a widget up then back to its original size, awaiting each phase.
- * Use this when subsequent code must run only after the full pulse finishes.
+ * The awaitable form of {@link pulse}.
+ *
+ * The same single loop, not an up-animation chained to a down-animation: the two
+ * halves were twice the frames of the gesture they described, stopped on the
+ * `setTimeout` that separated them, and resolved with nothing while every other
+ * `Async` helper resolves with the widget it just moved.
  *
  * @param {HTMLElement|object} widget        - The target widget.
  * @param {number}             [duration=300] - Total pulse duration in milliseconds
  *   (split evenly between scale-up and scale-down).
- * @returns {Promise<void>} Resolves when both phases of the pulse have completed.
+ * @returns {Promise<HTMLElement|object>} Resolves with `widget` when the pulse
+ *   finishes — or as soon as it is cancelled or replaced.
  */
-export const pulseAsync = async (widget, duration = 300) => {
-  await animateAsync(widget, "scale", 1, 1.1, duration / 2);
-  await animateAsync(widget, "scale", 1.1, 1, duration / 2);
-};
+export const pulseAsync = (widget, duration = 300) =>
+  new Promise((resolve) => {
+    runAnimation(
+      widget,
+      "scale",
+      1,
+      1,
+      duration,
+      "linear",
+      pulseScale,
+      resolve,
+    );
+  });