animejs 4.4.0 → 4.5.0

package/dist/modules/utils/stagger.js

@@ -1,17 +1,17 @@
 /**
  * Anime.js - utils - ESM
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
 
 import { unitsExecRgx, emptyString } from '../core/consts.js';
-import { isUnd, parseNumber, isFnc, isNum, sqrt, abs, floor, max, round, isArr, isStr } from '../core/helpers.js';
+import { isUnd, parseNumber, isFnc, isNum, sqrt, abs, floor, round, isArr, isStr } from '../core/helpers.js';
 import { parseEase } from '../easings/eases/parser.js';
 import { parseTimelinePosition } from '../timeline/position.js';
 import { getOriginalAnimatableValue } from '../core/values.js';
 import { registerTargets } from '../core/targets.js';
-import { shuffle } from './random.js';
+import { createSeededRandom, random, shuffle } from './random.js';
 
 /**
  * @import {
@@ -64,6 +64,7 @@ const stagger = (val, params = {}) => {
   let values = [];
   let maxValue = 0;
   let cachedOffset;
+  let jitterSamples = null;
   const from = params.from;
   const reversed = params.reversed;
   const ease = params.ease;
@@ -85,27 +86,42 @@ const stagger = (val, params = {}) => {
   const val2 = isRange ? parseNumber(val[1]) : 0;
   const unitMatch = unitsExecRgx.exec((isRange ? val[1] : val) + emptyString);
   const start = params.start || 0 + (isRange ? val1 : 0);
+  const seed = params.seed;
+  const hasSeed = !isUnd(seed) && seed !== false;
+  const rng = hasSeed ? createSeededRandom(seed === true ? 0 : /** @type {Number} */(seed)) : random;
+  const jitter = params.jitter;
+  const hasJitter = !isUnd(jitter);
+  const jitterIsArr = isArr(jitter);
+  const jitterStart = jitterIsArr ? /** @type {[Number,Number]} */(jitter)[0] : /** @type {Number} */(jitter) || 0;
+  const jitterEnd = jitterIsArr ? /** @type {[Number,Number]} */(jitter)[1] : /** @type {Number} */(jitter) || 0;
   let fromIndex = fromFirst ? 0 : isNum(from) ? from : 0;
   return (target, i, t, _, tl) => {
     const [ registeredTarget ] = registerTargets(target);
     const total = isUnd(customTotal) ? t.length : customTotal;
     const customIndex = !isUnd(useProp) ? isFnc(useProp) ? useProp(registeredTarget, i, total) : getOriginalAnimatableValue(registeredTarget, useProp) : false;
-    const staggerIndex = isNum(customIndex) || isStr(customIndex) && isNum(+customIndex) ? +customIndex : i;
+    const customIdx = isNum(customIndex) || isStr(customIndex) && isNum(+customIndex) ? +customIndex : i;
+    // Fall back to the natural index when the resolved value lands outside [0, total) so values[staggerIndex] never reads undefined.
+    const staggerIndex = customIdx >= 0 && customIdx < total ? customIdx : i;
     if (fromCenter) fromIndex = (total - 1) / 2;
     if (fromLast) fromIndex = total - 1;
     if (!values.length) {
       if (autoGrid) {
         let hasPositions = true;
+        let has3D = false;
         let minPosX = Infinity;
         let minPosY = Infinity;
+        let minPosZ = Infinity;
         let maxPosX = -Infinity;
         let maxPosY = -Infinity;
+        let maxPosZ = -Infinity;
         const pxArr = [];
         const pyArr = [];
+        const pzArr = [];
         for (let index = 0; index < total; index++) {
           const el = t[index];
           let px = 0;
           let py = 0;
+          let pz = 0;
           let found = false;
           if (el && isFnc(el.getBoundingClientRect)) {
             const rect = el.getBoundingClientRect();
@@ -117,6 +133,10 @@ const stagger = (val, params = {}) => {
             if (obj && isNum(obj.x) && isNum(obj.y)) {
               px = obj.x;
               py = obj.y;
+              if (isNum(obj.z)) {
+                pz = obj.z;
+                has3D = true;
+              }
               found = true;
             }
           }
@@ -126,42 +146,52 @@ const stagger = (val, params = {}) => {
           }
           pxArr.push(px);
           pyArr.push(py);
+          pzArr.push(pz);
           if (px < minPosX) minPosX = px;
           if (py < minPosY) minPosY = py;
+          if (pz < minPosZ) minPosZ = pz;
           if (px > maxPosX) maxPosX = px;
           if (py > maxPosY) maxPosY = py;
+          if (pz > maxPosZ) maxPosZ = pz;
         }
         if (hasPositions) {
           let fX = pxArr[0];
           let fY = pyArr[0];
+          let fZ = pzArr[0];
           if (fromArr) {
             fX = minPosX + from[0] * (maxPosX - minPosX);
             fY = minPosY + from[1] * (maxPosY - minPosY);
+            fZ = has3D ? minPosZ + (from.length >= 3 ? from[2] : 0.5) * (maxPosZ - minPosZ) : 0;
           } else if (fromCenter) {
             fX = (minPosX + maxPosX) / 2;
             fY = (minPosY + maxPosY) / 2;
+            fZ = (minPosZ + maxPosZ) / 2;
           } else if (fromLast) {
             fX = pxArr[total - 1];
             fY = pyArr[total - 1];
+            fZ = pzArr[total - 1];
           } else if (isNum(from)) {
             fX = pxArr[from];
             fY = pyArr[from];
+            fZ = pzArr[from];
           }
           for (let index = 0; index < total; index++) {
             const distanceX = fX - pxArr[index];
             const distanceY = fY - pyArr[index];
-            let value = sqrt(distanceX * distanceX + distanceY * distanceY);
+            const distanceZ = fZ - pzArr[index];
+            let value = sqrt(distanceX * distanceX + distanceY * distanceY + (has3D ? distanceZ * distanceZ : 0));
             if (axis === 'x') value = -distanceX;
             if (axis === 'y') value = -distanceY;
+            if (axis === 'z') value = -distanceZ;
             values.push(value);
           }
           let minDist = Infinity;
-          for (let index = 0, l = values.length; index < l; index++) {
+          for (let index = 0; index < total; index++) {
             const absVal = abs(values[index]);
             if (absVal > 0 && absVal < minDist) minDist = absVal;
           }
           if (minDist > 0 && minDist < Infinity) {
-            for (let index = 0, l = values.length; index < l; index++) {
+            for (let index = 0; index < total; index++) {
               values[index] = values[index] / minDist;
             }
           }
@@ -175,32 +205,51 @@ const stagger = (val, params = {}) => {
           if (!grid) {
             values.push(abs(fromIndex - index));
           } else {
-            let fromX, fromY;
+            const dims = grid.length;
+            const wh = grid[0] * grid[1];
+            let fromX, fromY, fromZ;
             if (fromArr) {
               fromX = from[0] * (grid[0] - 1);
               fromY = from[1] * (grid[1] - 1);
+              fromZ = dims === 3 ? (from.length >= 3 ? from[2] : 0.5) * (grid[2] - 1) : 0;
             } else if (fromCenter) {
               fromX = (grid[0] - 1) / 2;
               fromY = (grid[1] - 1) / 2;
+              fromZ = dims === 3 ? (grid[2] - 1) / 2 : 0;
             } else {
               fromX = fromIndex % grid[0];
-              fromY = floor(fromIndex / grid[0]);
+              fromY = floor(fromIndex / grid[0]) % grid[1];
+              fromZ = dims === 3 ? floor(fromIndex / wh) : 0;
             }
             const toX = index % grid[0];
-            const toY = floor(index / grid[0]);
+            const toY = floor(index / grid[0]) % grid[1];
+            const toZ = dims === 3 ? floor(index / wh) : 0;
             const distanceX = fromX - toX;
             const distanceY = fromY - toY;
-            let value = sqrt(distanceX * distanceX + distanceY * distanceY);
+            const distanceZ = fromZ - toZ;
+            let value = sqrt(distanceX * distanceX + distanceY * distanceY + (dims === 3 ? distanceZ * distanceZ : 0));
             if (axis === 'x') value = -distanceX;
             if (axis === 'y') value = -distanceY;
+            if (axis === 'z') value = -distanceZ;
             values.push(value);
           }
         }
       }
-      maxValue = max(...values);
-      if (staggerEase) values = values.map(val => staggerEase(val / maxValue) * maxValue);
-      if (reversed) values = values.map(val => axis ? (val < 0) ? val * -1 : -val : abs(maxValue - val));
-      if (fromRandom) values = shuffle(values);
+      maxValue = values[0];
+      for (let k = 1; k < total; k++) if (values[k] > maxValue) maxValue = values[k];
+      if (staggerEase || reversed) {
+        for (let k = 0; k < total; k++) {
+          let v = values[k];
+          if (staggerEase) v = staggerEase(v / maxValue) * maxValue;
+          if (reversed) v = axis ? -v : abs(maxValue - v);
+          values[k] = v;
+        }
+      }
+      if (hasJitter) {
+        jitterSamples = new Array(total);
+        for (let k = 0; k < total; k++) jitterSamples[k] = rng(-1, 1, 4);
+      }
+      if (fromRandom) values = shuffle(values, rng);
     }
     const spacing = isRange ? (val2 - val1) / maxValue : val1;
     if (isUnd(cachedOffset)) {
@@ -208,6 +257,11 @@ const stagger = (val, params = {}) => {
     }
     /** @type {String|Number} */
     let output = cachedOffset + ((spacing * round(values[staggerIndex], 2)) || 0);
+    if (hasJitter) {
+      const progress = maxValue ? values[staggerIndex] / maxValue : 0;
+      const mag = jitterStart + (jitterEnd - jitterStart) * progress;
+      output = /** @type {Number} */(output) + jitterSamples[staggerIndex] * mag;
+    }
     if (params.modifier) output = params.modifier(/** @type {Number} */(output));
     if (unitMatch) output = `${output}${unitMatch[2]}`;
     return output;

package/dist/modules/utils/target.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - CJS
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
@@ -93,6 +93,9 @@ function get(targetSelector, propName, unit) {
  */
 const set = (targets, parameters) => {
   if (helpers.isUnd(parameters)) return;
+  if (globals.globals.editor && globals.globals.editor.addSet) {
+    return globals.globals.editor.addSet(targets, parameters);
+  }
   parameters.duration = consts.minValue;
   // Do not overrides currently active tweens by default
   parameters.composition = values.setValue(parameters.composition, consts.compositionTypes.none);

package/dist/modules/utils/target.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - ESM
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
@@ -92,6 +92,9 @@ function get(targetSelector, propName, unit) {
  */
 const set = (targets, parameters) => {
   if (isUnd(parameters)) return;
+  if (globals.editor && globals.editor.addSet) {
+    return globals.editor.addSet(targets, parameters);
+  }
   parameters.duration = minValue;
   // Do not overrides currently active tweens by default
   parameters.composition = setValue(parameters.composition, compositionTypes.none);

package/dist/modules/utils/time.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - CJS
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
@@ -28,13 +28,14 @@ const sync = (callback = consts.noop) => {
 };
 
 /**
- * @param  {(...args: any[]) => Tickable | ((...args: any[]) => void) | void} constructor
- * @return {(...args: any[]) => Tickable | ((...args: any[]) => void)}
+ * @template {Tickable | ((...args: any[]) => void) | void} T
+ * @param  {(...args: any[]) => T} constructor
+ * @return {(...args: any[]) => T extends void ? () => void : T}
  */
 const keepTime = constructor => {
   /** @type {Tickable} */
   let tracked;
-  return (...args) => {
+  return /** @type {(...args: any[]) => T extends void ? () => void : T} */(/** @type {*} */((...args) => {
     let currentIteration, currentIterationProgress, reversed, alternate, startTime;
     if (tracked) {
       currentIteration = tracked.currentIteration;
@@ -52,7 +53,7 @@ const keepTime = constructor => {
       /** @type {Tickable} */(tracked)._startTime = startTime;
     }
     return cleanup || consts.noop;
-  }
+  }));
 };
 
 exports.keepTime = keepTime;

package/dist/modules/utils/time.d.ts

@@ -1,5 +1,5 @@
 export function sync(callback?: Callback<Timer>): Timer;
-export function keepTime(constructor: (...args: any[]) => Tickable | ((...args: any[]) => void) | void): (...args: any[]) => Tickable | ((...args: any[]) => void);
+export function keepTime<T extends Tickable | ((...args: any[]) => void) | void>(constructor: (...args: any[]) => T): (...args: any[]) => T extends void ? () => void : T;
 import { Timer } from '../timer/timer.js';
 import type { Callback } from '../types/index.js';
 import type { Tickable } from '../types/index.js';

package/dist/modules/utils/time.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - utils - ESM
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */
@@ -26,13 +26,14 @@ const sync = (callback = noop) => {
 };
 
 /**
- * @param  {(...args: any[]) => Tickable | ((...args: any[]) => void) | void} constructor
- * @return {(...args: any[]) => Tickable | ((...args: any[]) => void)}
+ * @template {Tickable | ((...args: any[]) => void) | void} T
+ * @param  {(...args: any[]) => T} constructor
+ * @return {(...args: any[]) => T extends void ? () => void : T}
  */
 const keepTime = constructor => {
   /** @type {Tickable} */
   let tracked;
-  return (...args) => {
+  return /** @type {(...args: any[]) => T extends void ? () => void : T} */(/** @type {*} */((...args) => {
     let currentIteration, currentIterationProgress, reversed, alternate, startTime;
     if (tracked) {
       currentIteration = tracked.currentIteration;
@@ -50,7 +51,7 @@ const keepTime = constructor => {
       /** @type {Tickable} */(tracked)._startTime = startTime;
     }
     return cleanup || noop;
-  }
+  }));
 };
 
 export { keepTime, sync };

package/dist/modules/waapi/composition.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - waapi - CJS
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/dist/modules/waapi/composition.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - waapi - ESM
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/dist/modules/waapi/index.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - waapi - CJS
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/dist/modules/waapi/index.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - waapi - ESM
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/dist/modules/waapi/waapi.cjs

@@ -1,6 +1,6 @@
 /**
  * Anime.js - waapi - CJS
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/dist/modules/waapi/waapi.js

@@ -1,6 +1,6 @@
 /**
  * Anime.js - waapi - ESM
- * @version v4.4.0
+ * @version v4.5.0
  * @license MIT
  * @copyright 2026 - Julian Garnier
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "animejs",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "JavaScript animation engine",
   "homepage": "https://animejs.com",
   "author": "Julian Garnier <julian@animejs.com>",
@@ -36,12 +36,17 @@
     "SVG",
     "WAAPI",
     "Canvas",
-    "WebGL"
+    "WebGL",
+    "treejs",
+    "tree.js"
   ],
   "files": [
     "dist"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/modules/adapters/**",
+    "./src/adapters/**"
+  ],
   "type": "module",
   "main": "./dist/modules/index.cjs",
   "module": "./dist/modules/index.js",
@@ -175,6 +180,30 @@
       "require": "./dist/modules/waapi/index.cjs",
       "import": "./dist/modules/waapi/index.js",
       "default": "./dist/modules/waapi/index.cjs"
+    },
+    "./adapters": {
+      "types": "./dist/modules/adapters/index.d.ts",
+      "require": "./dist/modules/adapters/index.cjs",
+      "import": "./dist/modules/adapters/index.js",
+      "default": "./dist/modules/adapters/index.cjs"
+    },
+    "./adapters/three": {
+      "types": "./dist/modules/adapters/three/index.d.ts",
+      "require": "./dist/modules/adapters/three/index.cjs",
+      "import": "./dist/modules/adapters/three/index.js",
+      "default": "./dist/modules/adapters/three/index.cjs"
+    }
+  },
+  "peerDependencies": {
+    "three": ">=0.150.0",
+    "@types/three": ">=0.150.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    },
+    "@types/three": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -186,7 +215,8 @@
     "mocha": "^10.2.0",
     "nodemon": "^3.1.10",
     "rollup": "^4.9.1",
-    "three": "^0.160.0",
+    "three": "^0.184.0",
+    "@types/three": "^0.184.0",
     "tweaks": "^0.3.4",
     "typescript": "^5.9.2"
   },
@@ -196,6 +226,9 @@
     "build": "rm -rf dist && build=true rollup -c && tsc -p tsconfig.types.json && echo '\\n\\033[32m✓ build completed\\n\\033[0m'",
     "test:browser": "browser-sync start --startPath tests/index.html --server --files 'dist/modules/**/*.js' 'tests/suites/**/*.js' --no-notify --directory",
     "test:node": "node --allow-natives-syntax \"node_modules/.bin/mocha\" -u tdd --timeout 20000 \"./tests/suites/node.test.js\"",
-    "open:examples": "browser-sync start --startPath examples --server --no-notify --directory --files '**/*.js'"
+    "open:examples": "browser-sync start --startPath examples --server --no-notify --directory --files '**/*.js'",
+    "typecheck": "tsc -p . && tsc -p tests && tsc -p examples",
+    "typecheck:examples": "tsc -p examples",
+    "typecheck:tests": "tsc -p tests"
   }
 }