anime-cursor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShuninYu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,307 @@
+# AnimeCursor
+
+<div align="center">
+  <img src="title.gif" width="60%" alt="AnimeCursor"/>
+</div>
+
+[[简体中文]](#SChinese)
+
+AnimeCursor is a lightweight animated cursor JS library that enables dynamic mouse pointers for websites.
+
+AnimeCursor has no dependencies on any frameworks, making it suitable for personal websites, creative portfolios, and experimental UI projects.
+
+---
+
+## ✨ Features
+
+* Supports PNG sprite sheet frame-by-frame animation
+* Supports GIF (animated GIFs, not static GIFs used by native cursors)
+* Customizable cursor types, automatically switched by AnimeCursor
+* CSS-based animation implementation, high performance
+* Prepare PNG sprite sheets in the correct format, and AnimeCursor will automatically generate cursor animations based on your settings
+* Built with native JavaScript, no third-party dependencies
+
+---
+
+## 📦 Installation
+
+### Local storage
+
+```html
+<script src="anime-cursor.umd.min.js"></script>
+```
+
+---
+
+## 🚀 Basic Usage
+
+Here is an example of how to use AnimeCursor:
+
+```html
+<script>
+new AnimeCursor({
+    cursors: {
+        default: {
+            tags: ['body'],
+            size: [64,64],
+            image: './cursor_default.png',
+            frames: 1
+        },
+        pointer: {
+            tags: ['a', 'button'],
+            size: [64,64],
+            image: './cursor_pointer.png',
+            frames: 3,
+            duration: 0.3,
+            pingpong: true,
+            offset: [10, 4]
+        }
+    }
+});
+</script>
+```
+
+---
+
+## ⚙️ Configuration Options
+
+### `cursors` (Required)
+
+An object used to define all cursor types.
+
+Each key represents a cursor type (the name can be freely defined).
+
+#### Cursor Configuration Parameters
+
+For each key, the following parameters can be set. Missing required parameters will cause an error.
+
+| Parameter | Type | Required | Description |
+|-|-|-|-|
+| `tags` | `string[]` | ✅ | HTML tags that should use this cursor |
+| `size` | `number` | ✅ | Cursor dimensions [width, height] in pixels |
+| `offset` | `[number, number]` | | Cursor alignment offset [ x , y ] |
+| `image` | `string` | ✅ | Image path (PNG / GIF) |
+| `frames` | `number` | ✅ | Number of frames for PNG sprites (set to `1` for static images) |
+| `duration` | `number` | | Animation loop duration (seconds) ⚠️ PNG sprite animations *only* work when this parameter is set |
+| `pingpong` | `boolean` | | Enable ping-pong (back-and-forth) looping (for PNG sprite animations only) |
+| `scale` | `[number, number]` | | Cursor scale factor based on `size` [ x , y ] ⚠️ Only supported for GIF cursors. Do not set for PNG sprite cursors, as it will break the animation. |
+| `pixel` | `boolean` | | Enable pixelated rendering |
+| `zIndex` | `number` | | Cursor z-index layer (not recommended to modify) |
+
+### `debug` (Optional)
+
+Enables debugging overlay.
+
+The debugging overlay shows the real mouse position and the current cursor type, helping to correct alignment offsets.
+
+### `enableTouch` (Optional)
+
+Enables animated cursors on mobile touch devices.
+
+AnimeCursor automatically detects mobile touch devices (e.g., phones, tablets) and disables animated cursors on them by default.
+If you want animated cursors to be displayed on these devices, add `enableTouch: true`.
+
+---
+
+## 📝 Notes
+
+### 📁 Files
+
+* For any PNG sprite animation cursor, its PNG sprite sheet should be arranged in a single horizontal row. AnimeCursor will automatically generate the PNG sprite animation.
+  For example, if you set the `size` (width, height) for a `pointer` cursor to `[64px , 64px]` and `frames` to `3`, the prepared sprite sheet dimensions (width, height) should be: `[192px , 64px]`.
+
+* For pixel art with a large number of frames, you can use the original image (whether GIF or PNG-sprite-sheet) to save storage space or bandwidth. Then, use the `scale` parameter in the configuration to resize the cursor and set `pixel` to `true` to avoid blurry scaling.
+
+### 🧩 Tagging Mechanism
+
+AnimeCursor automatically adds `data-cursor` attributes to page elements based on the configuration:
+
+```html
+<!-- Using the example configuration from the Basic Usage section -->
+<button data-cursor="pointer"></button>
+```
+
+`data-cursor` will NOT be added in the following cases:
+
+* The element's `tagName` is not included in the `tags` configuration of any custom cursor type.
+* The element already had a `data-cursor` attribute *before* AnimeCursor was initialized.
+
+Therefore, to assign a specific animated cursor to a particular element, simply add the corresponding `data-cursor` attribute to that element. AnimeCursor will not overwrite pre-existing `data-cursor` tags.
+
+### 🎞️ Animation Rules
+
+#### PNG Cursors
+
+Animation is generated **only when all of the following conditions are met**:
+
+* The image is a PNG
+* `frames > 1`
+* `duration` is set
+
+If `duration` is not set, the cursor will be treated as a **static cursor**, even if `frames > 1`.
+
+#### GIF Cursors
+
+* GIFs do not use `frames`, `duration`, or `pingpong`
+* Animation is controlled by the GIF file itself
+
+---
+
+## ❌ Error Handling
+
+* Missing required configuration parameters will directly terminate initialization.
+* Invalid optional configuration will also throw errors.
+* All errors are prefixed with `[AnimeCursor]` when logged to the console.
+
+---
+<h1 id="SChinese">AnimeCursor</h1>
+
+<div align="center">
+  <img src="title.gif" width="60%" alt="AnimeCursor"/>
+</div>
+
+AnimeCursor 是一个轻量级动画光标JS，能够让网站拥有动态的鼠标指针。
+
+AnimeCursor 无需依赖任何框架，适合个人网站、创意作品集以及实验性 UI 项目。
+
+---
+
+## ✨ 特性
+
+* 支持 PNG 精灵图逐帧动画
+* 支持 GIF（动态gif，而不是原生光标的静止gif）
+* 自定义光标类型，由 AnimeCursor 自动切换
+* 基于 CSS 的动画实现，高性能
+* 按照格式准备好 PNG 精灵图表，AnimeCursor 将基于你的设置自动生成光标动画
+* 基于原生JavaScript，无任何第三方依赖
+
+---
+
+## 📦 引入方式
+
+### 本地部署
+
+```html
+<script src="anime-cursor.umd.min.js"></script>
+```
+
+---
+
+## 🚀 基础用法
+
+下面是一个 AnimeCursor 使用示例：
+```html
+<script>
+new AnimeCursor({
+    cursors: {
+        default: {
+            tags: ['body'],
+            size: [64,64],
+            image: './cursor_default.png',
+            frames: 1
+        },
+        pointer: {
+            tags: ['a', 'button'],
+            size: [64,64],
+            image: './cursor_pointer.png',
+            frames: 3,
+            duration: 0.3,
+            pingpong: true,
+            offset: [10, 4]
+        }
+    }
+});
+</script>
+```
+
+---
+
+## ⚙️ 配置项说明
+
+### `cursors`（必填）
+
+用于定义所有光标类型的对象。
+
+每一个 key 代表一种光标类型（名称可以自由定义）。
+
+#### 光标配置参数
+
+对于每个key，有以下参数可以设置，其中必填项如果缺失则会报错。
+
+|参数|类型|必填|说明|
+|-|-|-|-|
+|`tags`|`string[]`|✅|使用该光标的 HTML 标签|
+|`size`|`number`|✅|光标尺寸（宽高，像素）|
+|`offset`|`[number, number]`||光标对齐偏移量 [ x , y ]|
+|`image`|`string`|✅|图片路径（PNG / GIF）|
+|`frames`|`number`|✅|PNG 帧数（静态图片请设置为 `1` ）|
+|`duration`|`number`||动画循环时长（秒）⚠️PNG精灵图动画只有设置该参数才会生效|
+|`pingpong`|`boolean`||是否启用乒乓循环（仅PNG精灵图动画）|
+|`scale`|`[number, number]`||基于size的光标缩放 [ x , y ]⚠️仅支持GIF光标，PNG精灵图动画光标请勿设置，否则会使动画失效|
+|`pixel`|`boolean`||是否启用像素化渲染|
+|`zIndex`|`number`||光标层级（不建议添加此项设置）|
+
+### `debug`（选填）
+
+用于启用debug覆盖。
+
+debug覆盖会显示鼠标的真实位置以及当前光标类型，以帮助纠正对齐偏移量。
+
+### `enableTouch`（选填）
+
+用于启用移动触屏设备上的动画光标。
+
+AnimeCursor 会自动识别移动触屏设备（比如手机、平板电脑）并默认屏蔽这些设备上的动画光标。
+如果你想在这些设备上显示动画光标，可以添加 `enableTouch: true` 。
+
+---
+
+## 📝 注意事项
+
+### 📁 文件
+
+* 对于任何 PNG 精灵图动画光标，它的 PNG 精灵图表都应该为单行横向布局，AnimeCursor 会自动生成 PNG 精灵图动画。
+例如，你为 `pointer` 光标设置的`size`（长，宽）为 `[64px , 64px]` ，帧数为 `3` ，那么你准备的精灵图表尺寸（长，宽）应该为： `[192px , 64px]` 。
+
+* 对于帧数特别多的像素图，你可以使用原尺寸图片（无论是gif还是png精灵图表）以节省存储空间或带宽，并在参数中设置 `scale` 来缩放光标，并将 `pixel` 设置为 `true` 来避免缩放模糊。
+
+### 🧩 标记机制
+
+AnimeCursor 会根据配置自动为页面元素添加 `data-cursor`：
+
+```html
+<!-- 以上面的示例用法配置为例 -->
+<button data-cursor="pointer"></button>
+```
+
+只有在以下情况不会添加 `data-cursor`：
+
+* 元素的 `tagName` 不在任何自定义光标类型的配置中。
+* 元素在 AnimeCursor 配置之前就已经存在 `data-cursor` 。
+
+因此，如果想要给某个特定元素指定一种动画指针，只需要给该元素添加指定的 `data-cursor` 即可，AnimeCursor 不会覆盖事先设定好的标记。
+
+### 🎞️ 动画判定
+
+#### PNG 光标
+
+只有在 **同时满足以下条件** 时，才会生成动画：
+
+* 图片为 PNG
+* `frames > 1`
+* 设置了 `duration`
+
+如果未设置 `duration`，即使帧数大于 1，也会被视为**静态光标**。
+
+#### GIF 光标
+
+* GIF 不使用 `frames`、`duration` 或 `pingpong`
+* 动画由 GIF 自身控制
+
+---
+
+## ❌ 错误处理
+
+* 缺少必填配置会直接终止初始化
+* 非法的可选配置也会报错
+* 所有错误均以 `[AnimeCursor]` 前缀输出到console

package/dist/anime-cursor.esm.js

@@ -0,0 +1,254 @@
+class AnimeCursor {
+
+    constructor(options = {}) {
+        this.options = {
+            enableTouch: false,
+            debug: false,
+            ...options
+        };
+        this.disabled = false;
+
+        if (!this.options.enableTouch && !this.isMouseLikeDevice()) {
+            this.disabled = true;
+
+            if (this.options.debug) {
+                console.warn('[AnimeCursor] Touch device detected, cursor disabled.');
+            }
+            return;
+        }
+
+        this.cursorEl = null;
+        this.lastCursorType = null;
+        this.debugEl = null;
+
+        this._validateOptions();
+        this._injectHTML();
+        this._injectCSS();
+        this._bindElements();
+        this._bindMouse();
+    }
+    
+    isMouseLikeDevice() {
+        return window.matchMedia('(pointer: fine)').matches;
+    }
+    
+    destroy() {
+        if (this.disabled) return;
+    }
+
+    // ----------------------------
+    // 配置校验（必填项）
+    // ----------------------------
+    _validateOptions() {
+        if (!this.options || !this.options.cursors) {
+            console.error('[AnimeCursor] 缺少 cursors 配置');
+            throw new Error('AnimeCursor init failed');
+        }
+
+        for (const [name, cfg] of Object.entries(this.options.cursors)) {
+            const required = ['tags', 'size', 'image', 'frames'];
+            required.forEach(key => {
+                if (cfg[key] === undefined) {
+                    console.error(`[AnimeCursor] 光标 "${name}" 缺少必填项：${key}`);
+                    throw new Error('AnimeCursor init failed');
+                }
+            });
+
+            if (!Array.isArray(cfg.tags)) {
+                console.error(`[AnimeCursor] 光标 "${name}" 的 tags 必须是数组`);
+                throw new Error('AnimeCursor init failed');
+            }
+
+            if (cfg.duration !== undefined && typeof cfg.duration !== 'number') {
+                console.error(`[AnimeCursor] 光标 "${name}" 的 duration 必须是数字（秒）`);
+                throw new Error('AnimeCursor init failed');
+            }
+        }
+    }
+
+    // ----------------------------
+    // 插入光标元素 HTML
+    // ----------------------------
+    _injectHTML() {
+        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;
+        }
+        else {cursor.className = 'cursor-default';}
+        document.body.appendChild(cursor);
+        this.cursorEl = cursor;
+    }
+
+    // ----------------------------
+    // 插入基础 CSS
+    // ----------------------------
+    _injectCSS() {
+        const style = document.createElement('style');
+        let css = '';
+
+        /* 通用样式和debug样式 */
+        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 frames = cfg.frames;
+            const image = cfg.image;
+            const offset = cfg.offset;
+            const zIndex = cfg.zIndex;
+            const scale = cfg.scale;
+            const isGif = image.toLowerCase().endsWith('.gif');
+            var pixel;
+            if (cfg.pixel) {pixel = 'pixelated';}
+            else {pixel = '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};` : ''}
+}`;
+
+            /* PNG 精灵图动画 */
+            const duration = cfg.duration;
+            const hasAnimation =
+                !isGif &&
+                frames > 1 &&
+                typeof duration === 'number';
+
+            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; }
+}
+`;
+            }
+        }
+
+        style.textContent = css;
+        document.head.appendChild(style);
+    }
+
+    // ----------------------------
+    // 给元素自动添加 data-cursor
+    // ----------------------------
+    _bindElements() {
+        for (const [type, cfg] of Object.entries(this.options.cursors)) {
+            cfg.tags.forEach(tag => {
+                const tagName = tag.toUpperCase();
+                document.querySelectorAll(tagName).forEach(el => {
+                    if (!el.dataset.cursor) {
+                        el.dataset.cursor = type;
+                    }
+                });
+            });
+        }
+    }
+
+    // ----------------------------
+    // 鼠标跟随 & 光标切换
+    // ----------------------------
+    _bindMouse() {
+        document.addEventListener('mousemove', e => {
+            const x = e.clientX;
+            const y = e.clientY;
+
+            this.cursorEl.style.left = x + 'px';
+            this.cursorEl.style.top = y + 'px';
+
+            if (this.debugEl) {
+                this.debugEl.style.left = x + 'px';
+                this.debugEl.style.top = y + 'px';
+            }
+
+            const target = document.elementFromPoint(x, y);
+            if (!target) return;
+
+            const cursorType = target.dataset.cursor || 'default';
+            if (this.debugEl) {this.debugEl.textContent = `(${x}px , ${y}px) ${cursorType}`;}
+
+            if (cursorType !== this.lastCursorType) {
+                if (this.debugEl) {this.cursorEl.className = `cursor-${cursorType}` + ' cursor-debugmode';}
+                else {this.cursorEl.className = `cursor-${cursorType}`;}
+                this.lastCursorType = cursorType;
+            }
+        });
+    }
+
+    // ----------------------------
+    // 获取可用最大 z-index
+    // ----------------------------
+    _getMaxZIndex() {
+        return 2147483646; // 浏览器安全最大值 2147483647 减一为留给debug覆盖
+    }
+}
+
+export { AnimeCursor as default };

package/dist/anime-cursor.umd.js

@@ -0,0 +1,262 @@
+(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';
+
+  class AnimeCursor {
+
+      constructor(options = {}) {
+          this.options = {
+              enableTouch: false,
+              debug: false,
+              ...options
+          };
+          this.disabled = false;
+
+          if (!this.options.enableTouch && !this.isMouseLikeDevice()) {
+              this.disabled = true;
+
+              if (this.options.debug) {
+                  console.warn('[AnimeCursor] Touch device detected, cursor disabled.');
+              }
+              return;
+          }
+
+          this.cursorEl = null;
+          this.lastCursorType = null;
+          this.debugEl = null;
+
+          this._validateOptions();
+          this._injectHTML();
+          this._injectCSS();
+          this._bindElements();
+          this._bindMouse();
+      }
+      
+      isMouseLikeDevice() {
+          return window.matchMedia('(pointer: fine)').matches;
+      }
+      
+      destroy() {
+          if (this.disabled) return;
+      }
+
+      // ----------------------------
+      // 配置校验（必填项）
+      // ----------------------------
+      _validateOptions() {
+          if (!this.options || !this.options.cursors) {
+              console.error('[AnimeCursor] 缺少 cursors 配置');
+              throw new Error('AnimeCursor init failed');
+          }
+
+          for (const [name, cfg] of Object.entries(this.options.cursors)) {
+              const required = ['tags', 'size', 'image', 'frames'];
+              required.forEach(key => {
+                  if (cfg[key] === undefined) {
+                      console.error(`[AnimeCursor] 光标 "${name}" 缺少必填项：${key}`);
+                      throw new Error('AnimeCursor init failed');
+                  }
+              });
+
+              if (!Array.isArray(cfg.tags)) {
+                  console.error(`[AnimeCursor] 光标 "${name}" 的 tags 必须是数组`);
+                  throw new Error('AnimeCursor init failed');
+              }
+
+              if (cfg.duration !== undefined && typeof cfg.duration !== 'number') {
+                  console.error(`[AnimeCursor] 光标 "${name}" 的 duration 必须是数字（秒）`);
+                  throw new Error('AnimeCursor init failed');
+              }
+          }
+      }
+
+      // ----------------------------
+      // 插入光标元素 HTML
+      // ----------------------------
+      _injectHTML() {
+          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;
+          }
+          else {cursor.className = 'cursor-default';}
+          document.body.appendChild(cursor);
+          this.cursorEl = cursor;
+      }
+
+      // ----------------------------
+      // 插入基础 CSS
+      // ----------------------------
+      _injectCSS() {
+          const style = document.createElement('style');
+          let css = '';
+
+          /* 通用样式和debug样式 */
+          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 frames = cfg.frames;
+              const image = cfg.image;
+              const offset = cfg.offset;
+              const zIndex = cfg.zIndex;
+              const scale = cfg.scale;
+              const isGif = image.toLowerCase().endsWith('.gif');
+              var pixel;
+              if (cfg.pixel) {pixel = 'pixelated';}
+              else {pixel = '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};` : ''}
+}`;
+
+              /* PNG 精灵图动画 */
+              const duration = cfg.duration;
+              const hasAnimation =
+                  !isGif &&
+                  frames > 1 &&
+                  typeof duration === 'number';
+
+              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; }
+}
+`;
+              }
+          }
+
+          style.textContent = css;
+          document.head.appendChild(style);
+      }
+
+      // ----------------------------
+      // 给元素自动添加 data-cursor
+      // ----------------------------
+      _bindElements() {
+          for (const [type, cfg] of Object.entries(this.options.cursors)) {
+              cfg.tags.forEach(tag => {
+                  const tagName = tag.toUpperCase();
+                  document.querySelectorAll(tagName).forEach(el => {
+                      if (!el.dataset.cursor) {
+                          el.dataset.cursor = type;
+                      }
+                  });
+              });
+          }
+      }
+
+      // ----------------------------
+      // 鼠标跟随 & 光标切换
+      // ----------------------------
+      _bindMouse() {
+          document.addEventListener('mousemove', e => {
+              const x = e.clientX;
+              const y = e.clientY;
+
+              this.cursorEl.style.left = x + 'px';
+              this.cursorEl.style.top = y + 'px';
+
+              if (this.debugEl) {
+                  this.debugEl.style.left = x + 'px';
+                  this.debugEl.style.top = y + 'px';
+              }
+
+              const target = document.elementFromPoint(x, y);
+              if (!target) return;
+
+              const cursorType = target.dataset.cursor || 'default';
+              if (this.debugEl) {this.debugEl.textContent = `(${x}px , ${y}px) ${cursorType}`;}
+
+              if (cursorType !== this.lastCursorType) {
+                  if (this.debugEl) {this.cursorEl.className = `cursor-${cursorType}` + ' cursor-debugmode';}
+                  else {this.cursorEl.className = `cursor-${cursorType}`;}
+                  this.lastCursorType = cursorType;
+              }
+          });
+      }
+
+      // ----------------------------
+      // 获取可用最大 z-index
+      // ----------------------------
+      _getMaxZIndex() {
+          return 2147483646; // 浏览器安全最大值 2147483647 减一为留给debug覆盖
+      }
+  }
+
+  return AnimeCursor;
+
+}));

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

@@ -0,0 +1 @@
+!function(e,n){"object"==typeof exports&&"undefined"!=typeof module?module.exports=n():"function"==typeof define&&define.amd?define(n):(e="undefined"!=typeof globalThis?globalThis:e||self).AnimeCursor=n()}(this,function(){"use strict";return class{constructor(e={}){if(this.options={enableTouch:!1,debug:!1,...e},this.disabled=!1,!this.options.enableTouch&&!this.isMouseLikeDevice())return this.disabled=!0,void(this.options.debug&&console.warn("[AnimeCursor] Touch device detected, cursor disabled."));this.cursorEl=null,this.lastCursorType=null,this.debugEl=null,this._validateOptions(),this._injectHTML(),this._injectCSS(),this._bindElements(),this._bindMouse()}isMouseLikeDevice(){return window.matchMedia("(pointer: fine)").matches}destroy(){this.disabled}_validateOptions(){if(!this.options||!this.options.cursors)throw console.error("[AnimeCursor] 缺少 cursors 配置"),new Error("AnimeCursor init failed");for(const[e,n]of Object.entries(this.options.cursors)){if(["tags","size","image","frames"].forEach(t=>{if(void 0===n[t])throw console.error(`[AnimeCursor] 光标 "${e}" 缺少必填项：${t}`),new Error("AnimeCursor init failed")}),!Array.isArray(n.tags))throw console.error(`[AnimeCursor] 光标 "${e}" 的 tags 必须是数组`),new Error("AnimeCursor init failed");if(void 0!==n.duration&&"number"!=typeof n.duration)throw console.error(`[AnimeCursor] 光标 "${e}" 的 duration 必须是数字（秒）`),new Error("AnimeCursor init failed")}}_injectHTML(){const e=document.createElement("div");if(e.id="anime-cursor",this.options.debug){e.className="cursor-default cursor-debugmode";const n=document.createElement("div");n.className="anime-cursor-debug",document.body.appendChild(n),this.debugEl=n}else e.className="cursor-default";document.body.appendChild(e),this.cursorEl=e}_injectCSS(){const e=document.createElement("style");let n="";n+=`\n* {\ncursor: none !important;\n}\n#anime-cursor {\nposition: fixed;\ntop: 0;\nleft: 0;\npointer-events: none;\nbackground-repeat: no-repeat;\ntransform-origin: 0 0;\ntransform-style: preserve-3d;\nz-index: ${this._getMaxZIndex()};\n}\n.cursor-debugmode {\n    border: 1px solid green;\n}\n.anime-cursor-debug {\n    position: fixed;\n    top: 0;\n    left: 0;\n    width: fit-content;\n    height: fit-content;\n    padding: 5px;\n    font-size: 16px;\n    text-wrap: nowrap;\n    color: red;\n    pointer-events: none;\n    overflow: visible;\n    z-index: 2147483647;\n}\n.anime-cursor-debug::before {\n    position: absolute;\n    content: "";\n    top: 0;\n    left: 0;\n    width: 100vw;\n    height: 1px;\n    background-color: red;\n}\n.anime-cursor-debug::after {\n    position: absolute;\n    content: "";\n    top: 0;\n    left: 0;\n    width: 1px;\n    height: 100vh;\n    background-color: red;\n}\n`;for(const[e,o]of Object.entries(this.options.cursors)){const r=`.cursor-${e}`,s=o.size,i=o.frames,d=o.image,u=o.offset,a=o.zIndex,c=o.scale,l=d.toLowerCase().endsWith(".gif");var t;t=o.pixel?"pixelated":"auto",n+=`\n${r} {\nwidth: ${s[0]}px;\nheight: ${s[1]}px;\nbackground-image: url("${d}");\nimage-rendering: ${t};\n${c||u?`transform: ${[c&&`scale(${c[0]}, ${c[1]})`,u&&`translate(-${u[0]}px, -${u[1]}px)`].filter(Boolean).join(" ")};`:""}\n  \n${void 0!==a?`z-index:${a};`:""}\n}`;const p=o.duration;if(!l&&i>1&&"number"==typeof p){const t=`animecursor_${e}`;n+=`\n${r} {\nanimation: ${t} steps(${i}) ${p}s infinite ${o.pingpong?"alternate":""};\n}\n\n@keyframes ${t} {\nfrom { background-position: 0 0; }\nto { background-position: -${s[0]*i}px 0; }\n}\n`}}e.textContent=n,document.head.appendChild(e)}_bindElements(){for(const[e,n]of Object.entries(this.options.cursors))n.tags.forEach(n=>{const t=n.toUpperCase();document.querySelectorAll(t).forEach(n=>{n.dataset.cursor||(n.dataset.cursor=e)})})}_bindMouse(){document.addEventListener("mousemove",e=>{const n=e.clientX,t=e.clientY;this.cursorEl.style.left=n+"px",this.cursorEl.style.top=t+"px",this.debugEl&&(this.debugEl.style.left=n+"px",this.debugEl.style.top=t+"px");const o=document.elementFromPoint(n,t);if(!o)return;const r=o.dataset.cursor||"default";this.debugEl&&(this.debugEl.textContent=`(${n}px , ${t}px) ${r}`),r!==this.lastCursorType&&(this.debugEl?this.cursorEl.className=`cursor-${r} cursor-debugmode`:this.cursorEl.className=`cursor-${r}`,this.lastCursorType=r)})}_getMaxZIndex(){return 2147483646}}});

package/package.json

@@ -0,0 +1,20 @@
+{
+    "name": "anime-cursor",
+    "version": "0.1.0",
+    "description": "A lightweight JS for website animated cursors",
+    "main": "dist/anime-cursor.umd.js",
+    "module": "dist/anime-cursor.esm.js",
+    "files": [
+        "dist"
+    ],
+    "keywords": ["cursor", "animation", "ui", "javascript"],
+    "scripts": {
+        "build": "rollup -c"
+    },
+    "author": "ShuninYu",
+    "license": "MIT",
+    "devDependencies": {
+        "@rollup/plugin-terser": "^0.4.4",
+        "rollup": "^4.56.0"
+    }
+}