anime-cursor 1.0.0 → 2.0.1

package/dist/anime-cursor.esm.js

@@ -1,11 +1,9 @@
 // AnimeCursor by github@ShuninYu
-// v1.0.0
+// v2.0.1
 
-// 静态变量存储唯一实例
 let _instance = null;
 
 class AnimeCursor {
-
     static get instance() {
         return _instance;
     }
@@ -43,551 +41,416 @@ class AnimeCursor {
     }
 
     constructor(options = {}) {
-        // 如果已有实例，直接返回它
         if (_instance) {
-            console.warn('[AnimeCursor] AnimeCursor already exists.');
+            console.warn('[AnimeCursor] Instance already exists, returning existing one');
             return _instance;
         }
 
         this.options = {
-            displayOnLoad: false,
-            enableTouch: false,
             debug: false,
+            enableTouch: false,
+            fallbackCursor: 'auto',           // Fallback cursor type (auto, pointer, etc.)
+            excludeSelectors: 'input, textarea, [contenteditable]', // Exclude native cursor elements
             ...options
         };
+
         this.disabled = false;
+        this.cursors = this.options.cursors || {};
 
+        // 检查是否应启用（触摸设备且未强制启用则禁用）
         if (!this.options.enableTouch && !this.isMouseLikeDevice()) {
             this.disabled = true;
-
             if (this.options.debug) {
-                console.warn('[AnimeCursor] Touch device detected, cursor disabled.');
+                console.warn('[AnimeCursor] Touch device detected, cursor animations disabled');
             }
             return;
         }
 
-        this.cursorEl = null;
-        this.lastCursorType = null;
-        this.debugEl = null;
         this.styleEl = null;
+        this.debugEl = null;
         this._onMouseMove = null;
 
         this._validateOptions();
-        this._injectPreload();
+        this._preloadImages();
         this._checkDomLoad();
 
-        // 保存实例引用
         _instance = this;
     }
-    
-    isMouseLikeDevice() {
-        if (this.disabled) return;
 
+    // 判断是否鼠标设备
+    isMouseLikeDevice() {
         return window.matchMedia('(pointer: fine)').matches;
     }
-    
-    // ----------------------------
-    // 刷新 清理 关闭 开启
-    // ----------------------------
-    refresh() {
-        if (this.disabled) return;
-    
-        if (this.options.debug) {
-            console.info('[AnimeCursor] starting refresh...');
-        }
-    
-        this._bindElements(true);
-    }
-    destroy() {
-        if (this.disabled) return;
 
-        // 1 移除事件监听
-        if (this._onMouseMove) {
-            document.removeEventListener('mousemove', this._onMouseMove);
-            this._onMouseMove = null;
-        }
-    
-        // 2 移除 cursor DOM
-        if (this.cursorEl) {
-            this.cursorEl.remove();
-            this.cursorEl = null;
-        }
-    
-        if (this.debugEl) {
-            this.debugEl.remove();
-            this.debugEl = null;
-        }
-    
-        // 3 移除注入的 CSS
-        if (this.styleEl) {
-            this.styleEl.remove();
-            this.styleEl = null;
-        }
-    
-        // 4 清理 data-cursor（只清理由 AnimeCursor 添加的）
-        for (const cfg of Object.values(this.options.cursors)) {
-            // v0.2.1 添加检查：只有存在且为数组的 tags 才进行处理
-            if (cfg.tags && Array.isArray(cfg.tags)) {
-                cfg.tags.forEach(tag => {
-                    document.querySelectorAll(tag).forEach(el => {
-                        if (el.dataset.cursorBound) {
-                            delete el.dataset.cursor;
-                            delete el.dataset.cursorBound;
-                        }
-                    });
-                });
-            }
-        }
-    
-        // 5 重置状态
-        this.lastCursorType = null;
-
-        // 清除静态引用
-        if (_instance === this) {
-            _instance = null;
-        }
-    }
-    disable() {
-        if (this.disabled) return;
-        this.disabled = true;
-    
-        if (this.cursorEl) {
-            this.cursorEl.style.display = 'none';
-            this.styleEl.innerHTML = this.styleEl.innerHTML.replace('* {cursor: none !important;}', '');
-            console.log('[AnimeCursor] AnimeCursor disabled!');
-        }
-    }
-    enable() {
-        if (!this.disabled) return;
-        this.disabled = false;
-    
-        if (this.cursorEl) {
-            this.cursorEl.style.display = '';
-            this.styleEl.innerHTML += '* {cursor: none; !important;}';
-            console.log('[AnimeCursor] AnimeCursor enabled!');
-        }
-    }
-    
-    // ----------------------------
-    // 配置校验（必填项）
-    // ----------------------------
+    // 验证配置（修改点：默认光标可选）
     _validateOptions() {
         if (this.disabled) return;
-    
-        if (!this.options || !this.options.cursors) {
-            console.error('[AnimeCursor] missing cursors set up');
-            throw new Error('AnimeCursor init failed');
+
+        if (!this.cursors || Object.keys(this.cursors).length === 0) {
+            throw new Error('[AnimeCursor] At least one cursor must be defined');
         }
-    
-        this.defaultCursorType = null;
-    
-        for (const [name, cfg] of Object.entries(this.options.cursors)) {
-            if (cfg.default === true) {
-                if (this.defaultCursorType) {
-                    throw new Error('[AnimeCursor] There can only be one default cursor');
-                }
-                this.defaultCursorType = name;
+
+        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`);
             }
-        }
-    
-        for (const [name, cfg] of Object.entries(this.options.cursors)) {
-            const required = ['size', 'image'];
-            required.forEach(key => {
-                if (cfg[key] === undefined) {
-                    console.error(`[AnimeCursor] cursor "${name}" missing required setting: ${key}`);
-                    throw new Error('AnimeCursor init failed');
-                }
-            });
-    
-            // 新增：校验 frames 与 duration 的类型一致性
-            if (cfg.frames !== undefined) {
-                if (Array.isArray(cfg.frames)) {
-                    // frames 为数组时，duration 必须为等长数组
-                    if (!Array.isArray(cfg.duration) || cfg.duration.length !== cfg.frames.length) {
-                        console.error(`[AnimeCursor] cursor "${name}" has frames as array but duration is not an array of same length`);
-                        throw new Error('AnimeCursor init failed');
-                    }
-                    // 检查 frames 数组元素是否为正整数
-                    for (let f of cfg.frames) {
-                        if (!Number.isInteger(f) || f <= 0) {
-                            console.error(`[AnimeCursor] cursor "${name}" frames array must contain positive integers`);
-                            throw new Error('AnimeCursor init failed');
+
+            // 处理 frames 和 duration 配置
+            if (cfg.frames !== undefined && cfg.duration !== undefined) {
+                const framesType = typeof cfg.frames;
+                const durationType = typeof cfg.duration;
+                if (framesType !== durationType) {
+                    console.warn(`[AnimeCursor] Cursor "${name}" has mismatched types for frames and duration, treating as static cursor`);
+                    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`);
+                                delete cfg.frames;
+                                delete cfg.duration;
+                                break;
+                            }
                         }
-                    }
-                    // 检查 duration 数组元素是否为正数
-                    for (let d of cfg.duration) {
-                        if (typeof d !== 'number' || d <= 0) {
-                            console.error(`[AnimeCursor] cursor "${name}" duration array must contain positive numbers`);
-                            throw new Error('AnimeCursor init failed');
+                        for (let d of cfg.duration) {
+                            if (typeof d !== 'number' || d <= 0) {
+                                console.warn(`[AnimeCursor] Cursor "${name}" duration array contains invalid value, treating as static cursor`);
+                                delete cfg.frames;
+                                delete cfg.duration;
+                                break;
+                            }
                         }
                     }
-                } else if (typeof cfg.frames === 'number') {
-                    // frames 为数字时，duration 可选，但不能是数组
-                    if (Array.isArray(cfg.duration)) {
-                        console.error(`[AnimeCursor] cursor "${name}" frames is number but duration is array, must be consistent`);
-                        throw new Error('AnimeCursor init failed');
-                    }
-                    if (!Number.isInteger(cfg.frames) || cfg.frames <= 0) {
-                        console.error(`[AnimeCursor] cursor "${name}" frames must be a positive integer`);
-                        throw new Error('AnimeCursor init failed');
-                    }
-                    if (cfg.duration !== undefined && (typeof cfg.duration !== 'number' || cfg.duration <= 0)) {
-                        console.error(`[AnimeCursor] cursor "${name}" duration must be a positive number`);
-                        throw new Error('AnimeCursor init failed');
+                } 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.error(`[AnimeCursor] cursor "${name}" frames must be a number or an array`);
-                    throw new Error('AnimeCursor init failed');
+                    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;
             }
-    
-            if (cfg.tags !== undefined && !Array.isArray(cfg.tags)) {
-                console.error(`[AnimeCursor] cursor "${name}" 's tags must be an array if provided`);
-                throw new Error('AnimeCursor init failed');
+
+            if (cfg.tags && !Array.isArray(cfg.tags)) {
+                throw new Error(`[AnimeCursor] Cursor "${name}" tags must be an array`);
+            }
+            if (cfg.default) {
+                if (hasDefault) throw new Error('[AnimeCursor] Only one default cursor allowed');
+                hasDefault = true;
+            }
+            if (cfg.offset && (!Array.isArray(cfg.offset) || cfg.offset.length !== 2)) {
+                throw new Error(`[AnimeCursor] Cursor "${name}" offset must be [x, y] array`);
             }
         }
-    }
 
-    // ----------------------------
-    // 等待 DOM 加载完成
-    // ----------------------------
-    _checkDomLoad() {
-        const init = () => {
-            this._injectHTML();
-            this._injectCSS();
-            this._bindElements();
-            this._bindMouse();
-        };
-    
-        if (document.readyState === 'loading') {
-            document.addEventListener('DOMContentLoaded', init);
-        } else {
-            init();
-        }
+        // 不再强制要求默认光标
+        this.defaultCursorName = hasDefault ? Object.keys(this.cursors).find(name => this.cursors[name].default) : null;
     }
 
-    // ----------------------------
-    // 插入光标图片预加载（）
-    // ----------------------------
-    _injectPreload() {
-        if (this.disabled) return;
-        
-        // 收集所有需要预加载的图片URL
-        const imageUrls = new Set();
-        
-        // 遍历所有光标配置，提取图片URL
-        for (const cfg of Object.values(this.options.cursors)) {
-            if (cfg.image) {
-                imageUrls.add(cfg.image);
-            }
+    // 预加载所有图片
+    _preloadImages() {
+        const images = new Set();
+        for (const cfg of Object.values(this.cursors)) {
+            const frameUrls = this._getFrameUrls(cfg);
+            frameUrls.forEach(url => images.add(url));
         }
-        
-        // 为每个图片URL创建预加载标签
-        imageUrls.forEach(url => {
+        images.forEach(url => {
             const link = document.createElement('link');
             link.rel = 'preload';
             link.as = 'image';
             link.href = url;
-            
-            // 可选：添加跨域处理（如果图片来自不同域名）
             if (url.startsWith('http') && !url.startsWith(window.location.origin)) {
                 link.crossOrigin = 'anonymous';
             }
-            
             document.head.appendChild(link);
-            
-            if (this.options.debug) {
-                console.info(`[AnimeCursor] Preloading image: ${url}`);
-            }
         });
-        
-        if (this.options.debug && imageUrls.size > 0) {
-            console.info(`[AnimeCursor] Preloaded ${imageUrls.size} cursor image(s)`);
+        if (this.options.debug && images.size) {
+            console.info(`[AnimeCursor] Preloaded ${images.size} cursor images`);
         }
     }
 
-    // ----------------------------
-    // 插入光标元素 HTML
-    // ----------------------------
-    _injectHTML() {
-        if (this.disabled) return;
+    // 根据配置生成所有帧的 URL 数组
+    _getFrameUrls(cfg) {
+        let totalFrames = 1;
+        if (cfg.frames !== undefined) {
+            if (Array.isArray(cfg.frames)) {
+                totalFrames = cfg.frames.reduce((a, b) => a + b, 0);
+            } else if (typeof cfg.frames === 'number') {
+                totalFrames = cfg.frames;
+            }
+        }
 
-        const cursor = document.createElement('div');
-        cursor.id = 'anime-cursor';
-        
-        // 如果debug选项存在，则添加debug元素
-        if (this.options.debug) {
-            cursor.className = 'cursor-default cursor-debugmode';
-            const debuger = document.createElement('div');
-            debuger.className = 'anime-cursor-debug';
-            document.body.appendChild(debuger);
-            this.debugEl = debuger;
+        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++) {
+            const frameNum = startNum + i;
+            const numStr = numFormat ? this._formatNumber(frameNum, numFormat) : frameNum;
+            const url = `${prefix}${numStr}${suffix}${ext}`;
+            urls.push(url);
+        }
+        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)/);
+        if (!numMatch) {
+            return {
+                prefix: base + '_',
+                suffix: '',
+                startNum: 1,
+                numFormat: null,
+                ext
+            };
         }
-        else {cursor.className = 'cursor-default';}
-        
-        // 检查是否设置初始化时显示光标
-        if (this.options.displayOnLoad) {
-            cursor.style.display = 'block';
+        const numStr = numMatch[0];
+        const startNum = parseInt(numStr, 10);
+        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 };
+    }
+
+    _formatNumber(num, width) {
+        return String(num).padStart(width, '0');
+    }
+
+    _checkDomLoad() {
+        const init = () => {
+            this._injectStyles();
+            if (this.options.debug) this._initDebug();
+            console.log('[AnimeCursor] Initialization complete');
+        };
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', init);
         } else {
-            cursor.style.display = 'none';
-            cursor.dataset.animecursorHide = 'true';
+            init();
         }
-        document.body.appendChild(cursor);
-        this.cursorEl = cursor;
     }
 
-    // ----------------------------
-    // 插入样式 CSS
-    // ----------------------------
-    _injectCSS() {
+    // 注入所有 CSS 规则（修改点：只有存在默认光标才生成 * 规则）
+    _injectStyles() {
         if (this.disabled) return;
 
         const style = document.createElement('style');
         style.id = 'animecursor-styles';
         let css = '';
 
-        /* 通用样式 */
-        css += `
-        * {cursor: none !important;}
-        #anime-cursor {
-        position: fixed;
-        top: 0;
-        left: 0;
-        pointer-events: none;
-        background-repeat: no-repeat;
-        transform-origin: 0 0;
-        transform-style: preserve-3d;
-        z-index: ${this._getMaxZIndex()};
-        }
-        .cursor-debugmode {
-            border: 1px solid green;
-        }
-        .anime-cursor-debug {
-            position: fixed;
-            top: 0;
-            left: 0;
-            width: fit-content;
-            height: fit-content;
-            padding: 5px;
-            font-size: 16px;
-            text-wrap: nowrap;
-            color: red;
-            pointer-events: none;
-            overflow: visible;
-            z-index: 2147483647;
-        }
-        .anime-cursor-debug::before {
-            position: absolute;
-            content: "";
-            top: 0;
-            left: 0;
-            width: 100vw;
-            height: 1px;
-            background-color: red;
-        }
-        .anime-cursor-debug::after {
-            position: absolute;
-            content: "";
-            top: 0;
-            left: 0;
-            width: 1px;
-            height: 100vh;
-            background-color: red;
+        // 如果有默认光标，生成全局规则
+        if (this.defaultCursorName) {
+            const defaultCfg = this.cursors[this.defaultCursorName];
+            const defaultCursorDef = this._buildCursorCss(this.defaultCursorName, defaultCfg);
+            css += `* { ${defaultCursorDef} }\n`;
         }
-        `;
-
-        /* 每种光标以及debug生成 CSS */
-        for (const [type, cfg] of Object.entries(this.options.cursors)) {
-        const className = `.cursor-${type}`;
-        const size = cfg.size;
-        const image = cfg.image;
-        const offset = cfg.offset;
-        const zIndex = cfg.zIndex;
-        const scale = cfg.scale;
-        const isGif = image.toLowerCase().endsWith('.gif');
-        const pixel = cfg.pixel ? 'pixelated' : 'auto';
-
-        // 基础样式
-        css += `
-        ${className} {
-            width: ${size[0]}px;
-            height: ${size[1]}px;
-            background-image: url("${image}");
-            image-rendering: ${pixel};
-            ${(scale || offset) ? `transform: ${[scale && `scale(${scale[0]}, ${scale[1]})`, offset && `translate(-${offset[0]}px, -${offset[1]}px)`].filter(Boolean).join(' ')};` : ''}
-            ${zIndex !== undefined ? `z-index:${zIndex};` : ''}
-        }`;
-
-        // 动画生成
-        const frames = cfg.frames;
-        const duration = cfg.duration;
-
-        // 判断是否使用新逻辑（数组形式）
-        if (Array.isArray(frames) && Array.isArray(duration) && frames.length === duration.length) {
-            // 计算总帧数和总时长
-            const totalFrames = frames.reduce((a, b) => a + b, 0);
-            const totalDuration = duration.reduce((a, b) => a + b, 0);
-            const hasAnimation = !isGif && totalFrames > 1 && totalDuration > 0;
-
-            if (hasAnimation) {
-                const animName = `animecursor_${type}`;
-                // 构建关键帧数组
-                const keyframes = [];
-                let cumPercent = 0;
-                let frameIndex = 0;
-
-                for (let p = 0; p < frames.length; p++) {
-                    const segFrames = frames[p];
-                    const segDuration = duration[p];
-                    const segPercent = segDuration / totalDuration;
-                    for (let j = 0; j < segFrames; j++) {
-                        const startPercent = cumPercent + (j * segPercent) / segFrames;
-                        keyframes.push({
-                            percent: startPercent,
-                            pos: -frameIndex * size[0]
-                        });
-                        frameIndex++;
-                    }
-                    cumPercent += segPercent;
-                }
-                // 添加最后一帧的结束点（100%）
-                keyframes.push({
-                    percent: 1.0,
-                    pos: -(totalFrames - 1) * size[0]
-                });
 
-                // 生成动画属性
-                css += `
-                ${className} {
-                    animation: ${animName} ${totalDuration}s infinite ${cfg.pingpong ? 'alternate' : ''};
-                }`;
-
-                // 生成 @keyframes
-                css += `
-                @keyframes ${animName} {`;
-                for (let i = 0; i < keyframes.length; i++) {
-                    const kf = keyframes[i];
+        // 为每个光标生成独立的类和关键帧
+        for (const [name, cfg] of Object.entries(this.cursors)) {
+            const className = `.ac-cursor-${name}`;
+            const offset = cfg.offset || [0, 0];
+            const fallback = cfg.fallback || this.options.fallbackCursor;
+
+            const frameUrls = this._getFrameUrls(cfg);
+            const frameCount = frameUrls.length;
+
+            const hasAnimation = cfg.frames !== undefined && cfg.duration !== undefined &&
+                ((Array.isArray(cfg.frames) && Array.isArray(cfg.duration)) ||
+                    (typeof cfg.frames === 'number' && typeof cfg.duration === 'number'));
+
+            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);
-                    if (kf.percent === 1.0) percent = '100'; // 确保100%显示为整数
-                    css += `
-                    ${percent}% {
-                        background-position: ${kf.pos}px 0;
-                        ${i < keyframes.length - 1 ? 'animation-timing-function: steps(1, end);' : ''}
-                    }`;
+                    if (kf.percent === 1.0) percent = '100';
+                    const cursorRule = `cursor: url("${kf.url}") ${offset[0]} ${offset[1]}, ${fallback};`;
+                    keyframesCss += `  ${percent}% { ${cursorRule} }\n`;
                 }
-                css += `
-                }`;
+                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' : ''}`;
+                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`;
             }
-        } else if (typeof frames === 'number' && typeof duration === 'number') {
-            // 旧逻辑：均匀动画
-            const hasAnimation = !isGif && frames > 1 && duration > 0;
-            if (hasAnimation) {
-                const animName = `animecursor_${type}`;
-                css += `
-                ${className} {
-                    animation: ${animName} steps(${frames}) ${duration}s infinite ${cfg.pingpong ? 'alternate' : ''};
-                }
 
-                @keyframes ${animName} {
-                    from { background-position: 0 0; }
-                    to { background-position: -${size[0] * frames}px 0; }
-                }`;
+            if (cfg.tags && cfg.tags.length) {
+                const selector = cfg.tags.join(', ');
+                css += `${selector} { ${this._buildCursorCss(name, cfg)} }\n`;
             }
+            css += `[data-cursor="${name}"] { ${this._buildCursorCss(name, cfg)} }\n`;
         }
-        // 若 frames 未定义或为单帧，则不生成动画，仅保留基础样式
-    }
-
-    style.textContent = css;
-    document.head.appendChild(style);
-    this.styleEl = style;
-}
-
-    // ----------------------------
-    // 给元素自动添加 data-cursor
-    // ----------------------------
-    _bindElements(refresh) {
-        if (this.disabled) return;
 
-        for (const [type, cfg] of Object.entries(this.options.cursors)) {
-            if (!cfg.tags || !Array.isArray(cfg.tags) || cfg.tags.length === 0) continue;
-            
-            cfg.tags.forEach(tag => {
-                const tagName = tag.toUpperCase();
-                document.querySelectorAll(tagName).forEach(el => {
-                    if (!el.dataset.cursor) {
-                        el.dataset.cursor = type;
-                        el.dataset.cursorBound = 'true';
-                    }
-                });
-            });
-        }
-        if (refresh) {
-            console.info('[AnimeCursor] refresh done');
+        if (this.options.excludeSelectors) {
+            css += `${this.options.excludeSelectors} { cursor: text !important; animation: none !important; }\n`;
         }
-    }
 
-    // ----------------------------
-    // 鼠标跟随 & 光标切换
-    // ----------------------------
-    _bindMouse() {
-        if (this.disabled) return;
+        css += `body.animecursor-disabled * { cursor: auto !important; animation: none !important; }\n`;
 
-        this._onMouseMove = (e) => {
-            if (this.disabled) return;
-
-            const x = e.clientX;
-            const y = e.clientY;
+        style.textContent = css;
+        document.head.appendChild(style);
+        this.styleEl = style;
+    }
 
-            this.cursorEl.style.left = x + 'px';
-            this.cursorEl.style.top = y + 'px';
+    _buildKeyframes(cfg, frameUrls) {
+        let frames = cfg.frames;
+        let durations = cfg.duration;
+        const frameCount = frameUrls.length;
 
-            if (this.cursorEl.dataset.animecursorHide) {
-                this.cursorEl.style.display = 'block';
-            }
+        if (typeof frames === 'number') {
+            const perFrameDuration = durations / frames;
+            frames = new Array(frames).fill(1);
+            durations = new Array(frames.length).fill(perFrameDuration);
+        }
 
-            if (this.debugEl) {
-                this.debugEl.style.left = x + 'px';
-                this.debugEl.style.top = y + 'px';
+        const keyframes = [];
+        let totalTime = durations.reduce((a, b) => a + b, 0);
+        let currentTime = 0;
+        let frameIdx = 0;
+        for (let seg = 0; seg < frames.length; seg++) {
+            const segFrames = frames[seg];
+            const segDuration = durations[seg];
+            const stepTime = segDuration / segFrames;
+            for (let f = 0; f < segFrames; f++) {
+                const percent = currentTime / totalTime;
+                keyframes.push({
+                    percent: percent,
+                    url: frameUrls[frameIdx]
+                });
+                currentTime += stepTime;
+                frameIdx++;
             }
+        }
+        keyframes.push({
+            percent: 1.0,
+            url: frameUrls[frameCount - 1]
+        });
+        return keyframes;
+    }
 
-            let nextCursorType = null;
-
-            // 获取命中的元素
-            const target = document.elementFromPoint(x, y);
+    _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'));
+        if (hasAnimation && frameUrls.length > 1) {
+            const totalDuration = Array.isArray(cfg.duration) ? cfg.duration.reduce((a, b) => a + b, 0) : cfg.duration;
+            css += ` animation: ac_anim_${name} ${totalDuration}s steps(1) infinite ${cfg.pingpong ? 'alternate' : ''};`;
+        }
+        return css;
+    }
 
-            // 优先使用元素自身的 data-cursor
-            if (target && target.dataset && target.dataset.cursor) {
-                nextCursorType = target.dataset.cursor;
+    _initDebug() {
+        const debugDiv = document.createElement('div');
+        debugDiv.className = 'animecursor-debug';
+        debugDiv.style.cssText = `
+      position: fixed;
+      top: 0;
+      left: 0;
+      background: rgba(0,0,0,0.7);
+      color: #0f0;
+      padding: 4px 8px;
+      font-family: monospace;
+      font-size: 12px;
+      z-index: 2147483647;
+      pointer-events: none;
+      white-space: nowrap;
+    `;
+        document.body.appendChild(debugDiv);
+        this.debugEl = debugDiv;
+
+        let lastCursor = '';
+        this._onMouseMove = (e) => {
+            const target = document.elementFromPoint(e.clientX, e.clientY);
+            let cursorType = null;
+            if (target) {
+                if (target.dataset.cursor && this.cursors[target.dataset.cursor]) {
+                    cursorType = target.dataset.cursor;
+                } else {
+                    for (const [name, cfg] of Object.entries(this.cursors)) {
+                        if (cfg.tags && cfg.tags.some(tag => target.matches(tag))) {
+                            cursorType = name;
+                            break;
+                        }
+                    }
+                }
             }
-            // 否则 尝试使用 default 光标
-            else if (this.defaultCursorType) {
-                nextCursorType = this.defaultCursorType;
+            // 如果没有匹配到任何自定义光标，且没有默认光标，则显示 "native"
+            if (!cursorType && !this.defaultCursorName) {
+                cursorType = 'native';
+            } else if (!cursorType && this.defaultCursorName) {
+                cursorType = this.defaultCursorName;
             }
-            
-            // 如果两者都没有 - 保持当前状态
-            if (!nextCursorType) return;
-            if (this.debugEl) {this.debugEl.textContent = `(${x}px , ${y}px) ${nextCursorType}`;}
-            
-            // 状态变化才切换 class
-            if (nextCursorType !== this.lastCursorType) {
-                if (this.debugEl) {this.cursorEl.className = `cursor-${nextCursorType}` + ' cursor-debugmode';}
-                else {this.cursorEl.className = `cursor-${nextCursorType}`;}
-                this.lastCursorType = nextCursorType;
+            if (cursorType !== lastCursor) {
+                lastCursor = cursorType;
+                debugDiv.textContent = `🎯 ${cursorType} @ (${e.clientX}, ${e.clientY})`;
+            } else {
+                debugDiv.textContent = `🎯 ${cursorType} @ (${e.clientX}, ${e.clientY})`;
             }
         };
-
         document.addEventListener('mousemove', this._onMouseMove);
-        console.log('[AnimeCursor] AnimeCursor setted up.');
     }
 
-    // ----------------------------
-    // 获取可用最大 z-index
-    // ----------------------------
-    _getMaxZIndex() {
+    refresh() {
+        if (this.disabled) return;
+        if (this.styleEl) this.styleEl.remove();
+        this._injectStyles();
+        if (this.options.debug) {
+            if (this.debugEl) this.debugEl.remove();
+            this._initDebug();
+        }
+        console.log('[AnimeCursor] Refresh complete');
+    }
+
+    destroy() {
+        if (this.disabled) return;
+        if (this.styleEl) this.styleEl.remove();
+        if (this.debugEl) this.debugEl.remove();
+        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;
+        document.body.classList.add('animecursor-disabled');
+        if (this.options.debug) console.log('[AnimeCursor] Disabled');
+    }
 
-        return 2147483646; // 浏览器安全最大值 2147483647 减一为留给debug覆盖
+    enable() {
+        if (!this.disabled) return;
+        this.disabled = false;
+        document.body.classList.remove('animecursor-disabled');
+        if (this.options.debug) console.log('[AnimeCursor] Enabled');
     }
-}
-
-export { AnimeCursor as default };
+}
+
+export { AnimeCursor as default };