animejs 4.1.2 → 4.1.4

package/lib/anime.esm.js

@@ -1,13 +1,13 @@
 /**
  * anime.js - ESM
- * @version v4.1.2
+ * @version v4.1.4
  * @author Julian Garnier
  * @license MIT
  * @copyright (c) 2025 Julian Garnier
  * @see https://animejs.com
  */
 
-// Global types ///////////////////////////////////////////////////////////////
+// Global types ////////////////////////////////////////////////////////////////
 
 /**
  * @typedef {Object} DefaultsParams
@@ -38,17 +38,18 @@
 /** @typedef {JSAnimation|Timeline} Renderable */
 /** @typedef {Timer|Renderable} Tickable */
 /** @typedef {Timer&JSAnimation&Timeline} CallbackArgument */
-/** @typedef {Animatable|Tickable|Draggable|ScrollObserver|TextSplitter|Scope} Revertible */
+/** @typedef {Animatable|Tickable|WAAPIAnimation|Draggable|ScrollObserver|TextSplitter|Scope} Revertible */
 
-// Stagger types //////////////////////////////////////////////////////////////
+// Stagger types ///////////////////////////////////////////////////////////////
 
 /**
+ * @template T
  * @callback StaggerFunction
  * @param {Target} [target]
  * @param {Number} [index]
  * @param {Number} [length]
  * @param {Timeline} [tl]
- * @return {Number|String}
+ * @return {T}
  */
 
 /**
@@ -58,13 +59,13 @@
  * @property {Boolean} [reversed]
  * @property {Array.<Number>} [grid]
  * @property {('x'|'y')} [axis]
- * @property {String|StaggerFunction} [use]
+ * @property {String|((target: Target, i: Number, length: Number) => Number)} [use]
  * @property {Number} [total]
  * @property {EasingParam} [ease]
  * @property {TweenModifier} [modifier]
  */
 
-// Eases types ////////////////////////////////////////////////////////////////
+// Eases types /////////////////////////////////////////////////////////////////
 
 /**
  * @callback EasingFunction
@@ -92,7 +93,17 @@
 /** @typedef {Array.<TargetSelector>|TargetSelector} TargetsParam */
 /** @typedef {Array.<Target>} TargetsArray */
 
- // Callback types ////////////////////////////////////////////////////////////
+// Spring types ////////////////////////////////////////////////////////////////
+
+/**
+ * @typedef {Object} SpringParams
+ * @property {Number} [mass=1] - Mass, default 1
+ * @property {Number} [stiffness=100] - Stiffness, default 100
+ * @property {Number} [damping=10] - Damping, default 10
+ * @property {Number} [velocity=0] - Initial velocity, default 0
+ */
+
+ // Callback types //////////////////////////////////////////////////////////////
 
 /**
  * @template T
@@ -119,7 +130,7 @@
  * @property {Callback<T>} [onRender]
  */
 
-// Timer types ////////////////////////////////////////////////////////////////
+// Timer types /////////////////////////////////////////////////////////////////
 
 /**
  * @typedef {Object} TimerOptions
@@ -141,7 +152,7 @@
  * @typedef {TimerOptions & TickableCallbacks<Timer>} TimerParams
  */
 
-// Tween types ////////////////////////////////////////////////////////////////
+// Tween types /////////////////////////////////////////////////////////////////
 
 /**
  * @callback FunctionValue
@@ -212,7 +223,7 @@
 /** @typedef {WeakMap.<Target, TweenLookups>} TweenReplaceLookups */
 /** @typedef {Map.<Target, TweenLookups>} TweenAdditiveLookups */
 
-// Animation types ////////////////////////////////////////////////////////////
+// JSAnimation types ///////////////////////////////////////////////////////////
 
 /**
  * @typedef {Number|String|FunctionValue} TweenParamValue
@@ -286,7 +297,36 @@
  * @typedef {Record<String, TweenOptions | Callback<JSAnimation> | TweenModifier | boolean | PercentageKeyframes | DurationKeyframes | ScrollObserver> & TimerOptions & AnimationOptions & TweenParamsOptions & TickableCallbacks<JSAnimation> & RenderableCallbacks<JSAnimation>} AnimationParams
  */
 
-// Timeline types /////////////////////////////////////////////////////////////
+// Timeline types //////////////////////////////////////////////////////////////
+
+/**
+ * Accepts:<br>
+ * - `Number` - Absolute position in milliseconds (e.g., `500` places element at exactly 500ms)<br>
+ * - `'+=Number'` - Addition: Position element X ms after the last element (e.g., `'+=100'`)<br>
+ * - `'-=Number'` - Subtraction: Position element X ms before the last element's end (e.g., `'-=100'`)<br>
+ * - `'*=Number'` - Multiplier: Position element at a fraction of the total duration (e.g., `'*=.5'` for halfway)<br>
+ * - `'<'` - Previous end: Position element at the end position of the previous element<br>
+ * - `'<<'` - Previous start: Position element at the start position of the previous element<br>
+ * - `'<<+=Number'` - Combined: Position element relative to previous element's start (e.g., `'<<+=250'`)<br>
+ * - `'label'` - Label: Position element at a named label position (e.g., `'My Label'`)
+ *
+ * @typedef {Number|`+=${Number}`|`-=${Number}`|`*=${Number}`|'<'|'<<'|`<<+=${Number}`|`<<-=${Number}`|String} TimelinePosition
+ */
+
+/**
+ * Accepts:<br>
+ * - `Number` - Absolute position in milliseconds (e.g., `500` places animation at exactly 500ms)<br>
+ * - `'+=Number'` - Addition: Position animation X ms after the last animation (e.g., `'+=100'`)<br>
+ * - `'-=Number'` - Subtraction: Position animation X ms before the last animation's end (e.g., `'-=100'`)<br>
+ * - `'*=Number'` - Multiplier: Position animation at a fraction of the total duration (e.g., `'*=.5'` for halfway)<br>
+ * - `'<'` - Previous end: Position animation at the end position of the previous animation<br>
+ * - `'<<'` - Previous start: Position animation at the start position of the previous animation<br>
+ * - `'<<+=Number'` - Combined: Position animation relative to previous animation's start (e.g., `'<<+=250'`)<br>
+ * - `'label'` - Label: Position animation at a named label position (e.g., `'My Label'`)<br>
+ * - `stagger(String|Nummber)` - Stagger multi-elements animation positions (e.g., 10, 20, 30...)
+ *
+ * @typedef {TimelinePosition | StaggerFunction<Number|String>} TimelineAnimationPosition
+ */
 
 /**
  * @typedef {Object} TimelineOptions
@@ -298,7 +338,57 @@
  * @typedef {TimerOptions & TimelineOptions & TickableCallbacks<Timeline> & RenderableCallbacks<Timeline>} TimelineParams
  */
 
-// Animatable types ///////////////////////////////////////////////////////////
+// WAAPIAnimation types ////////////////////////////////////////////////////////
+
+/**
+ * @typedef {String|Number|Array<String>|Array<Number>} WAAPITweenValue
+ */
+
+/**
+ * @callback WAAPIFunctionValue
+ * @param {DOMTarget} target - The animated target
+ * @param {Number} index - The target index
+ * @param {Number} length - The total number of animated targets
+ * @return {WAAPITweenValue}
+ */
+
+/**
+ * @typedef {WAAPITweenValue|WAAPIFunctionValue|Array<String|Number|WAAPIFunctionValue>} WAAPIKeyframeValue
+ */
+
+/**
+ * @typedef {(animation: WAAPIAnimation) => void} WAAPICallback
+ */
+
+/**
+ * @typedef {Object} WAAPITweenOptions
+ * @property {WAAPIKeyframeValue} [to]
+ * @property {WAAPIKeyframeValue} [from]
+ * @property {Number|WAAPIFunctionValue} [duration]
+ * @property {Number|WAAPIFunctionValue} [delay]
+ * @property {EasingParam} [ease]
+ * @property {CompositeOperation} [composition]
+ */
+
+/**
+ * @typedef {Object} WAAPIAnimationOptions
+ * @property {Number|Boolean} [loop]
+ * @property {Boolean} [Reversed]
+ * @property {Boolean} [Alternate]
+ * @property {Boolean|ScrollObserver} [autoplay]
+ * @property {Number} [playbackRate]
+ * @property {Number|WAAPIFunctionValue} [duration]
+ * @property {Number|WAAPIFunctionValue} [delay]
+ * @property {EasingParam} [ease]
+ * @property {CompositeOperation} [composition]
+ * @property {WAAPICallback} [onComplete]
+ */
+
+/**
+ * @typedef {Record<String, WAAPIKeyframeValue | WAAPIAnimationOptions | Boolean | ScrollObserver | WAAPICallback | EasingParam | WAAPITweenOptions> & WAAPIAnimationOptions} WAAPIAnimationParams
+ */
+
+// Animatable types ////////////////////////////////////////////////////////////
 
 /**
  * @callback AnimatablePropertySetter
@@ -334,7 +424,7 @@
  * @typedef {Record<String, TweenParamValue | EasingParam | TweenModifier | TweenComposition | AnimatablePropertyParamsOptions> & AnimatablePropertyParamsOptions} AnimatableParams
  */
 
-// Scope types ////////////////////////////////////////////////////////////////
+// Scope types /////////////////////////////////////////////////////////////////
 
 /**
  * @typedef {Object} ReactRef
@@ -377,7 +467,52 @@
  * @return {ScopeCleanupCallback|void}
  */
 
-// Draggable types ////////////////////////////////////////////////////////////
+// Scroll types ////////////////////////////////////////////////////////////////
+
+/**
+ * @typedef {String|Number} ScrollThresholdValue
+ */
+
+/**
+ * @typedef {Object} ScrollThresholdParam
+ * @property {ScrollThresholdValue} [target]
+ * @property {ScrollThresholdValue} [container]
+ */
+
+/**
+ * @callback ScrollObserverAxisCallback
+ * @param {ScrollObserver} self
+ * @return {'x'|'y'}
+ */
+
+/**
+ * @callback ScrollThresholdCallback
+ * @param {ScrollObserver} self
+ * @return {ScrollThresholdValue|ScrollThresholdParam}
+ */
+
+/**
+ * @typedef {Object} ScrollObserverParams
+ * @property {Number|String} [id]
+ * @property {Boolean|Number|String|EasingParam} [sync]
+ * @property {TargetsParam} [container]
+ * @property {TargetsParam} [target]
+ * @property {'x'|'y'|ScrollObserverAxisCallback|((observer: ScrollObserver) => 'x'|'y'|ScrollObserverAxisCallback)} [axis]
+ * @property {ScrollThresholdValue|ScrollThresholdParam|ScrollThresholdCallback|((observer: ScrollObserver) => ScrollThresholdValue|ScrollThresholdParam|ScrollThresholdCallback)} [enter]
+ * @property {ScrollThresholdValue|ScrollThresholdParam|ScrollThresholdCallback|((observer: ScrollObserver) => ScrollThresholdValue|ScrollThresholdParam|ScrollThresholdCallback)} [leave]
+ * @property {Boolean|((observer: ScrollObserver) => Boolean)} [repeat]
+ * @property {Boolean} [debug]
+ * @property {Callback<ScrollObserver>} [onEnter]
+ * @property {Callback<ScrollObserver>} [onLeave]
+ * @property {Callback<ScrollObserver>} [onEnterForward]
+ * @property {Callback<ScrollObserver>} [onLeaveForward]
+ * @property {Callback<ScrollObserver>} [onEnterBackward]
+ * @property {Callback<ScrollObserver>} [onLeaveBackward]
+ * @property {Callback<ScrollObserver>} [onUpdate]
+ * @property {Callback<ScrollObserver>} [onSyncComplete]
+ */
+
+// Draggable types /////////////////////////////////////////////////////////////
 
 /**
  * @typedef {Object} DraggableAxisParam
@@ -426,7 +561,7 @@
  * @property {Callback<Draggable>} [onAfterResize]
  */
 
-// Text types /////////////////////////////////////////////////////////////////
+// Text types //////////////////////////////////////////////////////////////////
 
 /**
  * @typedef {Object} splitTemplateParams
@@ -455,7 +590,7 @@
  * @property {Boolean} [debug]
  */
 
-// SVG types //////////////////////////////////////////////////////////////////
+// SVG types ///////////////////////////////////////////////////////////////////
 
 /**
  * @typedef {SVGGeometryElement & {
@@ -619,13 +754,13 @@ const globals = {
   defaults,
   /** @type {Number} */
   precision: 4,
-  /** @type {Number} */
+  /** @type {Number} equals 1 in ms mode, 0.001 in s mode */
   timeScale: 1,
   /** @type {Number} */
   tickThreshold: 200,
 };
 
-const globalVersions = { version: '4.1.2', engine: null };
+const globalVersions = { version: '4.1.4', engine: null };
 
 if (isBrowser) {
   if (!win.AnimeJS) win.AnimeJS = [];
@@ -648,7 +783,6 @@ const toLowerCase = str => str.replace(lowerCaseRgx, '$1-$2').toLowerCase();
  */
 const stringStartsWith = (str, sub) => str.indexOf(sub) === 0;
 
-// Time
 // Note: Date.now is used instead of performance.now since it is precise enough for timings calculations, performs slightly faster and works in Node.js environement.
 const now = Date.now;
 
@@ -767,7 +901,7 @@ const shuffle = items => {
  * @param  {Number} v
  * @return {Number}
  */
-const clampInfinity = v => v === Infinity ? maxValue : v === -Infinity ? -1e12 : v;
+const clampInfinity = v => v === Infinity ? maxValue : v === -Infinity ? -maxValue : v;
 
 /**
  * @param  {Number} v
@@ -1405,9 +1539,10 @@ class Engine extends Clock {
     this.pauseOnDocumentHidden = true;
     /** @type {DefaultsParams} */
     this.defaults = defaults;
-    this.paused = isBrowser && doc.hidden ? true  : false;
+    // this.paused = isBrowser && doc.hidden ? true  : false;
+    this.paused = true;
     /** @type {Number|NodeJS.Immediate} */
-    this.reqId = null;
+    this.reqId = 0;
   }
 
   update() {
@@ -1442,13 +1577,16 @@ class Engine extends Clock {
   }
 
   wake() {
-    if (this.useDefaultMainLoop && !this.reqId && !this.paused) {
+    if (this.useDefaultMainLoop && !this.reqId) {
+      // Imediatly request a tick to update engine._elapsedTime and get accurate offsetPosition calculation in timer.js
+      this.requestTick(now());
       this.reqId = engineTickMethod(tickEngine);
     }
     return this;
   }
 
   pause() {
+    if (!this.reqId) return;
     this.paused = true;
     return killEngine();
   }
@@ -1589,6 +1727,7 @@ function getNodeList(v) {
  */
 function parseTargets(targets) {
   if (isNil(targets)) return /** @type {TargetsArray} */([]);
+  if (!isBrowser) return /** @type {JSTargetsArray} */(isArr(targets) && targets.flat(Infinity) || [targets]);
   if (isArr(targets)) {
     const flattened = targets.flat(Infinity);
     /** @type {TargetsArray} */
@@ -1629,7 +1768,6 @@ function parseTargets(targets) {
     }
     return parsed;
   }
-  if (!isBrowser) return /** @type {JSTargetsArray} */([targets]);
   const nodeList = getNodeList(targets);
   if (nodeList) return /** @type {DOMTargetsArray} */(Array.from(nodeList));
   return /** @type {TargetsArray} */([targets]);
@@ -1770,7 +1908,7 @@ const createDrawableProxy = ($el, start, end) => {
             // const v1 = round(+value.slice(0, spaceIndex), precision);
             // const v2 = round(+value.slice(spaceIndex + 1), precision);
             const scaleFactor = getScaleFactor($scalled);
-            const os = v1 * -1e3 * scaleFactor;
+            const os = v1 * -pathLength * scaleFactor;
             const d1 = (v2 * pathLength * scaleFactor) + os;
             const d2 = (pathLength * scaleFactor +
                       ((v1 === 0 && v2 === 1) || (v1 === 1 && v2 === 0) ? 0 : 10 * scaleFactor) - d1);
@@ -2279,12 +2417,16 @@ const composeTween = (tween, siblings) => {
 
         const prevChangeStartTime = prevSibling._startTime;
         const prevTLOffset = prevAbsEndTime - (prevChangeStartTime + prevSibling._updateDuration);
+        // Rounding is necessary here to minimize floating point errors when working in seconds
+        const updatedPrevChangeDuration = round(absoluteUpdateStartTime - prevTLOffset - prevChangeStartTime, 12);
 
-        prevSibling._changeDuration = absoluteUpdateStartTime - prevTLOffset - prevChangeStartTime;
-        prevSibling._currentTime = prevSibling._changeDuration;
+        prevSibling._changeDuration = updatedPrevChangeDuration;
+        prevSibling._currentTime = updatedPrevChangeDuration;
         prevSibling._isOverlapped = 1;
 
-        if (prevSibling._changeDuration < minValue) {
+        // Override the previous tween if its new _changeDuration is lower than minValue
+        // TODO: See if it's even neceseeary to test against minValue, checking for 0 might be enough
+        if (updatedPrevChangeDuration < minValue) {
           overrideTween(prevSibling);
         }
       }
@@ -2315,7 +2457,7 @@ const composeTween = (tween, siblings) => {
           prevParent.cancel();
           // Previously, calling .cancel() on a timeline child would affect the render order of other children
           // Worked around this by marking it as .completed and using .pause() for safe removal in the engine loop
-          // This is no longer needed since timeline tween composition is now handled separatly
+          // This is no longer needed since timeline tween composition is now handled separately
           // Keeping this here for reference
           // prevParent.completed = true;
           // prevParent.pause();
@@ -2514,18 +2656,17 @@ class Timer extends Clock {
                                 /** @type {Number} */(timerLoop) < 0 ? Infinity :
                                 /** @type {Number} */(timerLoop) + 1;
 
+
     let offsetPosition = 0;
 
     if (parent) {
       offsetPosition = parentPosition;
     } else {
-      let startTime = now();
-      // Make sure to tick the engine once if suspended to avoid big gaps with the following offsetPosition calculation
-      if (engine.paused) {
-        engine.requestTick(startTime);
-        startTime = engine._elapsedTime;
-      }
-      offsetPosition = startTime - engine._startTime;
+      // Make sure to tick the engine once if not currently running to get up to date engine._elapsedTime
+      // to avoid big gaps with the following offsetPosition calculation
+      if (!engine.reqId) engine.requestTick(now());
+      // Make sure to scale the offset position with globals.timeScale to properly handle seconds unit
+      offsetPosition = (engine._elapsedTime - engine._startTime) * globals.timeScale;
     }
 
     // Timer's parameters
@@ -2726,6 +2867,9 @@ class Timer extends Clock {
   /** @return {this} */
   resetTime() {
     const timeScale = 1 / (this._speed * engine._speed);
+    // TODO: See if we can safely use engine._elapsedTime here
+    // if (!engine.reqId) engine.requestTick(now())
+    // this._startTime = engine._elapsedTime - (this._currentTime + this._delay) * timeScale;
     this._startTime = now() - (this._currentTime + this._delay) * timeScale;
     return this;
   }
@@ -2887,7 +3031,6 @@ class Timer extends Clock {
 
 }
 
-
 /**
  * @param {TimerParams} [parameters]
  * @return {Timer}
@@ -2931,10 +3074,10 @@ const binarySubdivide = (aX, mX1, mX2) => {
 };
 
 /**
- * @param  {Number} [mX1]
- * @param  {Number} [mY1]
- * @param  {Number} [mX2]
- * @param  {Number} [mY2]
+ * @param  {Number} [mX1] The x coordinate of the first point
+ * @param  {Number} [mY1] The y coordinate of the first point
+ * @param  {Number} [mX2] The x coordinate of the second point
+ * @param  {Number} [mY2] The y coordinate of the second point
  * @return {EasingFunction}
  */
 
@@ -2957,7 +3100,7 @@ const steps = (steps = 10, fromStart) => {
 /**
  * Without parameters, the linear function creates a non-eased transition.
  * Parameters, if used, creates a piecewise linear easing by interpolating linearly between the specified points.
- * @param  {...String|Number} [args] - Points
+ * @param  {...(String|Number)} args - Points
  * @return {EasingFunction}
  */
 const linear = (...args) => {
@@ -3605,7 +3748,8 @@ class JSAnimation extends Timer {
             const isFromToArray = isArr(tweenToValue);
             const isFromToValue = isFromToArray || (hasFromvalue && hasToValue);
             const tweenStartTime = prevTween ? lastTweenChangeEndTime + tweenDelay : tweenDelay;
-            const absoluteStartTime = absoluteOffsetTime + tweenStartTime;
+            // Rounding is necessary here to minimize floating point errors when working in seconds
+            const absoluteStartTime = round(absoluteOffsetTime + tweenStartTime, 12);
 
             // Force a onRender callback if the animation contains at least one from value and autoplay is set to false
             if (!shouldTriggerRender && (hasFromvalue || isFromToArray)) shouldTriggerRender = 1;
@@ -3733,7 +3877,7 @@ class JSAnimation extends Timer {
 
             // Tween factory
 
-            // Rounding is necessary here to minimize floating point errors
+            // Rounding is necessary here to minimize floating point errors when working in seconds
             const tweenUpdateDuration = round(+tweenDuration || minValue, 12);
 
             /** @type {Tween} */
@@ -3782,7 +3926,7 @@ class JSAnimation extends Timer {
             if (isNaN(firstTweenChangeStartTime)) {
               firstTweenChangeStartTime = tween._startTime;
             }
-            // Rounding is necessary here to minimize floating point errors
+            // Rounding is necessary here to minimize floating point errors when working in seconds
             lastTweenChangeEndTime = round(tweenStartTime + tweenUpdateDuration, 12);
             prevTween = tween;
             animationAnimationLength++;
@@ -3965,7 +4109,7 @@ const WAAPIEasesLookups = {
 
 const WAAPIeases = /*#__PURE__*/(() => {
   const list = {};
-  for (let type in easeTypes) list[type] = a => easeTypes[type](easeInPower(a));
+  for (let type in easeTypes) list[type] = (/** @type {String|Number} */p) => easeTypes[type](easeInPower(p));
   return /** @type {Record<String, EasingFunction>} */(list);
 })();
 
@@ -4001,54 +4145,6 @@ const parseWAAPIEasing = (ease) => {
   return parsedEase;
 };
 
-/**
- * @typedef {String|Number|Array<String>|Array<Number>} WAAPITweenValue
- */
-
-/**
- * @callback WAAPIFunctionvalue
- * @param {DOMTarget} target - The animated target
- * @param {Number} index - The target index
- * @param {Number} length - The total number of animated targets
- * @return {WAAPITweenValue}
- */
-
-/**
- * @typedef {WAAPITweenValue|WAAPIFunctionvalue|Array<String|Number|WAAPIFunctionvalue>} WAAPIKeyframeValue
- */
-
-/**
- * @typedef {(animation: WAAPIAnimation) => void} WAAPICallback
- */
-
-/**
- * @typedef {Object} WAAPITweenOptions
- * @property {WAAPIKeyframeValue} [to]
- * @property {WAAPIKeyframeValue} [from]
- * @property {Number|WAAPIFunctionvalue} [duration]
- * @property {Number|WAAPIFunctionvalue} [delay]
- * @property {EasingParam} [ease]
- * @property {CompositeOperation} [composition]
- */
-
-/**
- * @typedef {Object} WAAPIAnimationOptions
- * @property {Number|Boolean} [loop]
- * @property {Boolean} [Reversed]
- * @property {Boolean} [Alternate]
- * @property {Boolean|ScrollObserver} [autoplay]
- * @property {Number} [playbackRate]
- * @property {Number|WAAPIFunctionvalue} [duration]
- * @property {Number|WAAPIFunctionvalue} [delay]
- * @property {EasingParam} [ease]
- * @property {CompositeOperation} [composition]
- * @property {WAAPICallback} [onComplete]
- */
-
-/**
- * @typedef {Record<String, WAAPIKeyframeValue | WAAPIAnimationOptions | Boolean | ScrollObserver | WAAPICallback | EasingParam | WAAPITweenOptions> & WAAPIAnimationOptions} WAAPIAnimationParams
- */
-
 const transformsShorthands = ['x', 'y', 'z'];
 const commonDefaultPXProperties = [
   'perspective',
@@ -4346,7 +4442,7 @@ class WAAPIAnimation {
    * @return {this}
    */
   forEach(callback) {
-    const cb = isStr(callback) ? a => a[callback]() : callback;
+    const cb = isStr(callback) ? (/** @type {globalThis.Animation} */a) => a[callback]() : callback;
     this.animations.forEach(cb);
     return this;
   }
@@ -4879,10 +4975,6 @@ const utils = {
 
 
 
-/**
- * @typedef {Number|String|Function} TimePosition
- */
-
 /**
  * Timeline's children offsets positions parser
  * @param  {Timeline} timeline
@@ -4900,7 +4992,7 @@ const getPrevChildOffset = (timeline, timePosition) => {
 
 /**
  * @param  {Timeline} timeline
- * @param  {TimePosition} [timePosition]
+ * @param  {TimelinePosition} [timePosition]
  * @return {Number}
  */
 const parseTimelinePosition = (timeline, timePosition) => {
@@ -5006,17 +5098,17 @@ class Timeline extends Timer {
    * @overload
    * @param {TargetsParam} a1
    * @param {AnimationParams} a2
-   * @param {TimePosition} [a3]
+   * @param {TimelinePosition|StaggerFunction<Number|String>} [a3]
    * @return {this}
    *
    * @overload
    * @param {TimerParams} a1
-   * @param {TimePosition} [a2]
+   * @param {TimelinePosition} [a2]
    * @return {this}
    *
    * @param {TargetsParam|TimerParams} a1
-   * @param {AnimationParams|TimePosition} a2
-   * @param {TimePosition} [a3]
+   * @param {TimelinePosition|AnimationParams} a2
+   * @param {TimelinePosition|StaggerFunction<Number|String>} [a3]
    */
   add(a1, a2, a3) {
     const isAnim = isObj(a2);
@@ -5027,7 +5119,7 @@ class Timeline extends Timer {
         const childParams = /** @type {AnimationParams} */(a2);
         // Check for function for children stagger positions
         if (isFnc(a3)) {
-          const staggeredPosition = /** @type {Function} */(a3);
+          const staggeredPosition = a3;
           const parsedTargetsArray = parseTargets(/** @type {TargetsParam} */(a1));
           // Store initial duration before adding new children that will change the duration
           const tlDuration = this.duration;
@@ -5036,7 +5128,8 @@ class Timeline extends Timer {
           // Store the original id in order to add specific indexes to the new animations ids
           const id = childParams.id;
           let i = 0;
-          const parsedLength = parsedTargetsArray.length;
+          /** @type {Number} */
+          const parsedLength = (parsedTargetsArray.length);
           parsedTargetsArray.forEach((/** @type {Target} */target) => {
             // Create a new parameter object for each staggered children
             const staggeredChildParams = { ...childParams };
@@ -5047,7 +5140,7 @@ class Timeline extends Timer {
             addTlChild(
               staggeredChildParams,
               this,
-              staggeredPosition(target, i, parsedLength, this),
+              parseTimelinePosition(this, staggeredPosition(target, i, parsedLength, this)),
               target,
               i,
               parsedLength
@@ -5067,7 +5160,7 @@ class Timeline extends Timer {
         addTlChild(
           /** @type TimerParams */(a1),
           this,
-          parseTimelinePosition(this,/** @type TimePosition */(a2)),
+          parseTimelinePosition(this,a2),
         );
       }
       return this.init(1); // 1 = internalRender
@@ -5077,21 +5170,21 @@ class Timeline extends Timer {
   /**
    * @overload
    * @param {Tickable} [synced]
-   * @param {TimePosition} [position]
+   * @param {TimelinePosition} [position]
    * @return {this}
    *
    * @overload
    * @param {globalThis.Animation} [synced]
-   * @param {TimePosition} [position]
+   * @param {TimelinePosition} [position]
    * @return {this}
    *
    * @overload
    * @param {WAAPIAnimation} [synced]
-   * @param {TimePosition} [position]
+   * @param {TimelinePosition} [position]
    * @return {this}
    *
    * @param {Tickable|WAAPIAnimation|globalThis.Animation} [synced]
-   * @param {TimePosition} [position]
+   * @param {TimelinePosition} [position]
    */
   sync(synced, position) {
     if (isUnd(synced) || synced && isUnd(synced.pause)) return this;
@@ -5103,7 +5196,7 @@ class Timeline extends Timer {
   /**
    * @param  {TargetsParam} targets
    * @param  {AnimationParams} parameters
-   * @param  {TimePosition} [position]
+   * @param  {TimelinePosition} [position]
    * @return {this}
    */
   set(targets, parameters, position) {
@@ -5115,7 +5208,7 @@ class Timeline extends Timer {
 
   /**
    * @param {Callback<Timer>} callback
-   * @param {TimePosition} [position]
+   * @param {TimelinePosition} [position]
    * @return {this}
    */
   call(callback, position) {
@@ -5125,13 +5218,13 @@ class Timeline extends Timer {
 
   /**
    * @param {String} labelName
-   * @param {TimePosition} [position]
+   * @param {TimelinePosition} [position]
    * @return {this}
    *
    */
   label(labelName, position) {
     if (isUnd(labelName) || labelName && !isStr(labelName)) return this;
-    this.labels[labelName] = parseTimelinePosition(this,/** @type TimePosition */(position));
+    this.labels[labelName] = parseTimelinePosition(this, position);
     return this;
   }
 
@@ -5203,20 +5296,49 @@ class Animatable {
    */
   constructor(targets, parameters) {
     if (scope.current) scope.current.register(this);
+    const beginHandler = () => {
+      if (this.callbacks.completed) this.callbacks.reset();
+      this.callbacks.play();
+    };
+    const pauseHandler = () => {
+      if (this.callbacks.completed) return;
+      let paused = true;
+      for (let name in this.animations) {
+        const anim = this.animations[name];
+        if (!anim.paused && paused) {
+          paused = false;
+          break;
+        }
+      }
+      if (paused) {
+        this.callbacks.complete();
+      }
+    };
+    /** @type {AnimationParams} */
+    const globalParams = {
+      onBegin: beginHandler,
+      onComplete: pauseHandler,
+      onPause: pauseHandler,
+    };
     /** @type {AnimationParams} */
-    const globalParams = {};
+    const callbacksAnimationParams = { v: 1, autoplay: false };
     const properties = {};
     this.targets = [];
     this.animations = {};
+    /** @type {JSAnimation|null} */
+    this.callbacks = null;
     if (isUnd(targets) || isUnd(parameters)) return;
     for (let propName in parameters) {
       const paramValue = parameters[propName];
       if (isKey(propName)) {
         properties[propName] = paramValue;
+      } else if (stringStartsWith(propName, 'on')) {
+        callbacksAnimationParams[propName] = paramValue;
       } else {
         globalParams[propName] = paramValue;
       }
     }
+    this.callbacks = new JSAnimation({ v: 0 }, callbacksAnimationParams);
     for (let propName in properties) {
       const propValue = properties[propName];
       const isObjValue = isObj(propValue);
@@ -5276,6 +5398,7 @@ class Animatable {
     }
     this.animations = {};
     this.targets.length = 0;
+    if (this.callbacks) this.callbacks.revert();
     return this;
   }
 }
@@ -5285,7 +5408,7 @@ class Animatable {
  * @param {AnimatableParams} parameters
  * @return {AnimatableObject}
  */
-const createAnimatable = (targets, parameters) => /** @type {AnimatableObject} */(new Animatable(targets, parameters));
+const createAnimatable = (targets, parameters) => /** @type {AnimatableObject} */ (new Animatable(targets, parameters));
 
 
 
@@ -5295,6 +5418,8 @@ const createAnimatable = (targets, parameters) => /** @type {AnimatableObject} *
  * Webkit Copyright © 2016 Apple Inc
  */
 
+const maxSpringParamValue = K * 10;
+
 /**
  * @typedef {Object} SpringParams
  * @property {Number} [mass=1] - Mass, default 1
@@ -5302,7 +5427,6 @@ const createAnimatable = (targets, parameters) => /** @type {AnimatableObject} *
  * @property {Number} [damping=10] - Damping, default 10
  * @property {Number} [velocity=0] - Initial velocity, default 0
  */
-
 class Spring {
   /**
    * @param {SpringParams} [parameters]
@@ -5314,10 +5438,10 @@ class Spring {
     this.maxDuration = 60000; // The maximum allowed spring duration in ms (default 1 min)
     this.maxRestSteps = this.restDuration / this.timeStep / K; // How many steps allowed after reaching restThreshold before stopping the duration calculation
     this.maxIterations = this.maxDuration / this.timeStep / K; // Calculate the maximum iterations allowed based on maxDuration
-    this.m = clamp(setValue(parameters.mass, 1), 0, K);
-    this.s = clamp(setValue(parameters.stiffness, 100), 1, K);
-    this.d = clamp(setValue(parameters.damping, 10), .1, K);
-    this.v = clamp(setValue(parameters.velocity, 0), -1e3, K);
+    this.m = clamp(setValue(parameters.mass, 1), 0, maxSpringParamValue);
+    this.s = clamp(setValue(parameters.stiffness, 100), 1, maxSpringParamValue);
+    this.d = clamp(setValue(parameters.damping, 10), .1, maxSpringParamValue);
+    this.v = clamp(setValue(parameters.velocity, 0), -maxSpringParamValue, maxSpringParamValue);
     this.w0 = 0;
     this.zeta = 0;
     this.wd = 0;
@@ -5368,7 +5492,7 @@ class Spring {
   }
 
   set mass(v) {
-    this.m = clamp(setValue(v, 1), 0, K);
+    this.m = clamp(setValue(v, 1), 0, maxSpringParamValue);
     this.compute();
   }
 
@@ -5377,7 +5501,7 @@ class Spring {
   }
 
   set stiffness(v) {
-    this.s = clamp(setValue(v, 100), 1, K);
+    this.s = clamp(setValue(v, 100), 1, maxSpringParamValue);
     this.compute();
   }
 
@@ -5386,7 +5510,7 @@ class Spring {
   }
 
   set damping(v) {
-    this.d = clamp(setValue(v, 10), .1, K);
+    this.d = clamp(setValue(v, 10), .1, maxSpringParamValue);
     this.compute();
   }
 
@@ -5395,7 +5519,7 @@ class Spring {
   }
 
   set velocity(v) {
-    this.v = clamp(setValue(v, 0), -1e3, K);
+    this.v = clamp(setValue(v, 0), -maxSpringParamValue, maxSpringParamValue);
     this.compute();
   }
 }
@@ -5665,7 +5789,7 @@ class Draggable {
     /** @type {[Number, Number, Number, Number]} */
     this.dragArea = [0, 0, 0, 0]; // x, y, w, h
     /** @type {[Number, Number, Number, Number]} */
-    this.containerBounds = [-1e12, maxValue, maxValue, -1e12]; // t, r, b, l
+    this.containerBounds = [-maxValue, maxValue, maxValue, -maxValue]; // t, r, b, l
     /** @type {[Number, Number, Number, Number]} */
     this.scrollBounds = [0, 0, 0, 0]; // t, r, b, l
     /** @type {[Number, Number, Number, Number]} */
@@ -5694,32 +5818,23 @@ class Draggable {
     this.touchActionStyles = null;
     this.transforms = new Transforms(this.$target);
     this.overshootCoords = { x: 0, y: 0 };
-    this.overshootXTicker = new Timer({ autoplay: false }, null, 0).init();
-    this.overshootYTicker = new Timer({ autoplay: false }, null, 0).init();
-    this.updateTicker = new Timer({ autoplay: false }, null, 0).init();
-    this.overshootXTicker.onUpdate = () => {
-      if (this.disabled[0]) return;
-      this.updated = true;
-      this.manual = true;
-      this.animate[this.xProp](this.overshootCoords.x, 0);
-    };
-    this.overshootXTicker.onComplete = () => {
-      if (this.disabled[0]) return;
-      this.manual = false;
-      this.animate[this.xProp](this.overshootCoords.x, 0);
-    };
-    this.overshootYTicker.onUpdate = () => {
-      if (this.disabled[1]) return;
-      this.updated = true;
-      this.manual = true;
-      this.animate[this.yProp](this.overshootCoords.y, 0);
-    };
-    this.overshootYTicker.onComplete = () => {
-      if (this.disabled[1]) return;
-      this.manual = false;
-      this.animate[this.yProp](this.overshootCoords.y, 0);
-    };
-    this.updateTicker.onUpdate = () => this.update();
+    this.overshootTicker = new Timer({
+      autoplay: false,
+      onUpdate: () => {
+        this.updated = true;
+        this.manual = true;
+        // Use a duration of 1 to prevent the animatable from completing immediately to prevent issues with onSettle()
+        // https://github.com/juliangarnier/anime/issues/1045
+        if (!this.disabled[0]) this.animate[this.xProp](this.overshootCoords.x, 1);
+        if (!this.disabled[1]) this.animate[this.yProp](this.overshootCoords.y, 1);
+      },
+      onComplete: () => {
+        this.manual = false;
+        if (!this.disabled[0]) this.animate[this.xProp](this.overshootCoords.x, 0);
+        if (!this.disabled[1]) this.animate[this.yProp](this.overshootCoords.y, 0);
+      },
+    }, null, 0).init();
+    this.updateTicker = new Timer({ autoplay: false, onUpdate: () => this.update() }, null,0,).init();
     this.contained = !isUnd(container);
     this.manual = false;
     this.grabbed = false;
@@ -5730,7 +5845,7 @@ class Draggable {
     this.enabled = false;
     this.initialized = false;
     this.activeProp = this.disabled[1] ? xProp : yProp;
-    this.animate.animations[this.activeProp].onRender = () => {
+    this.animate.callbacks.onRender = () => {
       const hasUpdated = this.updated;
       const hasMoved = this.grabbed && hasUpdated;
       const hasReleased = !hasMoved && this.released;
@@ -5742,7 +5857,8 @@ class Draggable {
       this.deltaY = dy;
       this.coords[2] = x;
       this.coords[3] = y;
-      // Check if dx or dy are not 0 to check if the draggable has actually moved https://github.com/juliangarnier/anime/issues/1032
+      // Check if dx or dy are not 0 to check if the draggable has actually moved
+      // https://github.com/juliangarnier/anime/issues/1032
       if (hasUpdated && (dx || dy)) {
         this.onUpdate(this);
       }
@@ -5753,9 +5869,9 @@ class Draggable {
         this.angle = atan2(dy, dx);
       }
     };
-    this.animate.animations[this.activeProp].onComplete = () => {
+    this.animate.callbacks.onComplete = () => {
       if ((!this.grabbed && this.released)) {
-        // Set eleased to false before calling onSettle to avoid recursion
+        // Set released to false before calling onSettle to avoid recursion
         this.released = false;
       }
       if (!this.manual) {
@@ -5823,7 +5939,7 @@ class Draggable {
   setX(x, muteUpdateCallback = false) {
     if (this.disabled[0]) return;
     const v = round(x, 5);
-    this.overshootXTicker.pause();
+    this.overshootTicker.pause();
     this.manual = true;
     this.updated = !muteUpdateCallback;
     this.destX = v;
@@ -5841,7 +5957,7 @@ class Draggable {
   setY(y, muteUpdateCallback = false) {
     if (this.disabled[1]) return;
     const v = round(y, 5);
-    this.overshootYTicker.pause();
+    this.overshootTicker.pause();
     this.manual = true;
     this.updated = !muteUpdateCallback;
     this.destY = v;
@@ -5898,6 +6014,9 @@ class Draggable {
 
   updateBoundingValues() {
     const $container = this.$container;
+    // Return early if no $container defined to prevents error when reading scrollWidth / scrollHeight
+    // https://github.com/juliangarnier/anime/issues/1064
+    if (!$container) return;
     const cx = this.x;
     const cy = this.y;
     const cx2 = this.coords[2];
@@ -5967,14 +6086,13 @@ class Draggable {
   }
 
   /**
-   * Returns 0 if not OB, 1 if x is OB, 2 if y is OB, 3 if both x and y are OB
-   *
    * @param  {Array} bounds
    * @param  {Number} x
    * @param  {Number} y
    * @return {Number}
    */
   isOutOfBounds(bounds, x, y) {
+    // Returns 0 if not OB, 1 if x is OB, 2 if y is OB, 3 if both x and y are OB
     if (!this.contained) return 0;
     const [ bt, br, bb, bl ] = bounds;
     const [ dx, dy ] = this.disabled;
@@ -6107,8 +6225,7 @@ class Draggable {
 
   stop() {
     this.updateTicker.pause();
-    this.overshootXTicker.pause();
-    this.overshootYTicker.pause();
+    this.overshootTicker.pause();
     // Pauses the in bounds onRelease animations
     for (let prop in this.animate.animations) this.animate.animations[prop].pause();
     remove(this, null, 'x');
@@ -6135,10 +6252,10 @@ class Draggable {
     const canScroll = this.canScroll;
     if (!this.containerArray && this.isOutOfBounds(scrollBounds, x, y)) {
       const [ st, sr, sb, sl ] = scrollBounds;
-      const t = round(clamp(y - st, -1e12, 0), 0);
+      const t = round(clamp(y - st, -maxValue, 0), 0);
       const r = round(clamp(x - sr, 0, maxValue), 0);
       const b = round(clamp(y - sb, 0, maxValue), 0);
-      const l = round(clamp(x - sl, -1e12, 0), 0);
+      const l = round(clamp(x - sl, -maxValue, 0), 0);
       new JSAnimation(scroll, {
         x: round(scroll.x + (l ? l - gap : r ? r + gap : 0), 0),
         y: round(scroll.y + (t ? t - gap : b ? b + gap : 0), 0),
@@ -6196,7 +6313,7 @@ class Draggable {
    */
   handleDown(e) {
     const $eTarget = /** @type {HTMLElement} */(e.target);
-    if (this.grabbed || /** @type {HTMLInputElement}  */($eTarget).type === 'range') return;
+    if (this.grabbed || /** @type {HTMLInputElement} */($eTarget).type === 'range') return;
 
     e.stopPropagation();
 
@@ -6415,8 +6532,7 @@ class Draggable {
           composition,
         }).init();
 
-        this.overshootXTicker.stretch(durationX).restart();
-        this.overshootYTicker.stretch(durationY).restart();
+        this.overshootTicker.stretch(max(durationX, durationY)).restart();
 
     } else {
 
@@ -6546,8 +6662,7 @@ class Draggable {
     this.disable();
     this.$target.classList.remove('is-disabled');
     this.updateTicker.revert();
-    this.overshootXTicker.revert();
-    this.overshootYTicker.revert();
+    this.overshootTicker.revert();
     this.resizeTicker.revert();
     this.animate.revert();
     this.resizeObserver.disconnect();
@@ -6820,10 +6935,6 @@ class Scope {
  */
 const createScope = params => new Scope(params);
 
-/**
- * @typedef {String|Number} ScrollThresholdValue
- */
-
 /**
  * @return {Number}
  */
@@ -6975,8 +7086,8 @@ class ScrollContainer {
       height = this.winHeight;
     } else {
       const elRect = $el.getBoundingClientRect();
-      width = elRect.width;
-      height = elRect.height;
+      width = $el.clientWidth;
+      height = $el.clientHeight;
       this.top = elRect.top;
       this.left = elRect.left;
     }
@@ -7134,45 +7245,6 @@ let scrollerIndex = 0;
 
 const debugColors$1 = ['#FF4B4B','#FF971B','#FFC730','#F9F640','#7AFF5A','#18FF74','#17E09B','#3CFFEC','#05DBE9','#33B3F1','#638CF9','#C563FE','#FF4FCF','#F93F8A'];
 
-/**
- * @typedef {Object} ScrollThresholdParam
- * @property {ScrollThresholdValue} [target]
- * @property {ScrollThresholdValue} [container]
- */
-
-/**
- * @callback ScrollObserverAxisCallback
- * @param {ScrollObserver} self
- * @return {'x'|'y'}
- */
-
-/**
- * @callback ScrollThresholdCallback
- * @param {ScrollObserver} self
- * @return {ScrollThresholdValue|ScrollThresholdParam}
- */
-
-/**
- * @typedef {Object} ScrollObserverParams
- * @property {Number|String} [id]
- * @property {Boolean|Number|String|EasingParam} [sync]
- * @property {TargetsParam} [container]
- * @property {TargetsParam} [target]
- * @property {'x'|'y'|ScrollObserverAxisCallback|((observer: ScrollObserver) => 'x'|'y'|ScrollObserverAxisCallback)} [axis]
- * @property {ScrollThresholdValue|ScrollThresholdParam|ScrollThresholdCallback|((observer: ScrollObserver) => ScrollThresholdValue|ScrollThresholdParam|ScrollThresholdCallback)} [enter]
- * @property {ScrollThresholdValue|ScrollThresholdParam|ScrollThresholdCallback|((observer: ScrollObserver) => ScrollThresholdValue|ScrollThresholdParam|ScrollThresholdCallback)} [leave]
- * @property {Boolean|((observer: ScrollObserver) => Boolean)} [repeat]
- * @property {Boolean} [debug]
- * @property {Callback<ScrollObserver>} [onEnter]
- * @property {Callback<ScrollObserver>} [onLeave]
- * @property {Callback<ScrollObserver>} [onEnterForward]
- * @property {Callback<ScrollObserver>} [onLeaveForward]
- * @property {Callback<ScrollObserver>} [onEnterBackward]
- * @property {Callback<ScrollObserver>} [onLeaveBackward]
- * @property {Callback<ScrollObserver>} [onUpdate]
- * @property {Callback<ScrollObserver>} [onSyncComplete]
- */
-
 class ScrollObserver {
   /**
    * @param {ScrollObserverParams} parameters
@@ -7256,6 +7328,8 @@ class ScrollObserver {
     this.forceEnter = false;
     /** @type {Boolean} */
     this.hasEntered = false;
+    /** @type {Boolean} */
+    this.isReady = false;
     // /** @type {Array.<Number>} */
     // this.offsets = [];
     /** @type {Number} */
@@ -7344,6 +7418,8 @@ class ScrollObserver {
   }
 
   refresh() {
+    // This flag is used to prevent running handleScroll() outside of this.refresh() with values not calculated
+    this.isReady = true;
     this.reverted = false;
     const params = this._params;
     this.repeat = setValue(parseScrollObserverFunctionParameter(params.repeat, this), true);
@@ -7609,6 +7685,7 @@ class ScrollObserver {
   }
 
   handleScroll() {
+    if (!this.isReady) return;
     const linked = this.linked;
     const sync = this.sync;
     const syncEase = this.syncEase;
@@ -7640,7 +7717,7 @@ class ScrollObserver {
       if (syncSmooth && isNum(syncSmooth)) {
         if (/** @type {Number} */(syncSmooth) < 1) {
           const step = 0.0001;
-          const snap = lp < p && p === 1 ? step : lp > p && !p ? -1e-4 : 0;
+          const snap = lp < p && p === 1 ? step : lp > p && !p ? -step : 0;
           p = round(lerp(lp, p, interpolate(.01, .2, /** @type {Number} */(syncSmooth)), false) + snap, 6);
         }
       } else if (syncEase) {
@@ -7732,6 +7809,7 @@ class ScrollObserver {
       this.removeDebug();
     }
     this.reverted = true;
+    this.isReady = false;
     return this;
   }
 
@@ -7746,7 +7824,7 @@ const onScroll = (parameters = {}) => new ScrollObserver(parameters);
 
 
 
-const segmenter = !isUnd(Intl) && Intl.Segmenter;
+const segmenter = (typeof Intl !== 'undefined') && Intl.Segmenter;
 const valueRgx = /\{value\}/g;
 const indexRgx = /\{i\}/g;
 const whiteSpaceGroupRgx = /(\s+)/;
@@ -8201,9 +8279,33 @@ const text = {
 
 
 /**
- * @param  {Number|String|[Number|String,Number|String]} val
- * @param  {StaggerParams} params
- * @return {StaggerFunction}
+ * @overload
+ * @param {Number} val
+ * @param {StaggerParams} [params]
+ * @return {StaggerFunction<Number>}
+ */
+/**
+ * @overload
+ * @param {String} val
+ * @param {StaggerParams} [params]
+ * @return {StaggerFunction<String>}
+ */
+/**
+ * @overload
+ * @param {[Number, Number]} val
+ * @param {StaggerParams} [params]
+ * @return {StaggerFunction<Number>}
+ */
+/**
+ * @overload
+ * @param {[String, String]} val
+ * @param {StaggerParams} [params]
+ * @return {StaggerFunction<String>}
+ */
+/**
+ * @param {Number|String|[Number, Number]|[String, String]} val The staggered value or range
+ * @param {StaggerParams} [params] The stagger parameters
+ * @return {StaggerFunction<Number|String>}
  */
 const stagger = (val, params = {}) => {
   let values = [];