anime-cursor 2.0.1 → 2.1.0

package/README.md

@@ -33,7 +33,7 @@ AnimeCursor has no dependencies on any frameworks, making it suitable for person
 ### CDN
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/anime-cursor@v2.0.0/dist/anime-cursor.umd.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/anime-cursor@v2.1.0/dist/anime-cursor.umd.min.js"></script>
 ```
 
 ### npm
@@ -125,6 +125,7 @@ An object that defines all cursor types. Each key is a cursor name (any string).
 
 | Option             | Type    | Default                                | Description                                                  |
 | ------------------ | ------- | -------------------------------------- | ------------------------------------------------------------ |
+| `combineAnimations` | boolean | `false` | Automatically merges cursor animations with element‑defined animations (via `data-ac-animation`). When enabled, any element with the `data-ac-animation` attribute will have its own CSS animation combined with the cursor animation, allowing both to run simultaneously without overriding each other. |
 | `debug`            | boolean | `false`                                | Enables a debug overlay showing current cursor type and coordinates. |
 | `enableTouch`      | boolean | `false`                                | Allow animated cursors on touch devices (detected automatically, disabled by default). |
 | `fallbackCursor`   | string  | `'auto'`                               | Global fallback cursor for all animated cursors (e.g., `'auto'`, `'pointer'`). |
@@ -149,6 +150,21 @@ An object that defines all cursor types. Each key is a cursor name (any string).
 - **Variable Speed Animation**: `frames` and `duration` are arrays of equal length. Each segment defines a number of frames and the time to play them. The frames are evenly distributed within each segment.
 - **Static Cursor**: If `frames` or `duration` is missing, or if they are invalid (e.g., non-positive numbers, mismatched array lengths), the cursor is treated as static (only the first image is used). A warning will be logged in the console.
 
+### 🎞️ Combining Animations
+
+If your elements already have their own CSS animations (e.g., `animation: spin 2s infinite`), they may override AnimeCursor's cursor animations. To make both play together, enable the `combineAnimations` global option and add a `data-ac-animation` attribute to the element with your animation definition(s). AnimeCursor will then automatically combine them.
+
+Example:
+
+```html
+<button data-ac-animation="mySpin 2s linear infinite">Click Me</button>
+new AnimeCursor({
+    combineAnimations: true,
+    cursors: { ... }
+});
+```
+Multiple animations can be listed, separated by commas.
+
 ### 🧩 Tagging Mechanism
 
 AnimeCursor automatically adds the appropriate cursor style to elements based on `tags` and `data-cursor` attributes:
@@ -202,7 +218,7 @@ AnimeCursor 无需依赖任何框架，适合个人网站、创意作品集以
 ### CDN
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/anime-cursor@v2.0.0/dist/anime-cursor.umd.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/anime-cursor@v2.1.0/dist/anime-cursor.umd.min.js"></script>
 ```
 
 ### npm
@@ -294,6 +310,7 @@ new AnimeCursor({
 
 | 选项               | 类型    | 默认值                                 | 描述                                                         |
 | ------------------ | ------- | -------------------------------------- | ------------------------------------------------------------ |
+| `combineAnimations` | boolean | `false` | 自动将光标动画与元素自身定义的动画（通过 `data-ac-animation`）合并。开启后，任何带有 `data-ac-animation` 属性的元素，其光标动画与用户动画会同时播放，互不覆盖。 |
 | `debug`            | boolean | `false`                                | 启用调试浮层，显示当前光标类型和坐标。                       |
 | `enableTouch`      | boolean | `false`                                | 允许在触屏设备上显示动画光标（默认自动检测并禁用）。         |
 | `fallbackCursor`   | string  | `'auto'`                               | 全局备用光标类型，用于所有动画光标（如 `'auto'`、`'pointer'`）。 |
@@ -318,6 +335,21 @@ new AnimeCursor({
 - **变速动画**：`frames` 和 `duration` 均为等长数组。每个片段指定帧数和该片段的时长，片段内的帧均匀分布。
 - **静态光标**：如果缺少 `frames` 或 `duration`，或者设置无效（如非正数、数组长度不匹配），则光标被视为静态（仅使用第一帧图片）。控制台会输出警告。
 
+### 🎞️ 组合动画
+
+如果元素自身已经拥有 CSS 动画（例如 `animation: spin 2s infinite`），这些动画可能会覆盖 AnimeCursor 的光标动画。要让两者同时播放，请启用 `combineAnimations` 全局选项，并为元素添加 `data-ac-animation` 属性，将你的动画定义写入其中。AnimeCursor 会自动将两者组合。
+
+示例：
+
+```html
+<button data-ac-animation="mySpin 2s linear infinite">点我</button>
+new AnimeCursor({
+    combineAnimations: true,
+    cursors: { ... }
+});
+```
+多个动画可用逗号分隔。
+
 ### 🧩 标记机制
 
 AnimeCursor 会根据 `tags` 和 `data-cursor` 自动应用光标样式：

package/dist/anime-cursor.esm.js

@@ -1,5 +1,5 @@
 // AnimeCursor by github@ShuninYu
-// v2.0.1
+// v2.1.0
 
 let _instance = null;
 
@@ -49,13 +49,16 @@ class AnimeCursor {
         this.options = {
             debug: false,
             enableTouch: false,
-            fallbackCursor: 'auto',           // Fallback cursor type (auto, pointer, etc.)
-            excludeSelectors: 'input, textarea, [contenteditable]', // Exclude native cursor elements
+            fallbackCursor: 'auto',
+            excludeSelectors: 'input, textarea, [contenteditable]',
+            combineAnimations: false,     // 是否自动组合用户动画
             ...options
         };
 
         this.disabled = false;
         this.cursors = this.options.cursors || {};
+        this.cursorAnimationStrings = {};     // 存储每个光标类型的动画字符串
+        this.combinedRules = new Map();       // 存储已生成的组合类名
 
         // 检查是否应启用（触摸设备且未强制启用则禁用）
         if (!this.options.enableTouch && !this.isMouseLikeDevice()) {
@@ -77,12 +80,10 @@ class AnimeCursor {
         _instance = this;
     }
 
-    // 判断是否鼠标设备
     isMouseLikeDevice() {
         return window.matchMedia('(pointer: fine)').matches;
     }
 
-    // 验证配置（修改点：默认光标可选）
     _validateOptions() {
         if (this.disabled) return;
 
@@ -92,12 +93,11 @@ class AnimeCursor {
 
         let hasDefault = false;
         for (const [name, cfg] of Object.entries(this.cursors)) {
-            // 检查必填项
             if (!cfg.image) {
                 throw new Error(`[AnimeCursor] Cursor "${name}" missing required setting: image`);
             }
 
-            // 处理 frames 和 duration 配置
+            // 处理 frames 和 duration
             if (cfg.frames !== undefined && cfg.duration !== undefined) {
                 const framesType = typeof cfg.frames;
                 const durationType = typeof cfg.duration;
@@ -157,11 +157,9 @@ class AnimeCursor {
             }
         }
 
-        // 不再强制要求默认光标
         this.defaultCursorName = hasDefault ? Object.keys(this.cursors).find(name => this.cursors[name].default) : null;
     }
 
-    // 预加载所有图片
     _preloadImages() {
         const images = new Set();
         for (const cfg of Object.values(this.cursors)) {
@@ -183,7 +181,6 @@ class AnimeCursor {
         }
     }
 
-    // 根据配置生成所有帧的 URL 数组
     _getFrameUrls(cfg) {
         let totalFrames = 1;
         if (cfg.frames !== undefined) {
@@ -247,7 +244,7 @@ class AnimeCursor {
         }
     }
 
-    // 注入所有 CSS 规则（修改点：只有存在默认光标才生成 * 规则）
+    // 核心注入样式
     _injectStyles() {
         if (this.disabled) return;
 
@@ -275,6 +272,7 @@ class AnimeCursor {
                 ((Array.isArray(cfg.frames) && Array.isArray(cfg.duration)) ||
                     (typeof cfg.frames === 'number' && typeof cfg.duration === 'number'));
 
+            let cursorAnimation = '';
             if (hasAnimation && frameCount > 1) {
                 const keyframeName = `ac_anim_${name}`;
                 let keyframesCss = `@keyframes ${keyframeName} {\n`;
@@ -290,11 +288,15 @@ class AnimeCursor {
 
                 const totalDuration = Array.isArray(cfg.duration) ? cfg.duration.reduce((a, b) => a + b, 0) : cfg.duration;
                 const animation = `${keyframeName} ${totalDuration}s steps(1) infinite ${cfg.pingpong ? 'alternate' : ''}`;
+                cursorAnimation = animation;
                 css += `${className} { cursor: url("${frameUrls[0]}") ${offset[0]} ${offset[1]}, ${fallback}; animation: ${animation}; }\n`;
             } else {
                 css += `${className} { cursor: url("${frameUrls[0]}") ${offset[0]} ${offset[1]}, ${fallback}; }\n`;
             }
 
+            this.cursorAnimationStrings[name] = cursorAnimation;
+
+            // 标签和 data-cursor 规则
             if (cfg.tags && cfg.tags.length) {
                 const selector = cfg.tags.join(', ');
                 css += `${selector} { ${this._buildCursorCss(name, cfg)} }\n`;
@@ -306,6 +308,33 @@ class AnimeCursor {
             css += `${this.options.excludeSelectors} { cursor: text !important; animation: none !important; }\n`;
         }
 
+        // 自动组合动画（新功能）
+        if (this.options.combineAnimations) {
+            const elements = document.querySelectorAll('[data-ac-animation]');
+            for (const el of elements) {
+                const userAnim = el.getAttribute('data-ac-animation');
+                if (!userAnim) continue;
+
+                // 确定该元素应该使用哪个光标
+                let cursorName = this._getCursorTypeForElement(el);
+                if (!cursorName) continue;
+
+                const cursorAnim = this.cursorAnimationStrings[cursorName];
+                if (!cursorAnim) continue;
+
+                // 生成唯一标识
+                const key = `${cursorName}:${userAnim}`;
+                if (!this.combinedRules.has(key)) {
+                    const hash = this._simpleHash(key);
+                    const combinedClass = `ac-combined-${hash}`;
+                    css += `.${combinedClass} { animation: ${cursorAnim}, ${userAnim}; }\n`;
+                    this.combinedRules.set(key, combinedClass);
+                }
+                const combinedClass = this.combinedRules.get(key);
+                el.classList.add(combinedClass);
+            }
+        }
+
         css += `body.animecursor-disabled * { cursor: auto !important; animation: none !important; }\n`;
 
         style.textContent = css;
@@ -313,6 +342,19 @@ class AnimeCursor {
         this.styleEl = style;
     }
 
+    // 获取元素对应的光标类型（复用 debug 逻辑）
+    _getCursorTypeForElement(el) {
+        if (el.dataset.cursor && this.cursors[el.dataset.cursor]) {
+            return el.dataset.cursor;
+        }
+        for (const [name, cfg] of Object.entries(this.cursors)) {
+            if (cfg.tags && cfg.tags.some(tag => el.matches(tag))) {
+                return name;
+            }
+        }
+        return this.defaultCursorName; // 可能为 null
+    }
+
     _buildKeyframes(cfg, frameUrls) {
         let frames = cfg.frames;
         let durations = cfg.duration;
@@ -364,6 +406,16 @@ class AnimeCursor {
         return css;
     }
 
+    _simpleHash(str) {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash |= 0;
+        }
+        return Math.abs(hash).toString(36);
+    }
+
     _initDebug() {
         const debugDiv = document.createElement('div');
         debugDiv.className = 'animecursor-debug';
@@ -399,7 +451,6 @@ class AnimeCursor {
                     }
                 }
             }
-            // 如果没有匹配到任何自定义光标，且没有默认光标，则显示 "native"
             if (!cursorType && !this.defaultCursorName) {
                 cursorType = 'native';
             } else if (!cursorType && this.defaultCursorName) {
@@ -418,6 +469,7 @@ class AnimeCursor {
     refresh() {
         if (this.disabled) return;
         if (this.styleEl) this.styleEl.remove();
+        this.combinedRules.clear();
         this._injectStyles();
         if (this.options.debug) {
             if (this.debugEl) this.debugEl.remove();

package/dist/anime-cursor.umd.js

@@ -5,7 +5,7 @@
 })(this, (function () { 'use strict';
 
     // AnimeCursor by github@ShuninYu
-    // v2.0.1
+    // v2.1.0
 
     let _instance = null;
 
@@ -55,13 +55,16 @@
             this.options = {
                 debug: false,
                 enableTouch: false,
-                fallbackCursor: 'auto',           // Fallback cursor type (auto, pointer, etc.)
-                excludeSelectors: 'input, textarea, [contenteditable]', // Exclude native cursor elements
+                fallbackCursor: 'auto',
+                excludeSelectors: 'input, textarea, [contenteditable]',
+                combineAnimations: false,     // 是否自动组合用户动画
                 ...options
             };
 
             this.disabled = false;
             this.cursors = this.options.cursors || {};
+            this.cursorAnimationStrings = {};     // 存储每个光标类型的动画字符串
+            this.combinedRules = new Map();       // 存储已生成的组合类名
 
             // 检查是否应启用（触摸设备且未强制启用则禁用）
             if (!this.options.enableTouch && !this.isMouseLikeDevice()) {
@@ -83,12 +86,10 @@
             _instance = this;
         }
 
-        // 判断是否鼠标设备
         isMouseLikeDevice() {
             return window.matchMedia('(pointer: fine)').matches;
         }
 
-        // 验证配置（修改点：默认光标可选）
         _validateOptions() {
             if (this.disabled) return;
 
@@ -98,12 +99,11 @@
 
             let hasDefault = false;
             for (const [name, cfg] of Object.entries(this.cursors)) {
-                // 检查必填项
                 if (!cfg.image) {
                     throw new Error(`[AnimeCursor] Cursor "${name}" missing required setting: image`);
                 }
 
-                // 处理 frames 和 duration 配置
+                // 处理 frames 和 duration
                 if (cfg.frames !== undefined && cfg.duration !== undefined) {
                     const framesType = typeof cfg.frames;
                     const durationType = typeof cfg.duration;
@@ -163,11 +163,9 @@
                 }
             }
 
-            // 不再强制要求默认光标
             this.defaultCursorName = hasDefault ? Object.keys(this.cursors).find(name => this.cursors[name].default) : null;
         }
 
-        // 预加载所有图片
         _preloadImages() {
             const images = new Set();
             for (const cfg of Object.values(this.cursors)) {
@@ -189,7 +187,6 @@
             }
         }
 
-        // 根据配置生成所有帧的 URL 数组
         _getFrameUrls(cfg) {
             let totalFrames = 1;
             if (cfg.frames !== undefined) {
@@ -253,7 +250,7 @@
             }
         }
 
-        // 注入所有 CSS 规则（修改点：只有存在默认光标才生成 * 规则）
+        // 核心注入样式
         _injectStyles() {
             if (this.disabled) return;
 
@@ -281,6 +278,7 @@
                     ((Array.isArray(cfg.frames) && Array.isArray(cfg.duration)) ||
                         (typeof cfg.frames === 'number' && typeof cfg.duration === 'number'));
 
+                let cursorAnimation = '';
                 if (hasAnimation && frameCount > 1) {
                     const keyframeName = `ac_anim_${name}`;
                     let keyframesCss = `@keyframes ${keyframeName} {\n`;
@@ -296,11 +294,15 @@
 
                     const totalDuration = Array.isArray(cfg.duration) ? cfg.duration.reduce((a, b) => a + b, 0) : cfg.duration;
                     const animation = `${keyframeName} ${totalDuration}s steps(1) infinite ${cfg.pingpong ? 'alternate' : ''}`;
+                    cursorAnimation = animation;
                     css += `${className} { cursor: url("${frameUrls[0]}") ${offset[0]} ${offset[1]}, ${fallback}; animation: ${animation}; }\n`;
                 } else {
                     css += `${className} { cursor: url("${frameUrls[0]}") ${offset[0]} ${offset[1]}, ${fallback}; }\n`;
                 }
 
+                this.cursorAnimationStrings[name] = cursorAnimation;
+
+                // 标签和 data-cursor 规则
                 if (cfg.tags && cfg.tags.length) {
                     const selector = cfg.tags.join(', ');
                     css += `${selector} { ${this._buildCursorCss(name, cfg)} }\n`;
@@ -312,6 +314,33 @@
                 css += `${this.options.excludeSelectors} { cursor: text !important; animation: none !important; }\n`;
             }
 
+            // 自动组合动画（新功能）
+            if (this.options.combineAnimations) {
+                const elements = document.querySelectorAll('[data-ac-animation]');
+                for (const el of elements) {
+                    const userAnim = el.getAttribute('data-ac-animation');
+                    if (!userAnim) continue;
+
+                    // 确定该元素应该使用哪个光标
+                    let cursorName = this._getCursorTypeForElement(el);
+                    if (!cursorName) continue;
+
+                    const cursorAnim = this.cursorAnimationStrings[cursorName];
+                    if (!cursorAnim) continue;
+
+                    // 生成唯一标识
+                    const key = `${cursorName}:${userAnim}`;
+                    if (!this.combinedRules.has(key)) {
+                        const hash = this._simpleHash(key);
+                        const combinedClass = `ac-combined-${hash}`;
+                        css += `.${combinedClass} { animation: ${cursorAnim}, ${userAnim}; }\n`;
+                        this.combinedRules.set(key, combinedClass);
+                    }
+                    const combinedClass = this.combinedRules.get(key);
+                    el.classList.add(combinedClass);
+                }
+            }
+
             css += `body.animecursor-disabled * { cursor: auto !important; animation: none !important; }\n`;
 
             style.textContent = css;
@@ -319,6 +348,19 @@
             this.styleEl = style;
         }
 
+        // 获取元素对应的光标类型（复用 debug 逻辑）
+        _getCursorTypeForElement(el) {
+            if (el.dataset.cursor && this.cursors[el.dataset.cursor]) {
+                return el.dataset.cursor;
+            }
+            for (const [name, cfg] of Object.entries(this.cursors)) {
+                if (cfg.tags && cfg.tags.some(tag => el.matches(tag))) {
+                    return name;
+                }
+            }
+            return this.defaultCursorName; // 可能为 null
+        }
+
         _buildKeyframes(cfg, frameUrls) {
             let frames = cfg.frames;
             let durations = cfg.duration;
@@ -370,6 +412,16 @@
             return css;
         }
 
+        _simpleHash(str) {
+            let hash = 0;
+            for (let i = 0; i < str.length; i++) {
+                const char = str.charCodeAt(i);
+                hash = ((hash << 5) - hash) + char;
+                hash |= 0;
+            }
+            return Math.abs(hash).toString(36);
+        }
+
         _initDebug() {
             const debugDiv = document.createElement('div');
             debugDiv.className = 'animecursor-debug';
@@ -405,7 +457,6 @@
                         }
                     }
                 }
-                // 如果没有匹配到任何自定义光标，且没有默认光标，则显示 "native"
                 if (!cursorType && !this.defaultCursorName) {
                     cursorType = 'native';
                 } else if (!cursorType && this.defaultCursorName) {
@@ -424,6 +475,7 @@
         refresh() {
             if (this.disabled) return;
             if (this.styleEl) this.styleEl.remove();
+            this.combinedRules.clear();
             this._injectStyles();
             if (this.options.debug) {
                 if (this.debugEl) this.debugEl.remove();

package/dist/anime-cursor.umd.min.js

@@ -1 +1 @@
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):(e="undefined"!=typeof globalThis?globalThis:e||self).AnimeCursor=t()}(this,function(){"use strict";let e=null;return class{static get instance(){return e}static destroy(){return!!e&&(e.destroy(),!0)}static refresh(){return!!e&&(e.refresh(),!0)}static disable(){return!!e&&(e.disable(),!0)}static enable(){return!!e&&(e.enable(),!0)}constructor(t={}){return e?(console.warn("[AnimeCursor] Instance already exists, returning existing one"),e):(this.options={debug:!1,enableTouch:!1,fallbackCursor:"auto",excludeSelectors:"input, textarea, [contenteditable]",...t},this.disabled=!1,this.cursors=this.options.cursors||{},this.options.enableTouch||this.isMouseLikeDevice()?(this.styleEl=null,this.debugEl=null,this._onMouseMove=null,this._validateOptions(),this._preloadImages(),this._checkDomLoad(),void(e=this)):(this.disabled=!0,void(this.options.debug&&console.warn("[AnimeCursor] Touch device detected, cursor animations disabled"))))}isMouseLikeDevice(){return window.matchMedia("(pointer: fine)").matches}_validateOptions(){if(this.disabled)return;if(!this.cursors||0===Object.keys(this.cursors).length)throw new Error("[AnimeCursor] At least one cursor must be defined");let e=!1;for(const[t,r]of Object.entries(this.cursors)){if(!r.image)throw new Error(`[AnimeCursor] Cursor "${t}" missing required setting: image`);if(void 0!==r.frames&&void 0!==r.duration){if(typeof r.frames!==typeof r.duration)console.warn(`[AnimeCursor] Cursor "${t}" has mismatched types for frames and duration, treating as static cursor`),delete r.frames,delete r.duration;else if(Array.isArray(r.frames)&&Array.isArray(r.duration))if(r.frames.length!==r.duration.length)console.warn(`[AnimeCursor] Cursor "${t}" frames and duration arrays have different lengths, treating as static cursor`),delete r.frames,delete r.duration;else{for(let e of r.frames)if(!Number.isInteger(e)||e<=0){console.warn(`[AnimeCursor] Cursor "${t}" frames array contains invalid value, treating as static cursor`),delete r.frames,delete r.duration;break}for(let e of r.duration)if("number"!=typeof e||e<=0){console.warn(`[AnimeCursor] Cursor "${t}" duration array contains invalid value, treating as static cursor`),delete r.frames,delete r.duration;break}}else"number"==typeof r.frames&&"number"==typeof r.duration?(r.frames<=0||r.duration<=0)&&(console.warn(`[AnimeCursor] Cursor "${t}" frames or duration <= 0, treating as static cursor`),delete r.frames,delete r.duration):(console.warn(`[AnimeCursor] Cursor "${t}" frames and duration must be both numbers or both arrays, treating as static cursor`),delete r.frames,delete r.duration)}else void 0===r.frames&&void 0===r.duration||(console.warn(`[AnimeCursor] Cursor "${t}" has only frames or duration defined, treating as static cursor`),delete r.frames,delete r.duration);if(r.tags&&!Array.isArray(r.tags))throw new Error(`[AnimeCursor] Cursor "${t}" tags must be an array`);if(r.default){if(e)throw new Error("[AnimeCursor] Only one default cursor allowed");e=!0}if(r.offset&&(!Array.isArray(r.offset)||2!==r.offset.length))throw new Error(`[AnimeCursor] Cursor "${t}" offset must be [x, y] array`)}this.defaultCursorName=e?Object.keys(this.cursors).find(e=>this.cursors[e].default):null}_preloadImages(){const e=new Set;for(const t of Object.values(this.cursors)){this._getFrameUrls(t).forEach(t=>e.add(t))}e.forEach(e=>{const t=document.createElement("link");t.rel="preload",t.as="image",t.href=e,e.startsWith("http")&&!e.startsWith(window.location.origin)&&(t.crossOrigin="anonymous"),document.head.appendChild(t)}),this.options.debug&&e.size&&console.info(`[AnimeCursor] Preloaded ${e.size} cursor images`)}_getFrameUrls(e){let t=1;void 0!==e.frames&&(Array.isArray(e.frames)?t=e.frames.reduce((e,t)=>e+t,0):"number"==typeof e.frames&&(t=e.frames));const{image:r}=e;if(1===t)return[r];const{prefix:s,suffix:o,startNum:i,numFormat:n,ext:a}=this._parseImagePattern(r),u=[];for(let e=0;e<t;e++){const t=i+e,r=`${s}${n?this._formatNumber(t,n):t}${o}${a}`;u.push(r)}return u}_parseImagePattern(e){const t=e.match(/\.[^.]+$/),r=t?t[0]:"",s=e.slice(0,-r.length),o=s.match(/(\d+)(?!.*\d)/);if(!o)return{prefix:s+"_",suffix:"",startNum:1,numFormat:null,ext:r};const i=o[0],n=parseInt(i,10),a=i.length;return{prefix:s.slice(0,o.index),suffix:s.slice(o.index+i.length),startNum:n,numFormat:a,ext:r}}_formatNumber(e,t){return String(e).padStart(t,"0")}_checkDomLoad(){const e=()=>{this._injectStyles(),this.options.debug&&this._initDebug(),console.log("[AnimeCursor] Initialization complete")};"loading"===document.readyState?document.addEventListener("DOMContentLoaded",e):e()}_injectStyles(){if(this.disabled)return;const e=document.createElement("style");e.id="animecursor-styles";let t="";if(this.defaultCursorName){const e=this.cursors[this.defaultCursorName];t+=`* { ${this._buildCursorCss(this.defaultCursorName,e)} }\n`}for(const[e,r]of Object.entries(this.cursors)){const s=`.ac-cursor-${e}`,o=r.offset||[0,0],i=r.fallback||this.options.fallbackCursor,n=this._getFrameUrls(r),a=n.length;if(void 0!==r.frames&&void 0!==r.duration&&(Array.isArray(r.frames)&&Array.isArray(r.duration)||"number"==typeof r.frames&&"number"==typeof r.duration)&&a>1){const a=`ac_anim_${e}`;let u=`@keyframes ${a} {\n`;const l=this._buildKeyframes(r,n);for(const e of l){let t=(100*e.percent).toFixed(5);1===e.percent&&(t="100");u+=`  ${t}% { ${`cursor: url("${e.url}") ${o[0]} ${o[1]}, ${i};`} }\n`}u+="}\n",t+=u;const d=`${a} ${Array.isArray(r.duration)?r.duration.reduce((e,t)=>e+t,0):r.duration}s steps(1) infinite ${r.pingpong?"alternate":""}`;t+=`${s} { cursor: url("${n[0]}") ${o[0]} ${o[1]}, ${i}; animation: ${d}; }\n`}else t+=`${s} { cursor: url("${n[0]}") ${o[0]} ${o[1]}, ${i}; }\n`;if(r.tags&&r.tags.length){t+=`${r.tags.join(", ")} { ${this._buildCursorCss(e,r)} }\n`}t+=`[data-cursor="${e}"] { ${this._buildCursorCss(e,r)} }\n`}this.options.excludeSelectors&&(t+=`${this.options.excludeSelectors} { cursor: text !important; animation: none !important; }\n`),t+="body.animecursor-disabled * { cursor: auto !important; animation: none !important; }\n",e.textContent=t,document.head.appendChild(e),this.styleEl=e}_buildKeyframes(e,t){let r=e.frames,s=e.duration;const o=t.length;if("number"==typeof r){const e=s/r;r=new Array(r).fill(1),s=new Array(r.length).fill(e)}const i=[];let n=s.reduce((e,t)=>e+t,0),a=0,u=0;for(let e=0;e<r.length;e++){const o=r[e],l=s[e]/o;for(let e=0;e<o;e++){const e=a/n;i.push({percent:e,url:t[u]}),a+=l,u++}}return i.push({percent:1,url:t[o-1]}),i}_buildCursorCss(e,t){const r=this._getFrameUrls(t),s=t.offset||[0,0],o=t.fallback||this.options.fallbackCursor;let i=`cursor: url("${r[0]}") ${s[0]} ${s[1]}, ${o};`;if(void 0!==t.frames&&void 0!==t.duration&&(Array.isArray(t.frames)&&Array.isArray(t.duration)||"number"==typeof t.frames&&"number"==typeof t.duration)&&r.length>1){i+=` animation: ac_anim_${e} ${Array.isArray(t.duration)?t.duration.reduce((e,t)=>e+t,0):t.duration}s steps(1) infinite ${t.pingpong?"alternate":""};`}return i}_initDebug(){const e=document.createElement("div");e.className="animecursor-debug",e.style.cssText="\n      position: fixed;\n      top: 0;\n      left: 0;\n      background: rgba(0,0,0,0.7);\n      color: #0f0;\n      padding: 4px 8px;\n      font-family: monospace;\n      font-size: 12px;\n      z-index: 2147483647;\n      pointer-events: none;\n      white-space: nowrap;\n    ",document.body.appendChild(e),this.debugEl=e;let t="";this._onMouseMove=r=>{const s=document.elementFromPoint(r.clientX,r.clientY);let o=null;if(s)if(s.dataset.cursor&&this.cursors[s.dataset.cursor])o=s.dataset.cursor;else for(const[e,t]of Object.entries(this.cursors))if(t.tags&&t.tags.some(e=>s.matches(e))){o=e;break}o||this.defaultCursorName?!o&&this.defaultCursorName&&(o=this.defaultCursorName):o="native",o!==t?(t=o,e.textContent=`🎯 ${o} @ (${r.clientX}, ${r.clientY})`):e.textContent=`🎯 ${o} @ (${r.clientX}, ${r.clientY})`},document.addEventListener("mousemove",this._onMouseMove)}refresh(){this.disabled||(this.styleEl&&this.styleEl.remove(),this._injectStyles(),this.options.debug&&(this.debugEl&&this.debugEl.remove(),this._initDebug()),console.log("[AnimeCursor] Refresh complete"))}destroy(){this.disabled||(this.styleEl&&this.styleEl.remove(),this.debugEl&&this.debugEl.remove(),this._onMouseMove&&document.removeEventListener("mousemove",this._onMouseMove),document.body.classList.remove("animecursor-disabled"),e=null,console.log("[AnimeCursor] Destroyed"))}disable(){this.disabled||(this.disabled=!0,document.body.classList.add("animecursor-disabled"),this.options.debug&&console.log("[AnimeCursor] Disabled"))}enable(){this.disabled&&(this.disabled=!1,document.body.classList.remove("animecursor-disabled"),this.options.debug&&console.log("[AnimeCursor] Enabled"))}}});
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):(e="undefined"!=typeof globalThis?globalThis:e||self).AnimeCursor=t()}(this,function(){"use strict";let e=null;return class{static get instance(){return e}static destroy(){return!!e&&(e.destroy(),!0)}static refresh(){return!!e&&(e.refresh(),!0)}static disable(){return!!e&&(e.disable(),!0)}static enable(){return!!e&&(e.enable(),!0)}constructor(t={}){return e?(console.warn("[AnimeCursor] Instance already exists, returning existing one"),e):(this.options={debug:!1,enableTouch:!1,fallbackCursor:"auto",excludeSelectors:"input, textarea, [contenteditable]",combineAnimations:!1,...t},this.disabled=!1,this.cursors=this.options.cursors||{},this.cursorAnimationStrings={},this.combinedRules=new Map,this.options.enableTouch||this.isMouseLikeDevice()?(this.styleEl=null,this.debugEl=null,this._onMouseMove=null,this._validateOptions(),this._preloadImages(),this._checkDomLoad(),void(e=this)):(this.disabled=!0,void(this.options.debug&&console.warn("[AnimeCursor] Touch device detected, cursor animations disabled"))))}isMouseLikeDevice(){return window.matchMedia("(pointer: fine)").matches}_validateOptions(){if(this.disabled)return;if(!this.cursors||0===Object.keys(this.cursors).length)throw new Error("[AnimeCursor] At least one cursor must be defined");let e=!1;for(const[t,r]of Object.entries(this.cursors)){if(!r.image)throw new Error(`[AnimeCursor] Cursor "${t}" missing required setting: image`);if(void 0!==r.frames&&void 0!==r.duration){if(typeof r.frames!==typeof r.duration)console.warn(`[AnimeCursor] Cursor "${t}" has mismatched types for frames and duration, treating as static cursor`),delete r.frames,delete r.duration;else if(Array.isArray(r.frames)&&Array.isArray(r.duration))if(r.frames.length!==r.duration.length)console.warn(`[AnimeCursor] Cursor "${t}" frames and duration arrays have different lengths, treating as static cursor`),delete r.frames,delete r.duration;else{for(let e of r.frames)if(!Number.isInteger(e)||e<=0){console.warn(`[AnimeCursor] Cursor "${t}" frames array contains invalid value, treating as static cursor`),delete r.frames,delete r.duration;break}for(let e of r.duration)if("number"!=typeof e||e<=0){console.warn(`[AnimeCursor] Cursor "${t}" duration array contains invalid value, treating as static cursor`),delete r.frames,delete r.duration;break}}else"number"==typeof r.frames&&"number"==typeof r.duration?(r.frames<=0||r.duration<=0)&&(console.warn(`[AnimeCursor] Cursor "${t}" frames or duration <= 0, treating as static cursor`),delete r.frames,delete r.duration):(console.warn(`[AnimeCursor] Cursor "${t}" frames and duration must be both numbers or both arrays, treating as static cursor`),delete r.frames,delete r.duration)}else void 0===r.frames&&void 0===r.duration||(console.warn(`[AnimeCursor] Cursor "${t}" has only frames or duration defined, treating as static cursor`),delete r.frames,delete r.duration);if(r.tags&&!Array.isArray(r.tags))throw new Error(`[AnimeCursor] Cursor "${t}" tags must be an array`);if(r.default){if(e)throw new Error("[AnimeCursor] Only one default cursor allowed");e=!0}if(r.offset&&(!Array.isArray(r.offset)||2!==r.offset.length))throw new Error(`[AnimeCursor] Cursor "${t}" offset must be [x, y] array`)}this.defaultCursorName=e?Object.keys(this.cursors).find(e=>this.cursors[e].default):null}_preloadImages(){const e=new Set;for(const t of Object.values(this.cursors)){this._getFrameUrls(t).forEach(t=>e.add(t))}e.forEach(e=>{const t=document.createElement("link");t.rel="preload",t.as="image",t.href=e,e.startsWith("http")&&!e.startsWith(window.location.origin)&&(t.crossOrigin="anonymous"),document.head.appendChild(t)}),this.options.debug&&e.size&&console.info(`[AnimeCursor] Preloaded ${e.size} cursor images`)}_getFrameUrls(e){let t=1;void 0!==e.frames&&(Array.isArray(e.frames)?t=e.frames.reduce((e,t)=>e+t,0):"number"==typeof e.frames&&(t=e.frames));const{image:r}=e;if(1===t)return[r];const{prefix:s,suffix:o,startNum:i,numFormat:n,ext:a}=this._parseImagePattern(r),u=[];for(let e=0;e<t;e++){const t=i+e,r=`${s}${n?this._formatNumber(t,n):t}${o}${a}`;u.push(r)}return u}_parseImagePattern(e){const t=e.match(/\.[^.]+$/),r=t?t[0]:"",s=e.slice(0,-r.length),o=s.match(/(\d+)(?!.*\d)/);if(!o)return{prefix:s+"_",suffix:"",startNum:1,numFormat:null,ext:r};const i=o[0],n=parseInt(i,10),a=i.length;return{prefix:s.slice(0,o.index),suffix:s.slice(o.index+i.length),startNum:n,numFormat:a,ext:r}}_formatNumber(e,t){return String(e).padStart(t,"0")}_checkDomLoad(){const e=()=>{this._injectStyles(),this.options.debug&&this._initDebug(),console.log("[AnimeCursor] Initialization complete")};"loading"===document.readyState?document.addEventListener("DOMContentLoaded",e):e()}_injectStyles(){if(this.disabled)return;const e=document.createElement("style");e.id="animecursor-styles";let t="";if(this.defaultCursorName){const e=this.cursors[this.defaultCursorName];t+=`* { ${this._buildCursorCss(this.defaultCursorName,e)} }\n`}for(const[e,r]of Object.entries(this.cursors)){const s=`.ac-cursor-${e}`,o=r.offset||[0,0],i=r.fallback||this.options.fallbackCursor,n=this._getFrameUrls(r),a=n.length;let u="";if(void 0!==r.frames&&void 0!==r.duration&&(Array.isArray(r.frames)&&Array.isArray(r.duration)||"number"==typeof r.frames&&"number"==typeof r.duration)&&a>1){const a=`ac_anim_${e}`;let l=`@keyframes ${a} {\n`;const d=this._buildKeyframes(r,n);for(const e of d){let t=(100*e.percent).toFixed(5);1===e.percent&&(t="100");l+=`  ${t}% { ${`cursor: url("${e.url}") ${o[0]} ${o[1]}, ${i};`} }\n`}l+="}\n",t+=l;const c=`${a} ${Array.isArray(r.duration)?r.duration.reduce((e,t)=>e+t,0):r.duration}s steps(1) infinite ${r.pingpong?"alternate":""}`;u=c,t+=`${s} { cursor: url("${n[0]}") ${o[0]} ${o[1]}, ${i}; animation: ${c}; }\n`}else t+=`${s} { cursor: url("${n[0]}") ${o[0]} ${o[1]}, ${i}; }\n`;if(this.cursorAnimationStrings[e]=u,r.tags&&r.tags.length){t+=`${r.tags.join(", ")} { ${this._buildCursorCss(e,r)} }\n`}t+=`[data-cursor="${e}"] { ${this._buildCursorCss(e,r)} }\n`}if(this.options.excludeSelectors&&(t+=`${this.options.excludeSelectors} { cursor: text !important; animation: none !important; }\n`),this.options.combineAnimations){const e=document.querySelectorAll("[data-ac-animation]");for(const r of e){const e=r.getAttribute("data-ac-animation");if(!e)continue;let s=this._getCursorTypeForElement(r);if(!s)continue;const o=this.cursorAnimationStrings[s];if(!o)continue;const i=`${s}:${e}`;if(!this.combinedRules.has(i)){const r=`ac-combined-${this._simpleHash(i)}`;t+=`.${r} { animation: ${o}, ${e}; }\n`,this.combinedRules.set(i,r)}const n=this.combinedRules.get(i);r.classList.add(n)}}t+="body.animecursor-disabled * { cursor: auto !important; animation: none !important; }\n",e.textContent=t,document.head.appendChild(e),this.styleEl=e}_getCursorTypeForElement(e){if(e.dataset.cursor&&this.cursors[e.dataset.cursor])return e.dataset.cursor;for(const[t,r]of Object.entries(this.cursors))if(r.tags&&r.tags.some(t=>e.matches(t)))return t;return this.defaultCursorName}_buildKeyframes(e,t){let r=e.frames,s=e.duration;const o=t.length;if("number"==typeof r){const e=s/r;r=new Array(r).fill(1),s=new Array(r.length).fill(e)}const i=[];let n=s.reduce((e,t)=>e+t,0),a=0,u=0;for(let e=0;e<r.length;e++){const o=r[e],l=s[e]/o;for(let e=0;e<o;e++){const e=a/n;i.push({percent:e,url:t[u]}),a+=l,u++}}return i.push({percent:1,url:t[o-1]}),i}_buildCursorCss(e,t){const r=this._getFrameUrls(t),s=t.offset||[0,0],o=t.fallback||this.options.fallbackCursor;let i=`cursor: url("${r[0]}") ${s[0]} ${s[1]}, ${o};`;if(void 0!==t.frames&&void 0!==t.duration&&(Array.isArray(t.frames)&&Array.isArray(t.duration)||"number"==typeof t.frames&&"number"==typeof t.duration)&&r.length>1){i+=` animation: ac_anim_${e} ${Array.isArray(t.duration)?t.duration.reduce((e,t)=>e+t,0):t.duration}s steps(1) infinite ${t.pingpong?"alternate":""};`}return i}_simpleHash(e){let t=0;for(let r=0;r<e.length;r++){t=(t<<5)-t+e.charCodeAt(r),t|=0}return Math.abs(t).toString(36)}_initDebug(){const e=document.createElement("div");e.className="animecursor-debug",e.style.cssText="\n      position: fixed;\n      top: 0;\n      left: 0;\n      background: rgba(0,0,0,0.7);\n      color: #0f0;\n      padding: 4px 8px;\n      font-family: monospace;\n      font-size: 12px;\n      z-index: 2147483647;\n      pointer-events: none;\n      white-space: nowrap;\n    ",document.body.appendChild(e),this.debugEl=e;let t="";this._onMouseMove=r=>{const s=document.elementFromPoint(r.clientX,r.clientY);let o=null;if(s)if(s.dataset.cursor&&this.cursors[s.dataset.cursor])o=s.dataset.cursor;else for(const[e,t]of Object.entries(this.cursors))if(t.tags&&t.tags.some(e=>s.matches(e))){o=e;break}o||this.defaultCursorName?!o&&this.defaultCursorName&&(o=this.defaultCursorName):o="native",o!==t?(t=o,e.textContent=`🎯 ${o} @ (${r.clientX}, ${r.clientY})`):e.textContent=`🎯 ${o} @ (${r.clientX}, ${r.clientY})`},document.addEventListener("mousemove",this._onMouseMove)}refresh(){this.disabled||(this.styleEl&&this.styleEl.remove(),this.combinedRules.clear(),this._injectStyles(),this.options.debug&&(this.debugEl&&this.debugEl.remove(),this._initDebug()),console.log("[AnimeCursor] Refresh complete"))}destroy(){this.disabled||(this.styleEl&&this.styleEl.remove(),this.debugEl&&this.debugEl.remove(),this._onMouseMove&&document.removeEventListener("mousemove",this._onMouseMove),document.body.classList.remove("animecursor-disabled"),e=null,console.log("[AnimeCursor] Destroyed"))}disable(){this.disabled||(this.disabled=!0,document.body.classList.add("animecursor-disabled"),this.options.debug&&console.log("[AnimeCursor] Disabled"))}enable(){this.disabled&&(this.disabled=!1,document.body.classList.remove("animecursor-disabled"),this.options.debug&&console.log("[AnimeCursor] Enabled"))}}});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "anime-cursor",
-    "version": "2.0.1",
+    "version": "2.1.0",
     "description": "A lightweight JavaScript library for animated custom cursors",
     "main": "dist/anime-cursor.umd.js",
     "module": "dist/anime-cursor.esm.js",