anime-cursor 1.0.0 → 2.0.1

package/dist/anime-cursor.umd.js

@@ -1,17 +1,15 @@
-(function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
-    typeof define === 'function' && define.amd ? define(factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, global.AnimeCursor = factory());
-})(this, (function () { 'use strict';
-
+(function (global, factory) {
+    typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
+    typeof define === 'function' && define.amd ? define(factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, global.AnimeCursor = factory());
+})(this, (function () { 'use strict';
+
     // AnimeCursor by github@ShuninYu
-    // v1.0.0
+    // v2.0.1
 
-    // 静态变量存储唯一实例
     let _instance = null;
 
     class AnimeCursor {
-
         static get instance() {
             return _instance;
         }
@@ -49,553 +47,418 @@
         }
 
         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 && !Array.isArray(cfg.tags)) {
+                    throw new Error(`[AnimeCursor] Cursor "${name}" tags must be an array`);
                 }
-        
-                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.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;
-        }
-        `;
-
-            /* 每种光标以及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]
-                    });
+            // 如果有默认光标，生成全局规则
+            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)) {
+                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;
 
-                    // 生成动画属性
-                    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];
+                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 += `
-                }`;
-                }
-            } 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' : ''};
+                    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`;
                 }
 
-                @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');
+        }
 
-            return 2147483646; // 浏览器安全最大值 2147483647 减一为留给debug覆盖
+        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 AnimeCursor;
-
-}));
+
+        enable() {
+            if (!this.disabled) return;
+            this.disabled = false;
+            document.body.classList.remove('animecursor-disabled');
+            if (this.options.debug) console.log('[AnimeCursor] Enabled');
+        }
+    }
+
+    return AnimeCursor;
+
+}));