mason-sprite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mason
+
+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,134 @@
+# mason-sprite
+
+Lightweight sprite sheet animation for **React**, **Vue**, and **Svelte** — one package, subpath imports.
+
+Drop in a PNG or WebP sprite sheet, set `rows`, `cols`, and `fps` — and you're done. No Lottie, no timeline editor. Just a simple **CSS** or **Canvas** sprite player.
+
+## Install
+
+```bash
+npm install mason-sprite
+```
+
+Peer dependencies (install only what you use):
+
+| Framework | Peers |
+|-----------|-------|
+| React | `react`, `react-dom` |
+| Vue 3 | `vue` |
+| Svelte | `svelte` |
+
+## Usage
+
+### Core engine (vanilla JS)
+
+```ts
+import { SpriteAnimator } from 'mason-sprite';
+
+const animator = new SpriteAnimator({
+  src: '/sprites/hero.png',
+  rows: 2,
+  cols: 5,
+  fps: 10,
+  loop: true,
+  width: 140,
+  height: 140,
+});
+
+animator.attach(document.getElementById('sprite')!);
+animator.play();
+```
+
+### React
+
+```tsx
+import { Sprite } from 'mason-sprite/react';
+
+<Sprite
+  src="/sprites/hero.png"
+  rows={2}
+  cols={5}
+  fps={10}
+  loop
+  width={140}
+  height={140}
+/>
+```
+
+### Vue 3
+
+```vue
+<script setup>
+import { Sprite } from 'mason-sprite/vue';
+</script>
+
+<template>
+  <Sprite
+    src="/sprites/hero.png"
+    :rows="2"
+    :cols="5"
+    :fps="10"
+    :loop="true"
+    :width="140"
+    :height="140"
+  />
+</template>
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { Sprite } from 'mason-sprite/svelte';
+</script>
+
+<Sprite
+  src="/sprites/hero.png"
+  rows={2}
+  cols={5}
+  fps={10}
+  loop
+  width={140}
+  height={140}
+/>
+```
+
+## Exports
+
+| Import path | Contents |
+|-------------|----------|
+| `mason-sprite` | `SpriteAnimator`, types, utilities |
+| `mason-sprite/react` | `Sprite`, `useSprite` |
+| `mason-sprite/vue` | `Sprite` component |
+| `mason-sprite/svelte` | `Sprite` component |
+
+## Features
+
+- PNG / WebP sprite sheet support
+- CSS or Canvas rendering
+- `play`, `pause`, `stop`, `goToFrame` controls
+- Works with any uniform grid sprite sheet (`rows × cols`)
+
+## Sprite Sheet Requirements
+
+- Uniform grid — every frame is the same size
+- PNG or WebP format
+- `rows × cols` = total frame count
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm typecheck
+```
+
+## Publish
+
+```bash
+npm publish
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,273 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/index.ts
+var core_exports = {};
+__export(core_exports, {
+  SPRITE_ANIMATION_DEFAULTS: () => SPRITE_ANIMATION_DEFAULTS,
+  SpriteAnimator: () => SpriteAnimator,
+  getBackgroundPositionPercent: () => getBackgroundPositionPercent,
+  getFramePosition: () => getFramePosition,
+  getTotalFrames: () => getTotalFrames
+});
+module.exports = __toCommonJS(core_exports);
+
+// src/core/constants.ts
+var SPRITE_ANIMATION_DEFAULTS = {
+  fps: 12,
+  loop: true,
+  width: 128,
+  height: 128,
+  autoPlay: true,
+  renderer: "css"
+};
+
+// src/core/utils.ts
+function getTotalFrames(rows, cols) {
+  return rows * cols;
+}
+function getFramePosition(frameIndex, cols) {
+  return {
+    row: Math.floor(frameIndex / cols),
+    col: frameIndex % cols
+  };
+}
+function getBackgroundPositionPercent(frameIndex, rows, cols) {
+  const { row, col } = getFramePosition(frameIndex, cols);
+  const x = cols <= 1 ? 0 : col / (cols - 1) * 100;
+  const y = rows <= 1 ? 0 : row / (rows - 1) * 100;
+  return { x, y };
+}
+
+// src/core/canvas-renderer.ts
+function drawCanvasFrame(canvas, image, frameIndex, rows, cols, width, height) {
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return;
+  const frameWidth = image.naturalWidth / cols;
+  const frameHeight = image.naturalHeight / rows;
+  const { row, col } = getFramePosition(frameIndex, cols);
+  canvas.width = width;
+  canvas.height = height;
+  ctx.clearRect(0, 0, width, height);
+  ctx.drawImage(
+    image,
+    col * frameWidth,
+    row * frameHeight,
+    frameWidth,
+    frameHeight,
+    0,
+    0,
+    width,
+    height
+  );
+}
+
+// src/core/css-renderer.ts
+function applyCssFrame(target, src, frameIndex, rows, cols, width, height) {
+  const { x, y } = getBackgroundPositionPercent(frameIndex, rows, cols);
+  target.style.backgroundImage = `url("${src}")`;
+  target.style.backgroundRepeat = "no-repeat";
+  target.style.backgroundSize = `${cols * 100}% ${rows * 100}%`;
+  target.style.backgroundPosition = `${x}% ${y}%`;
+  target.style.width = `${width}px`;
+  target.style.height = `${height}px`;
+  target.style.display = "inline-block";
+}
+function resetCssRenderer(target) {
+  target.style.backgroundImage = "";
+}
+
+// src/core/sprite-animator.ts
+var SpriteAnimator = class {
+  constructor(options) {
+    this.currentFrame = 0;
+    this.isPlaying = false;
+    this.isLoaded = false;
+    this.rafId = null;
+    this.lastTimestamp = 0;
+    this.accumulatedTime = 0;
+    this.image = null;
+    this.target = null;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.destroyed = false;
+    this.tick = (timestamp) => {
+      if (!this.isPlaying || this.destroyed) return;
+      if (this.lastTimestamp === 0) {
+        this.lastTimestamp = timestamp;
+      }
+      const delta = timestamp - this.lastTimestamp;
+      this.lastTimestamp = timestamp;
+      this.accumulatedTime += delta;
+      const frameDuration = 1e3 / this.options.fps;
+      while (this.accumulatedTime >= frameDuration) {
+        this.accumulatedTime -= frameDuration;
+        this.advanceFrame();
+      }
+      this.rafId = requestAnimationFrame(this.tick);
+    };
+    this.options = {
+      ...SPRITE_ANIMATION_DEFAULTS,
+      ...options
+    };
+    this.loadImage();
+  }
+  attach(target) {
+    this.target = target;
+    if (this.isLoaded) {
+      this.render();
+    }
+    if (this.options.autoPlay) {
+      this.play();
+    }
+  }
+  play() {
+    if (this.destroyed || this.isPlaying) return;
+    this.isPlaying = true;
+    this.lastTimestamp = 0;
+    this.accumulatedTime = 0;
+    this.rafId = requestAnimationFrame(this.tick);
+    this.notify();
+  }
+  pause() {
+    if (!this.isPlaying) return;
+    this.isPlaying = false;
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+    this.notify();
+  }
+  stop() {
+    this.pause();
+    this.currentFrame = 0;
+    this.render();
+    this.notify();
+  }
+  goToFrame(frame) {
+    const total = this.getTotalFrames();
+    this.currentFrame = Math.max(0, Math.min(frame, total - 1));
+    this.render();
+    this.options.onFrameChange?.(this.currentFrame);
+    this.notify();
+  }
+  getState() {
+    return {
+      currentFrame: this.currentFrame,
+      totalFrames: this.getTotalFrames(),
+      isPlaying: this.isPlaying,
+      isLoaded: this.isLoaded
+    };
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    listener(this.getState());
+    return () => this.listeners.delete(listener);
+  }
+  updateOptions(partial) {
+    const prevSrc = this.options.src;
+    const prevFps = this.options.fps;
+    this.options = { ...this.options, ...partial };
+    if (partial.src !== void 0 && partial.src !== prevSrc) {
+      this.loadImage();
+    } else if (this.isLoaded) {
+      this.render();
+    }
+    if (partial.fps !== void 0 && partial.fps !== prevFps) {
+      this.accumulatedTime = 0;
+    }
+  }
+  destroy() {
+    this.destroyed = true;
+    this.pause();
+    this.listeners.clear();
+    if (this.target && this.options.renderer === "css") {
+      resetCssRenderer(this.target);
+    }
+    this.target = null;
+    this.image = null;
+  }
+  getTotalFrames() {
+    return getTotalFrames(this.options.rows, this.options.cols);
+  }
+  loadImage() {
+    this.isLoaded = false;
+    const img = new Image();
+    img.crossOrigin = "anonymous";
+    img.onload = () => {
+      if (this.destroyed) return;
+      this.image = img;
+      this.isLoaded = true;
+      if (!this.options.width || !this.options.height) {
+        const frameWidth = img.naturalWidth / this.options.cols;
+        const frameHeight = img.naturalHeight / this.options.rows;
+        this.options.width = frameWidth;
+        this.options.height = frameHeight;
+      }
+      this.render();
+      this.notify();
+      if (this.options.autoPlay && this.target) {
+        this.play();
+      }
+    };
+    img.onerror = () => {
+      console.error(`[SpriteAnimator] Failed to load image: ${this.options.src}`);
+    };
+    img.src = this.options.src;
+  }
+  advanceFrame() {
+    const total = this.getTotalFrames();
+    const next = this.currentFrame + 1;
+    if (next >= total) {
+      if (this.options.loop) {
+        this.currentFrame = 0;
+      } else {
+        this.currentFrame = total - 1;
+        this.pause();
+        this.options.onComplete?.();
+      }
+    } else {
+      this.currentFrame = next;
+    }
+    this.render();
+    this.options.onFrameChange?.(this.currentFrame);
+    this.notify();
+  }
+  render() {
+    if (!this.target || !this.isLoaded) return;
+    const { src, rows, cols, width, height, renderer } = this.options;
+    if (renderer === "canvas" && this.target instanceof HTMLCanvasElement && this.image) {
+      drawCanvasFrame(this.target, this.image, this.currentFrame, rows, cols, width, height);
+    } else if (renderer === "css" && this.target instanceof HTMLElement) {
+      applyCssFrame(this.target, src, this.currentFrame, rows, cols, width, height);
+    }
+  }
+  notify() {
+    const state = this.getState();
+    this.listeners.forEach((listener) => listener(state));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SPRITE_ANIMATION_DEFAULTS,
+  SpriteAnimator,
+  getBackgroundPositionPercent,
+  getFramePosition,
+  getTotalFrames
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/index.ts","../src/core/constants.ts","../src/core/utils.ts","../src/core/canvas-renderer.ts","../src/core/css-renderer.ts","../src/core/sprite-animator.ts"],"sourcesContent":["export { SPRITE_ANIMATION_DEFAULTS } from './constants.js';\nexport { SpriteAnimator } from './sprite-animator.js';\nexport type {\n  FramePosition,\n  RendererMode,\n  SpriteAnimationOptions,\n  SpriteAnimationState,\n} from './types.js';\nexport {\n  getBackgroundPositionPercent,\n  getFramePosition,\n  getTotalFrames,\n} from './utils.js';\n","import type { RendererMode } from './types.js';\n\nexport const SPRITE_ANIMATION_DEFAULTS = {\n  fps: 12,\n  loop: true,\n  width: 128,\n  height: 128,\n  autoPlay: true,\n  renderer: 'css' as RendererMode,\n} as const;\n","import type { FramePosition } from './types.js';\n\nexport function getTotalFrames(rows: number, cols: number): number {\n  return rows * cols;\n}\n\nexport function getFramePosition(frameIndex: number, cols: number): FramePosition {\n  return {\n    row: Math.floor(frameIndex / cols),\n    col: frameIndex % cols,\n  };\n}\n\nexport function getBackgroundPositionPercent(\n  frameIndex: number,\n  rows: number,\n  cols: number,\n): { x: number; y: number } {\n  const { row, col } = getFramePosition(frameIndex, cols);\n  const x = cols <= 1 ? 0 : (col / (cols - 1)) * 100;\n  const y = rows <= 1 ? 0 : (row / (rows - 1)) * 100;\n  return { x, y };\n}\n","import { getFramePosition } from './utils.js';\n\nexport function drawCanvasFrame(\n  canvas: HTMLCanvasElement,\n  image: HTMLImageElement,\n  frameIndex: number,\n  rows: number,\n  cols: number,\n  width: number,\n  height: number,\n): void {\n  const ctx = canvas.getContext('2d');\n  if (!ctx) return;\n\n  const frameWidth = image.naturalWidth / cols;\n  const frameHeight = image.naturalHeight / rows;\n  const { row, col } = getFramePosition(frameIndex, cols);\n\n  canvas.width = width;\n  canvas.height = height;\n\n  ctx.clearRect(0, 0, width, height);\n  ctx.drawImage(\n    image,\n    col * frameWidth,\n    row * frameHeight,\n    frameWidth,\n    frameHeight,\n    0,\n    0,\n    width,\n    height,\n  );\n}\n","import { getBackgroundPositionPercent } from './utils.js';\n\nexport interface CssRendererTarget {\n  style: CSSStyleDeclaration;\n}\n\nexport function applyCssFrame(\n  target: CssRendererTarget,\n  src: string,\n  frameIndex: number,\n  rows: number,\n  cols: number,\n  width: number,\n  height: number,\n): void {\n  const { x, y } = getBackgroundPositionPercent(frameIndex, rows, cols);\n\n  target.style.backgroundImage = `url(\"${src}\")`;\n  target.style.backgroundRepeat = 'no-repeat';\n  target.style.backgroundSize = `${cols * 100}% ${rows * 100}%`;\n  target.style.backgroundPosition = `${x}% ${y}%`;\n  target.style.width = `${width}px`;\n  target.style.height = `${height}px`;\n  target.style.display = 'inline-block';\n}\n\nexport function resetCssRenderer(target: CssRendererTarget): void {\n  target.style.backgroundImage = '';\n}\n","import { SPRITE_ANIMATION_DEFAULTS } from './constants.js';\nimport { drawCanvasFrame } from './canvas-renderer.js';\nimport { applyCssFrame, resetCssRenderer } from './css-renderer.js';\nimport type { SpriteAnimationOptions, SpriteAnimationState } from './types.js';\nimport { getTotalFrames } from './utils.js';\n\ntype StateListener = (state: SpriteAnimationState) => void;\n\ntype ResolvedSpriteAnimationOptions = Required<\n  Pick<SpriteAnimationOptions, 'src' | 'rows' | 'cols'>\n> &\n  Required<Pick<SpriteAnimationOptions, 'fps' | 'loop' | 'width' | 'height' | 'autoPlay' | 'renderer'>> &\n  Pick<SpriteAnimationOptions, 'onComplete' | 'onFrameChange'>;\n\nexport class SpriteAnimator {\n  private options: ResolvedSpriteAnimationOptions;\n  private currentFrame = 0;\n  private isPlaying = false;\n  private isLoaded = false;\n  private rafId: number | null = null;\n  private lastTimestamp = 0;\n  private accumulatedTime = 0;\n  private image: HTMLImageElement | null = null;\n  private target: HTMLElement | HTMLCanvasElement | null = null;\n  private listeners = new Set<StateListener>();\n  private destroyed = false;\n\n  constructor(options: SpriteAnimationOptions) {\n    this.options = {\n      ...SPRITE_ANIMATION_DEFAULTS,\n      ...options,\n    };\n    this.loadImage();\n  }\n\n  attach(target: HTMLElement | HTMLCanvasElement): void {\n    this.target = target;\n    if (this.isLoaded) {\n      this.render();\n    }\n    if (this.options.autoPlay) {\n      this.play();\n    }\n  }\n\n  play(): void {\n    if (this.destroyed || this.isPlaying) return;\n    this.isPlaying = true;\n    this.lastTimestamp = 0;\n    this.accumulatedTime = 0;\n    this.rafId = requestAnimationFrame(this.tick);\n    this.notify();\n  }\n\n  pause(): void {\n    if (!this.isPlaying) return;\n    this.isPlaying = false;\n    if (this.rafId !== null) {\n      cancelAnimationFrame(this.rafId);\n      this.rafId = null;\n    }\n    this.notify();\n  }\n\n  stop(): void {\n    this.pause();\n    this.currentFrame = 0;\n    this.render();\n    this.notify();\n  }\n\n  goToFrame(frame: number): void {\n    const total = this.getTotalFrames();\n    this.currentFrame = Math.max(0, Math.min(frame, total - 1));\n    this.render();\n    this.options.onFrameChange?.(this.currentFrame);\n    this.notify();\n  }\n\n  getState(): SpriteAnimationState {\n    return {\n      currentFrame: this.currentFrame,\n      totalFrames: this.getTotalFrames(),\n      isPlaying: this.isPlaying,\n      isLoaded: this.isLoaded,\n    };\n  }\n\n  subscribe(listener: StateListener): () => void {\n    this.listeners.add(listener);\n    listener(this.getState());\n    return () => this.listeners.delete(listener);\n  }\n\n  updateOptions(partial: Partial<SpriteAnimationOptions>): void {\n    const prevSrc = this.options.src;\n    const prevFps = this.options.fps;\n    this.options = { ...this.options, ...partial };\n\n    if (partial.src !== undefined && partial.src !== prevSrc) {\n      this.loadImage();\n    } else if (this.isLoaded) {\n      this.render();\n    }\n\n    if (partial.fps !== undefined && partial.fps !== prevFps) {\n      this.accumulatedTime = 0;\n    }\n  }\n\n  destroy(): void {\n    this.destroyed = true;\n    this.pause();\n    this.listeners.clear();\n    if (this.target && this.options.renderer === 'css') {\n      resetCssRenderer(this.target);\n    }\n    this.target = null;\n    this.image = null;\n  }\n\n  private getTotalFrames(): number {\n    return getTotalFrames(this.options.rows, this.options.cols);\n  }\n\n  private loadImage(): void {\n    this.isLoaded = false;\n    const img = new Image();\n    img.crossOrigin = 'anonymous';\n    img.onload = () => {\n      if (this.destroyed) return;\n      this.image = img;\n      this.isLoaded = true;\n\n      if (!this.options.width || !this.options.height) {\n        const frameWidth = img.naturalWidth / this.options.cols;\n        const frameHeight = img.naturalHeight / this.options.rows;\n        this.options.width = frameWidth;\n        this.options.height = frameHeight;\n      }\n\n      this.render();\n      this.notify();\n\n      if (this.options.autoPlay && this.target) {\n        this.play();\n      }\n    };\n    img.onerror = () => {\n      console.error(`[SpriteAnimator] Failed to load image: ${this.options.src}`);\n    };\n    img.src = this.options.src;\n  }\n\n  private tick = (timestamp: number): void => {\n    if (!this.isPlaying || this.destroyed) return;\n\n    if (this.lastTimestamp === 0) {\n      this.lastTimestamp = timestamp;\n    }\n\n    const delta = timestamp - this.lastTimestamp;\n    this.lastTimestamp = timestamp;\n    this.accumulatedTime += delta;\n\n    const frameDuration = 1000 / this.options.fps;\n    while (this.accumulatedTime >= frameDuration) {\n      this.accumulatedTime -= frameDuration;\n      this.advanceFrame();\n    }\n\n    this.rafId = requestAnimationFrame(this.tick);\n  };\n\n  private advanceFrame(): void {\n    const total = this.getTotalFrames();\n    const next = this.currentFrame + 1;\n\n    if (next >= total) {\n      if (this.options.loop) {\n        this.currentFrame = 0;\n      } else {\n        this.currentFrame = total - 1;\n        this.pause();\n        this.options.onComplete?.();\n      }\n    } else {\n      this.currentFrame = next;\n    }\n\n    this.render();\n    this.options.onFrameChange?.(this.currentFrame);\n    this.notify();\n  }\n\n  private render(): void {\n    if (!this.target || !this.isLoaded) return;\n\n    const { src, rows, cols, width, height, renderer } = this.options;\n\n    if (renderer === 'canvas' && this.target instanceof HTMLCanvasElement && this.image) {\n      drawCanvasFrame(this.target, this.image, this.currentFrame, rows, cols, width, height);\n    } else if (renderer === 'css' && this.target instanceof HTMLElement) {\n      applyCssFrame(this.target, src, this.currentFrame, rows, cols, width, height);\n    }\n  }\n\n  private notify(): void {\n    const state = this.getState();\n    this.listeners.forEach((listener) => listener(state));\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,84 @@
+type RendererMode = 'css' | 'canvas';
+interface SpriteAnimationOptions {
+    /** Sprite sheet image URL (PNG, WebP, etc.) */
+    src: string;
+    /** Number of rows in the sprite sheet */
+    rows: number;
+    /** Number of columns in the sprite sheet */
+    cols: number;
+    /** Frames per second (default: 12) */
+    fps?: number;
+    /** Whether to loop the animation (default: true) */
+    loop?: boolean;
+    /** Display width in pixels */
+    width?: number;
+    /** Display height in pixels */
+    height?: number;
+    /** Start playing automatically (default: true) */
+    autoPlay?: boolean;
+    /** Rendering mode: CSS background-position or Canvas (default: 'css') */
+    renderer?: RendererMode;
+    /** Called when a non-looping animation completes */
+    onComplete?: () => void;
+    /** Called on each frame change */
+    onFrameChange?: (frame: number) => void;
+}
+interface SpriteAnimationState {
+    currentFrame: number;
+    totalFrames: number;
+    isPlaying: boolean;
+    isLoaded: boolean;
+}
+interface FramePosition {
+    row: number;
+    col: number;
+}
+
+declare const SPRITE_ANIMATION_DEFAULTS: {
+    readonly fps: 12;
+    readonly loop: true;
+    readonly width: 128;
+    readonly height: 128;
+    readonly autoPlay: true;
+    readonly renderer: RendererMode;
+};
+
+type StateListener = (state: SpriteAnimationState) => void;
+declare class SpriteAnimator {
+    private options;
+    private currentFrame;
+    private isPlaying;
+    private isLoaded;
+    private rafId;
+    private lastTimestamp;
+    private accumulatedTime;
+    private image;
+    private target;
+    private listeners;
+    private destroyed;
+    constructor(options: SpriteAnimationOptions);
+    attach(target: HTMLElement | HTMLCanvasElement): void;
+    play(): void;
+    pause(): void;
+    stop(): void;
+    goToFrame(frame: number): void;
+    getState(): SpriteAnimationState;
+    subscribe(listener: StateListener): () => void;
+    updateOptions(partial: Partial<SpriteAnimationOptions>): void;
+    destroy(): void;
+    private getTotalFrames;
+    private loadImage;
+    private tick;
+    private advanceFrame;
+    private render;
+    private notify;
+}
+
+declare function getTotalFrames(rows: number, cols: number): number;
+declare function getFramePosition(frameIndex: number, cols: number): FramePosition;
+declare function getBackgroundPositionPercent(frameIndex: number, rows: number, cols: number): {
+    x: number;
+    y: number;
+};
+
+export { type FramePosition, type RendererMode, SPRITE_ANIMATION_DEFAULTS, type SpriteAnimationOptions, type SpriteAnimationState, SpriteAnimator, getBackgroundPositionPercent, getFramePosition, getTotalFrames };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+type RendererMode = 'css' | 'canvas';
+interface SpriteAnimationOptions {
+    /** Sprite sheet image URL (PNG, WebP, etc.) */
+    src: string;
+    /** Number of rows in the sprite sheet */
+    rows: number;
+    /** Number of columns in the sprite sheet */
+    cols: number;
+    /** Frames per second (default: 12) */
+    fps?: number;
+    /** Whether to loop the animation (default: true) */
+    loop?: boolean;
+    /** Display width in pixels */
+    width?: number;
+    /** Display height in pixels */
+    height?: number;
+    /** Start playing automatically (default: true) */
+    autoPlay?: boolean;
+    /** Rendering mode: CSS background-position or Canvas (default: 'css') */
+    renderer?: RendererMode;
+    /** Called when a non-looping animation completes */
+    onComplete?: () => void;
+    /** Called on each frame change */
+    onFrameChange?: (frame: number) => void;
+}
+interface SpriteAnimationState {
+    currentFrame: number;
+    totalFrames: number;
+    isPlaying: boolean;
+    isLoaded: boolean;
+}
+interface FramePosition {
+    row: number;
+    col: number;
+}
+
+declare const SPRITE_ANIMATION_DEFAULTS: {
+    readonly fps: 12;
+    readonly loop: true;
+    readonly width: 128;
+    readonly height: 128;
+    readonly autoPlay: true;
+    readonly renderer: RendererMode;
+};
+
+type StateListener = (state: SpriteAnimationState) => void;
+declare class SpriteAnimator {
+    private options;
+    private currentFrame;
+    private isPlaying;
+    private isLoaded;
+    private rafId;
+    private lastTimestamp;
+    private accumulatedTime;
+    private image;
+    private target;
+    private listeners;
+    private destroyed;
+    constructor(options: SpriteAnimationOptions);
+    attach(target: HTMLElement | HTMLCanvasElement): void;
+    play(): void;
+    pause(): void;
+    stop(): void;
+    goToFrame(frame: number): void;
+    getState(): SpriteAnimationState;
+    subscribe(listener: StateListener): () => void;
+    updateOptions(partial: Partial<SpriteAnimationOptions>): void;
+    destroy(): void;
+    private getTotalFrames;
+    private loadImage;
+    private tick;
+    private advanceFrame;
+    private render;
+    private notify;
+}
+
+declare function getTotalFrames(rows: number, cols: number): number;
+declare function getFramePosition(frameIndex: number, cols: number): FramePosition;
+declare function getBackgroundPositionPercent(frameIndex: number, rows: number, cols: number): {
+    x: number;
+    y: number;
+};
+
+export { type FramePosition, type RendererMode, SPRITE_ANIMATION_DEFAULTS, type SpriteAnimationOptions, type SpriteAnimationState, SpriteAnimator, getBackgroundPositionPercent, getFramePosition, getTotalFrames };