anime-cursor 2.0.0 → 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.0
+// 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,14 +93,12 @@ 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;
                 if (framesType !== durationType) {
@@ -107,13 +106,11 @@ class AnimeCursor {
                     delete cfg.frames;
                     delete cfg.duration;
                 } else if (Array.isArray(cfg.frames) && Array.isArray(cfg.duration)) {
-                    // 数组形式：必须长度相等
                     if (cfg.frames.length !== cfg.duration.length) {
                         console.warn(`[AnimeCursor] Cursor "${name}" frames and duration arrays have different lengths, treating as static cursor`);
                         delete cfg.frames;
                         delete cfg.duration;
                     } else {
-                        // 验证数组元素为正整数/正数
                         for (let f of cfg.frames) {
                             if (!Number.isInteger(f) || f <= 0) {
                                 console.warn(`[AnimeCursor] Cursor "${name}" frames array contains invalid value, treating as static cursor`);
@@ -132,48 +129,37 @@ class AnimeCursor {
                         }
                     }
                 } else if (typeof cfg.frames === 'number' && typeof cfg.duration === 'number') {
-                    // 数字形式：合法
                     if (cfg.frames <= 0 || cfg.duration <= 0) {
                         console.warn(`[AnimeCursor] Cursor "${name}" frames or duration <= 0, treating as static cursor`);
                         delete cfg.frames;
                         delete cfg.duration;
                     }
                 } else {
-                    // 其他情况（如一个数字一个数组）
                     console.warn(`[AnimeCursor] Cursor "${name}" frames and duration must be both numbers or both arrays, treating as static cursor`);
                     delete cfg.frames;
                     delete cfg.duration;
                 }
             } else if (cfg.frames !== undefined || cfg.duration !== undefined) {
-                // 只设置了一个
                 console.warn(`[AnimeCursor] Cursor "${name}" has only frames or duration defined, treating as static cursor`);
                 delete cfg.frames;
                 delete cfg.duration;
             }
 
-            // 检查 tags
             if (cfg.tags && !Array.isArray(cfg.tags)) {
                 throw new Error(`[AnimeCursor] Cursor "${name}" tags must be an array`);
             }
-            // 检查 default
             if (cfg.default) {
                 if (hasDefault) throw new Error('[AnimeCursor] Only one default cursor allowed');
                 hasDefault = true;
             }
-            // 检查 offset
             if (cfg.offset && (!Array.isArray(cfg.offset) || cfg.offset.length !== 2)) {
                 throw new Error(`[AnimeCursor] Cursor "${name}" offset must be [x, y] array`);
             }
         }
 
-        if (!hasDefault) {
-            throw new Error('[AnimeCursor] A default cursor (default: true) must be defined');
-        }
-
-        this.defaultCursorName = Object.keys(this.cursors).find(name => this.cursors[name].default);
+        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)) {
@@ -195,10 +181,8 @@ class AnimeCursor {
         }
     }
 
-    // 根据配置生成所有帧的 URL 数组
     _getFrameUrls(cfg) {
-        // 确定总帧数
-        let totalFrames = 1; // 默认单帧
+        let totalFrames = 1;
         if (cfg.frames !== undefined) {
             if (Array.isArray(cfg.frames)) {
                 totalFrames = cfg.frames.reduce((a, b) => a + b, 0);
@@ -210,7 +194,6 @@ class AnimeCursor {
         const { image } = cfg;
         if (totalFrames === 1) return [image];
 
-        // 解析文件名模板
         const { prefix, suffix, startNum, numFormat, ext } = this._parseImagePattern(image);
         const urls = [];
         for (let i = 0; i < totalFrames; i++) {
@@ -222,15 +205,12 @@ class AnimeCursor {
         return urls;
     }
 
-    // 解析图片路径，提取数字模板
     _parseImagePattern(path) {
-        // 匹配最后一个数字部分（包括可能的前后括号/下划线等）
         const extMatch = path.match(/\.[^.]+$/);
         const ext = extMatch ? extMatch[0] : '';
         const base = path.slice(0, -ext.length);
-        const numMatch = base.match(/(\d+)(?!.*\d)/); // 最后一个数字串
+        const numMatch = base.match(/(\d+)(?!.*\d)/);
         if (!numMatch) {
-            // 无数字，则默认在扩展名前加 _%d
             return {
                 prefix: base + '_',
                 suffix: '',
@@ -241,10 +221,9 @@ class AnimeCursor {
         }
         const numStr = numMatch[0];
         const startNum = parseInt(numStr, 10);
-        const numFormat = numStr.length; // 数字位数，用于格式化
+        const numFormat = numStr.length;
         const prefix = base.slice(0, numMatch.index);
         const suffix = base.slice(numMatch.index + numStr.length);
-        // 判断是否有包裹字符（如括号）
         return { prefix, suffix, startNum, numFormat, ext };
     }
 
@@ -252,7 +231,6 @@ class AnimeCursor {
         return String(num).padStart(width, '0');
     }
 
-    // 等待 DOM 加载
     _checkDomLoad() {
         const init = () => {
             this._injectStyles();
@@ -266,7 +244,7 @@ class AnimeCursor {
         }
     }
 
-    // 注入所有 CSS 规则
+    // 核心注入样式
     _injectStyles() {
         if (this.disabled) return;
 
@@ -274,11 +252,12 @@ class AnimeCursor {
         style.id = 'animecursor-styles';
         let css = '';
 
-        // 全局规则：隐藏原生光标并应用默认动画光标
-        // 注意：默认光标通过 * 应用，但会被后面更具体的规则覆盖
-        const defaultCfg = this.cursors[this.defaultCursorName];
-        const defaultCursorDef = this._buildCursorCss(this.defaultCursorName, defaultCfg);
-        css += `* { ${defaultCursorDef} }\n`;
+        // 如果有默认光标，生成全局规则
+        if (this.defaultCursorName) {
+            const defaultCfg = this.cursors[this.defaultCursorName];
+            const defaultCursorDef = this._buildCursorCss(this.defaultCursorName, defaultCfg);
+            css += `* { ${defaultCursorDef} }\n`;
+        }
 
         // 为每个光标生成独立的类和关键帧
         for (const [name, cfg] of Object.entries(this.cursors)) {
@@ -286,20 +265,17 @@ class AnimeCursor {
             const offset = cfg.offset || [0, 0];
             const fallback = cfg.fallback || this.options.fallbackCursor;
 
-            // 获取所有帧 URL
             const frameUrls = this._getFrameUrls(cfg);
             const frameCount = frameUrls.length;
 
-            // 判断是否有动画（有 frames 和 duration 且都有效）
             const hasAnimation = cfg.frames !== undefined && cfg.duration !== undefined &&
                 ((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`;
-
-                // 构建关键帧列表（百分比和对应图片）
                 const keyframes = this._buildKeyframes(cfg, frameUrls);
                 for (const kf of keyframes) {
                     let percent = (kf.percent * 100).toFixed(5);
@@ -310,30 +286,55 @@ class AnimeCursor {
                 keyframesCss += `}\n`;
                 css += keyframesCss;
 
-                // 应用动画的类
                 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`;
             }
 
-            // 为 tags 和 data-cursor 生成选择器规则
+            this.cursorAnimationStrings[name] = cursorAnimation;
+
+            // 标签和 data-cursor 规则
             if (cfg.tags && cfg.tags.length) {
                 const selector = cfg.tags.join(', ');
                 css += `${selector} { ${this._buildCursorCss(name, cfg)} }\n`;
             }
-            // 支持 data-cursor 属性
             css += `[data-cursor="${name}"] { ${this._buildCursorCss(name, cfg)} }\n`;
         }
 
-        // 排除原生文本光标元素
         if (this.options.excludeSelectors) {
             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;
@@ -341,20 +342,29 @@ class AnimeCursor {
         this.styleEl = style;
     }
 
-    // 根据 frames/duration 配置构建关键帧列表（百分比和对应图片 URL）
+    // 获取元素对应的光标类型（复用 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;
         const frameCount = frameUrls.length;
 
-        // 统一转换为数组形式，方便处理
         if (typeof frames === 'number') {
-            // 均匀分配
             const perFrameDuration = durations / frames;
             frames = new Array(frames).fill(1);
             durations = new Array(frames.length).fill(perFrameDuration);
         }
-        // 此时 frames 和 durations 都是等长数组
 
         const keyframes = [];
         let totalTime = durations.reduce((a, b) => a + b, 0);
@@ -363,7 +373,7 @@ class AnimeCursor {
         for (let seg = 0; seg < frames.length; seg++) {
             const segFrames = frames[seg];
             const segDuration = durations[seg];
-            const stepTime = segDuration / segFrames; // 每帧时长
+            const stepTime = segDuration / segFrames;
             for (let f = 0; f < segFrames; f++) {
                 const percent = currentTime / totalTime;
                 keyframes.push({
@@ -374,7 +384,6 @@ class AnimeCursor {
                 frameIdx++;
             }
         }
-        // 确保最后一帧在 100%
         keyframes.push({
             percent: 1.0,
             url: frameUrls[frameCount - 1]
@@ -382,13 +391,11 @@ class AnimeCursor {
         return keyframes;
     }
 
-    // 生成单个光标的 CSS 声明（不包含动画，用于选择器规则）
     _buildCursorCss(name, cfg) {
         const frameUrls = this._getFrameUrls(cfg);
         const offset = cfg.offset || [0, 0];
         const fallback = cfg.fallback || this.options.fallbackCursor;
         let css = `cursor: url("${frameUrls[0]}") ${offset[0]} ${offset[1]}, ${fallback};`;
-        // 如果有动画，附加动画属性
         const hasAnimation = cfg.frames !== undefined && cfg.duration !== undefined &&
             ((Array.isArray(cfg.frames) && Array.isArray(cfg.duration)) ||
                 (typeof cfg.frames === 'number' && typeof cfg.duration === 'number'));
@@ -399,7 +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';
@@ -422,12 +438,11 @@ class AnimeCursor {
         let lastCursor = '';
         this._onMouseMove = (e) => {
             const target = document.elementFromPoint(e.clientX, e.clientY);
-            let cursorType = this.defaultCursorName;
+            let cursorType = null;
             if (target) {
                 if (target.dataset.cursor && this.cursors[target.dataset.cursor]) {
                     cursorType = target.dataset.cursor;
                 } else {
-                    // 检查匹配 tags
                     for (const [name, cfg] of Object.entries(this.cursors)) {
                         if (cfg.tags && cfg.tags.some(tag => target.matches(tag))) {
                             cursorType = name;
@@ -436,6 +451,11 @@ class AnimeCursor {
                     }
                 }
             }
+            if (!cursorType && !this.defaultCursorName) {
+                cursorType = 'native';
+            } else if (!cursorType && this.defaultCursorName) {
+                cursorType = this.defaultCursorName;
+            }
             if (cursorType !== lastCursor) {
                 lastCursor = cursorType;
                 debugDiv.textContent = `🎯 ${cursorType} @ (${e.clientX}, ${e.clientY})`;
@@ -446,10 +466,10 @@ class AnimeCursor {
         document.addEventListener('mousemove', this._onMouseMove);
     }
 
-    // 刷新：重新注入样式（用于动态添加新光标等场景）
     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();
@@ -458,7 +478,6 @@ class AnimeCursor {
         console.log('[AnimeCursor] Refresh complete');
     }
 
-    // 销毁实例
     destroy() {
         if (this.disabled) return;
         if (this.styleEl) this.styleEl.remove();
@@ -466,13 +485,11 @@ class AnimeCursor {
         if (this._onMouseMove) {
             document.removeEventListener('mousemove', this._onMouseMove);
         }
-        // 清除全局禁用类
         document.body.classList.remove('animecursor-disabled');
         _instance = null;
         console.log('[AnimeCursor] Destroyed');
     }
 
-    // 禁用光标动画
     disable() {
         if (this.disabled) return;
         this.disabled = true;
@@ -480,7 +497,6 @@ class AnimeCursor {
         if (this.options.debug) console.log('[AnimeCursor] Disabled');
     }
 
-    // 启用光标动画
     enable() {
         if (!this.disabled) return;
         this.disabled = false;

package/dist/anime-cursor.umd.js

@@ -5,7 +5,7 @@
 })(this, (function () { 'use strict';
 
     // AnimeCursor by github@ShuninYu
-    // v2.0.0
+    // 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,14 +99,12 @@
 
             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;
                     if (framesType !== durationType) {
@@ -113,13 +112,11 @@
                         delete cfg.frames;
                         delete cfg.duration;
                     } else if (Array.isArray(cfg.frames) && Array.isArray(cfg.duration)) {
-                        // 数组形式：必须长度相等
                         if (cfg.frames.length !== cfg.duration.length) {
                             console.warn(`[AnimeCursor] Cursor "${name}" frames and duration arrays have different lengths, treating as static cursor`);
                             delete cfg.frames;
                             delete cfg.duration;
                         } else {
-                            // 验证数组元素为正整数/正数
                             for (let f of cfg.frames) {
                                 if (!Number.isInteger(f) || f <= 0) {
                                     console.warn(`[AnimeCursor] Cursor "${name}" frames array contains invalid value, treating as static cursor`);
@@ -138,48 +135,37 @@
                             }
                         }
                     } else if (typeof cfg.frames === 'number' && typeof cfg.duration === 'number') {
-                        // 数字形式：合法
                         if (cfg.frames <= 0 || cfg.duration <= 0) {
                             console.warn(`[AnimeCursor] Cursor "${name}" frames or duration <= 0, treating as static cursor`);
                             delete cfg.frames;
                             delete cfg.duration;
                         }
                     } else {
-                        // 其他情况（如一个数字一个数组）
                         console.warn(`[AnimeCursor] Cursor "${name}" frames and duration must be both numbers or both arrays, treating as static cursor`);
                         delete cfg.frames;
                         delete cfg.duration;
                     }
                 } else if (cfg.frames !== undefined || cfg.duration !== undefined) {
-                    // 只设置了一个
                     console.warn(`[AnimeCursor] Cursor "${name}" has only frames or duration defined, treating as static cursor`);
                     delete cfg.frames;
                     delete cfg.duration;
                 }
 
-                // 检查 tags
                 if (cfg.tags && !Array.isArray(cfg.tags)) {
                     throw new Error(`[AnimeCursor] Cursor "${name}" tags must be an array`);
                 }
-                // 检查 default
                 if (cfg.default) {
                     if (hasDefault) throw new Error('[AnimeCursor] Only one default cursor allowed');
                     hasDefault = true;
                 }
-                // 检查 offset
                 if (cfg.offset && (!Array.isArray(cfg.offset) || cfg.offset.length !== 2)) {
                     throw new Error(`[AnimeCursor] Cursor "${name}" offset must be [x, y] array`);
                 }
             }
 
-            if (!hasDefault) {
-                throw new Error('[AnimeCursor] A default cursor (default: true) must be defined');
-            }
-
-            this.defaultCursorName = Object.keys(this.cursors).find(name => this.cursors[name].default);
+            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)) {
@@ -201,10 +187,8 @@
             }
         }
 
-        // 根据配置生成所有帧的 URL 数组
         _getFrameUrls(cfg) {
-            // 确定总帧数
-            let totalFrames = 1; // 默认单帧
+            let totalFrames = 1;
             if (cfg.frames !== undefined) {
                 if (Array.isArray(cfg.frames)) {
                     totalFrames = cfg.frames.reduce((a, b) => a + b, 0);
@@ -216,7 +200,6 @@
             const { image } = cfg;
             if (totalFrames === 1) return [image];
 
-            // 解析文件名模板
             const { prefix, suffix, startNum, numFormat, ext } = this._parseImagePattern(image);
             const urls = [];
             for (let i = 0; i < totalFrames; i++) {
@@ -228,15 +211,12 @@
             return urls;
         }
 
-        // 解析图片路径，提取数字模板
         _parseImagePattern(path) {
-            // 匹配最后一个数字部分（包括可能的前后括号/下划线等）
             const extMatch = path.match(/\.[^.]+$/);
             const ext = extMatch ? extMatch[0] : '';
             const base = path.slice(0, -ext.length);
-            const numMatch = base.match(/(\d+)(?!.*\d)/); // 最后一个数字串
+            const numMatch = base.match(/(\d+)(?!.*\d)/);
             if (!numMatch) {
-                // 无数字，则默认在扩展名前加 _%d
                 return {
                     prefix: base + '_',
                     suffix: '',
@@ -247,10 +227,9 @@
             }
             const numStr = numMatch[0];
             const startNum = parseInt(numStr, 10);
-            const numFormat = numStr.length; // 数字位数，用于格式化
+            const numFormat = numStr.length;
             const prefix = base.slice(0, numMatch.index);
             const suffix = base.slice(numMatch.index + numStr.length);
-            // 判断是否有包裹字符（如括号）
             return { prefix, suffix, startNum, numFormat, ext };
         }
 
@@ -258,7 +237,6 @@
             return String(num).padStart(width, '0');
         }
 
-        // 等待 DOM 加载
         _checkDomLoad() {
             const init = () => {
                 this._injectStyles();
@@ -272,7 +250,7 @@
             }
         }
 
-        // 注入所有 CSS 规则
+        // 核心注入样式
         _injectStyles() {
             if (this.disabled) return;
 
@@ -280,11 +258,12 @@
             style.id = 'animecursor-styles';
             let css = '';
 
-            // 全局规则：隐藏原生光标并应用默认动画光标
-            // 注意：默认光标通过 * 应用，但会被后面更具体的规则覆盖
-            const defaultCfg = this.cursors[this.defaultCursorName];
-            const defaultCursorDef = this._buildCursorCss(this.defaultCursorName, defaultCfg);
-            css += `* { ${defaultCursorDef} }\n`;
+            // 如果有默认光标，生成全局规则
+            if (this.defaultCursorName) {
+                const defaultCfg = this.cursors[this.defaultCursorName];
+                const defaultCursorDef = this._buildCursorCss(this.defaultCursorName, defaultCfg);
+                css += `* { ${defaultCursorDef} }\n`;
+            }
 
             // 为每个光标生成独立的类和关键帧
             for (const [name, cfg] of Object.entries(this.cursors)) {
@@ -292,20 +271,17 @@
                 const offset = cfg.offset || [0, 0];
                 const fallback = cfg.fallback || this.options.fallbackCursor;
 
-                // 获取所有帧 URL
                 const frameUrls = this._getFrameUrls(cfg);
                 const frameCount = frameUrls.length;
 
-                // 判断是否有动画（有 frames 和 duration 且都有效）
                 const hasAnimation = cfg.frames !== undefined && cfg.duration !== undefined &&
                     ((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`;
-
-                    // 构建关键帧列表（百分比和对应图片）
                     const keyframes = this._buildKeyframes(cfg, frameUrls);
                     for (const kf of keyframes) {
                         let percent = (kf.percent * 100).toFixed(5);
@@ -316,30 +292,55 @@
                     keyframesCss += `}\n`;
                     css += keyframesCss;
 
-                    // 应用动画的类
                     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`;
                 }
 
-                // 为 tags 和 data-cursor 生成选择器规则
+                this.cursorAnimationStrings[name] = cursorAnimation;
+
+                // 标签和 data-cursor 规则
                 if (cfg.tags && cfg.tags.length) {
                     const selector = cfg.tags.join(', ');
                     css += `${selector} { ${this._buildCursorCss(name, cfg)} }\n`;
                 }
-                // 支持 data-cursor 属性
                 css += `[data-cursor="${name}"] { ${this._buildCursorCss(name, cfg)} }\n`;
             }
 
-            // 排除原生文本光标元素
             if (this.options.excludeSelectors) {
                 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;
@@ -347,20 +348,29 @@
             this.styleEl = style;
         }
 
-        // 根据 frames/duration 配置构建关键帧列表（百分比和对应图片 URL）
+        // 获取元素对应的光标类型（复用 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;
             const frameCount = frameUrls.length;
 
-            // 统一转换为数组形式，方便处理
             if (typeof frames === 'number') {
-                // 均匀分配
                 const perFrameDuration = durations / frames;
                 frames = new Array(frames).fill(1);
                 durations = new Array(frames.length).fill(perFrameDuration);
             }
-            // 此时 frames 和 durations 都是等长数组
 
             const keyframes = [];
             let totalTime = durations.reduce((a, b) => a + b, 0);
@@ -369,7 +379,7 @@
             for (let seg = 0; seg < frames.length; seg++) {
                 const segFrames = frames[seg];
                 const segDuration = durations[seg];
-                const stepTime = segDuration / segFrames; // 每帧时长
+                const stepTime = segDuration / segFrames;
                 for (let f = 0; f < segFrames; f++) {
                     const percent = currentTime / totalTime;
                     keyframes.push({
@@ -380,7 +390,6 @@
                     frameIdx++;
                 }
             }
-            // 确保最后一帧在 100%
             keyframes.push({
                 percent: 1.0,
                 url: frameUrls[frameCount - 1]
@@ -388,13 +397,11 @@
             return keyframes;
         }
 
-        // 生成单个光标的 CSS 声明（不包含动画，用于选择器规则）
         _buildCursorCss(name, cfg) {
             const frameUrls = this._getFrameUrls(cfg);
             const offset = cfg.offset || [0, 0];
             const fallback = cfg.fallback || this.options.fallbackCursor;
             let css = `cursor: url("${frameUrls[0]}") ${offset[0]} ${offset[1]}, ${fallback};`;
-            // 如果有动画，附加动画属性
             const hasAnimation = cfg.frames !== undefined && cfg.duration !== undefined &&
                 ((Array.isArray(cfg.frames) && Array.isArray(cfg.duration)) ||
                     (typeof cfg.frames === 'number' && typeof cfg.duration === 'number'));
@@ -405,7 +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';
@@ -428,12 +444,11 @@
             let lastCursor = '';
             this._onMouseMove = (e) => {
                 const target = document.elementFromPoint(e.clientX, e.clientY);
-                let cursorType = this.defaultCursorName;
+                let cursorType = null;
                 if (target) {
                     if (target.dataset.cursor && this.cursors[target.dataset.cursor]) {
                         cursorType = target.dataset.cursor;
                     } else {
-                        // 检查匹配 tags
                         for (const [name, cfg] of Object.entries(this.cursors)) {
                             if (cfg.tags && cfg.tags.some(tag => target.matches(tag))) {
                                 cursorType = name;
@@ -442,6 +457,11 @@
                         }
                     }
                 }
+                if (!cursorType && !this.defaultCursorName) {
+                    cursorType = 'native';
+                } else if (!cursorType && this.defaultCursorName) {
+                    cursorType = this.defaultCursorName;
+                }
                 if (cursorType !== lastCursor) {
                     lastCursor = cursorType;
                     debugDiv.textContent = `🎯 ${cursorType} @ (${e.clientX}, ${e.clientY})`;
@@ -452,10 +472,10 @@
             document.addEventListener('mousemove', this._onMouseMove);
         }
 
-        // 刷新：重新注入样式（用于动态添加新光标等场景）
         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();
@@ -464,7 +484,6 @@
             console.log('[AnimeCursor] Refresh complete');
         }
 
-        // 销毁实例
         destroy() {
             if (this.disabled) return;
             if (this.styleEl) this.styleEl.remove();
@@ -472,13 +491,11 @@
             if (this._onMouseMove) {
                 document.removeEventListener('mousemove', this._onMouseMove);
             }
-            // 清除全局禁用类
             document.body.classList.remove('animecursor-disabled');
             _instance = null;
             console.log('[AnimeCursor] Destroyed');
         }
 
-        // 禁用光标动画
         disable() {
             if (this.disabled) return;
             this.disabled = true;
@@ -486,7 +503,6 @@
             if (this.options.debug) console.log('[AnimeCursor] Disabled');
         }
 
-        // 启用光标动画
         enable() {
             if (!this.disabled) return;
             this.disabled = false;

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`)}if(!e)throw new Error("[AnimeCursor] A default cursor (default: true) must be defined");this.defaultCursorName=Object.keys(this.cursors).find(e=>this.cursors[e].default)}_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:n,numFormat:i,ext:a}=this._parseImagePattern(r),u=[];for(let e=0;e<t;e++){const t=n+e,r=`${s}${i?this._formatNumber(t,i):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 n=o[0],i=parseInt(n,10),a=n.length;return{prefix:s.slice(0,o.index),suffix:s.slice(o.index+n.length),startNum:i,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="";const r=this.cursors[this.defaultCursorName];t+=`* { ${this._buildCursorCss(this.defaultCursorName,r)} }\n`;for(const[e,r]of Object.entries(this.cursors)){const s=`.ac-cursor-${e}`,o=r.offset||[0,0],n=r.fallback||this.options.fallbackCursor,i=this._getFrameUrls(r),a=i.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,i);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]}, ${n};`} }\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("${i[0]}") ${o[0]} ${o[1]}, ${n}; animation: ${d}; }\n`}else t+=`${s} { cursor: url("${i[0]}") ${o[0]} ${o[1]}, ${n}; }\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 n=[];let i=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/i;n.push({percent:e,url:t[u]}),a+=l,u++}}return n.push({percent:1,url:t[o-1]}),n}_buildCursorCss(e,t){const r=this._getFrameUrls(t),s=t.offset||[0,0],o=t.fallback||this.options.fallbackCursor;let n=`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){n+=` 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 n}_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=this.defaultCursorName;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!==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.0",
+    "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",