@vitykovskiy/canvas-sprite-animations 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# sprite-animations
+
+`sprite-animations` is a framework-agnostic TypeScript library for 2D sprite animation on HTML canvas.
+
+The current MVP focus is deliberately narrow:
+- regular grid sprite sheets;
+- runtime playback on `CanvasRenderingContext2D`;
+- timing via `fps` and/or `duration`;
+- predictable positioning and scaling;
+- a separate playground for asset validation and config tuning.
+
+## Current package structure
+
+```text
+src/
+  core/
+    animation-player.ts
+    sprite-sheet.ts
+    index.ts
+  renderers/
+    create-canvas-sprite-renderer.ts
+    index.ts
+  types.ts
+  index.ts
+```
+
+## Public entry points
+
+- `sprite-animations`
+- `sprite-animations/core`
+- `sprite-animations/renderers`
+- `sprite-animations/types`
+
+## Public API draft
+
+```ts
+import {
+  createAnimationPlayer,
+  createCanvasSpriteRenderer,
+  createSpriteSheet,
+  loadSpriteSheetImage,
+} from "sprite-animations";
+
+const loadedImage = await loadSpriteSheetImage("/assets/hero.png");
+
+const spriteSheet = createSpriteSheet({
+  image: loadedImage.image,
+  grid: {
+    frameWidth: 64,
+    frameHeight: 64,
+    columns: 8,
+    rows: 4,
+    totalFrames: 24,
+  },
+});
+
+const player = createAnimationPlayer({
+  totalFrames: spriteSheet.getFrameCount(),
+  fps: 12,
+  duration: 1500,
+  loop: true,
+});
+
+const renderer = createCanvasSpriteRenderer();
+```
+
+## API responsibilities
+
+- `loadSpriteSheetImage(...)`
+  Loads a sprite sheet from a URL, `HTMLImageElement`, or `ImageBitmap`.
+
+- `createSpriteSheet(...)`
+  Defines the sprite grid contract and frame lookup API.
+
+- `createAnimationPlayer(...)`
+  Owns playback state and timing policy.
+
+- `createCanvasSpriteRenderer(...)`
+  Draws a resolved frame to a canvas context without owning playback state.
+
+## Timing policy
+
+- If only `fps` is set, playback advances frame-by-frame using frame duration.
+- If only `duration` is set, frames are resolved from elapsed progress across the full animation.
+- If both `fps` and `duration` are set, `duration` has priority and `fps` acts as an update-frequency cap, which means frame skipping is allowed.
+
+## Canvas rendering contract
+
+- The renderer only draws a requested frame.
+- Positioning is controlled through `{ x, y }` draw options.
+- Scaling is applied at draw time and does not mutate sprite sheet metadata.
+
+## Status
+
+This repository is in active MVP setup. The package structure and public API are defined first; asset loading, runtime behavior hardening, playground UX, and publish-ready infrastructure are tracked as separate backlog tasks.
+
+## Validation
+
+Current scaffold validation commands:
+
+```bash
+tsc --noEmit -p tsconfig.json
+npm test
+npm run playground:build
+npm pack --dry-run
+```
+
+## Playground
+
+Run the dev playground locally:
+
+```bash
+npm install
+npm run playground:dev
+```
+
+## Package workflow
+
+- `npm run build`
+  Builds library artifacts into `dist/` without bundling the playground.
+
+- `npm test`
+  Rebuilds the library and runs runtime regression tests.
+
+- `npm run check`
+  Runs typecheck, tests, and playground build as a single quality gate.
+
+- `npm run pack:check`
+  Verifies the package contents with `npm pack --dry-run`.
+
+- `npm run playground:build`
+  Emits the dev playground into `playground-dist/` so it does not overwrite library artifacts in `dist/`.

package/dist/core/animation-player.d.ts

@@ -0,0 +1,3 @@
+import type { AnimationPlayer, AnimationPlayerConfig } from "../types.js";
+export declare function createAnimationPlayer(config: AnimationPlayerConfig): AnimationPlayer;
+//# sourceMappingURL=animation-player.d.ts.map

package/dist/core/animation-player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-player.d.ts","sourceRoot":"","sources":["../../src/core/animation-player.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EAGtB,MAAM,aAAa,CAAC;AAErB,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,GAC5B,eAAe,CAoGjB"}

package/dist/core/animation-player.js

@@ -0,0 +1,118 @@
+export function createAnimationPlayer(config) {
+    const normalizedConfig = normalizeAnimationPlayerConfig(config);
+    let playbackState = "idle";
+    let elapsedMs = 0;
+    let frameIndex = normalizedConfig.initialFrame;
+    let completed = false;
+    const snapshot = () => ({
+        frameIndex,
+        elapsedMs,
+        playbackState,
+        completed,
+    });
+    return {
+        config: toPublicAnimationPlayerConfig(normalizedConfig),
+        play() {
+            playbackState = "playing";
+            completed = false;
+        },
+        pause() {
+            if (playbackState === "playing") {
+                playbackState = "paused";
+            }
+        },
+        stop() {
+            playbackState = "stopped";
+            elapsedMs = 0;
+            frameIndex = normalizedConfig.initialFrame;
+            completed = false;
+        },
+        reset() {
+            playbackState = "idle";
+            elapsedMs = 0;
+            frameIndex = normalizedConfig.initialFrame;
+            completed = false;
+        },
+        update(deltaMs) {
+            if (playbackState !== "playing" || deltaMs <= 0) {
+                return snapshot();
+            }
+            elapsedMs += deltaMs;
+            if (normalizedConfig.duration !== undefined) {
+                const duration = normalizedConfig.duration;
+                if (duration <= 0) {
+                    frameIndex = normalizedConfig.totalFrames - 1;
+                    completed = true;
+                    playbackState = normalizedConfig.loop ? "playing" : "stopped";
+                    return snapshot();
+                }
+                const cycles = elapsedMs / duration;
+                if (!normalizedConfig.loop && cycles >= 1) {
+                    frameIndex = normalizedConfig.totalFrames - 1;
+                    elapsedMs = duration;
+                    completed = true;
+                    playbackState = "stopped";
+                    return snapshot();
+                }
+                const cycleProgress = normalizedConfig.loop
+                    ? cycles - Math.floor(cycles)
+                    : Math.min(cycles, 0.999999);
+                frameIndex = Math.min(normalizedConfig.totalFrames - 1, Math.floor(cycleProgress * normalizedConfig.totalFrames));
+                return snapshot();
+            }
+            const frameDurationMs = 1000 / normalizedConfig.fps;
+            const nextFrameIndex = normalizedConfig.initialFrame +
+                Math.floor(elapsedMs / frameDurationMs);
+            if (normalizedConfig.loop) {
+                frameIndex = nextFrameIndex % normalizedConfig.totalFrames;
+                return snapshot();
+            }
+            if (nextFrameIndex >= normalizedConfig.totalFrames) {
+                frameIndex = normalizedConfig.totalFrames - 1;
+                completed = true;
+                playbackState = "stopped";
+                return snapshot();
+            }
+            frameIndex = nextFrameIndex;
+            return snapshot();
+        },
+        getSnapshot() {
+            return snapshot();
+        },
+    };
+}
+function normalizeAnimationPlayerConfig(config) {
+    if (!Number.isInteger(config.totalFrames) || config.totalFrames <= 0) {
+        throw new Error("Animation player requires a positive integer totalFrames.");
+    }
+    if (config.fps !== undefined && config.fps <= 0) {
+        throw new Error("fps must be greater than 0 when provided.");
+    }
+    if (config.duration !== undefined && config.duration < 0) {
+        throw new Error("duration must be greater than or equal to 0 when provided.");
+    }
+    const initialFrame = config.initialFrame ?? 0;
+    if (!Number.isInteger(initialFrame) || initialFrame < 0) {
+        throw new Error("initialFrame must be a non-negative integer.");
+    }
+    if (initialFrame >= config.totalFrames) {
+        throw new Error("initialFrame must be less than totalFrames.");
+    }
+    return Object.freeze({
+        totalFrames: config.totalFrames,
+        initialFrame,
+        fps: config.fps ?? 12,
+        duration: config.duration,
+        loop: config.loop ?? true,
+    });
+}
+function toPublicAnimationPlayerConfig(config) {
+    return Object.freeze({
+        totalFrames: config.totalFrames,
+        initialFrame: config.initialFrame,
+        fps: config.fps,
+        ...(config.duration === undefined ? {} : { duration: config.duration }),
+        loop: config.loop,
+    });
+}
+//# sourceMappingURL=animation-player.js.map

package/dist/core/animation-player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-player.js","sourceRoot":"","sources":["../../src/core/animation-player.ts"],"names":[],"mappings":"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"}

package/dist/core/asset-loader.d.ts

@@ -0,0 +1,3 @@
+import type { LoadedSpriteSheetImage, LoadSpriteSheetImageOptions, SpriteSheetImageSource } from "../types.js";
+export declare function loadSpriteSheetImage(source: SpriteSheetImageSource, options?: LoadSpriteSheetImageOptions): Promise<LoadedSpriteSheetImage>;
+//# sourceMappingURL=asset-loader.d.ts.map

package/dist/core/asset-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-loader.d.ts","sourceRoot":"","sources":["../../src/core/asset-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,sBAAsB,CAAC,CAoBjC"}

package/dist/core/asset-loader.js

@@ -0,0 +1,56 @@
+export async function loadSpriteSheetImage(source, options = {}) {
+    if (typeof source === "string") {
+        return loadImageFromUrl(source, options);
+    }
+    if (isImageBitmap(source)) {
+        return {
+            image: source,
+            width: source.width,
+            height: source.height,
+        };
+    }
+    await waitForImageElement(source);
+    return {
+        image: source,
+        width: source.naturalWidth,
+        height: source.naturalHeight,
+    };
+}
+async function loadImageFromUrl(url, options) {
+    const image = new Image();
+    if (options.crossOrigin !== undefined) {
+        image.crossOrigin = options.crossOrigin;
+    }
+    image.src = url;
+    await waitForImageElement(image);
+    return {
+        image,
+        width: image.naturalWidth,
+        height: image.naturalHeight,
+    };
+}
+function waitForImageElement(image) {
+    if (image.complete && image.naturalWidth > 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const handleLoad = () => {
+            cleanup();
+            resolve();
+        };
+        const handleError = () => {
+            cleanup();
+            reject(new Error("Failed to load sprite sheet image."));
+        };
+        const cleanup = () => {
+            image.removeEventListener("load", handleLoad);
+            image.removeEventListener("error", handleError);
+        };
+        image.addEventListener("load", handleLoad, { once: true });
+        image.addEventListener("error", handleError, { once: true });
+    });
+}
+function isImageBitmap(value) {
+    return typeof ImageBitmap !== "undefined" && value instanceof ImageBitmap;
+}
+//# sourceMappingURL=asset-loader.js.map

package/dist/core/asset-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-loader.js","sourceRoot":"","sources":["../../src/core/asset-loader.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAA8B,EAC9B,UAAuC,EAAE;IAEzC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,KAAK,EAAE,MAAM;YACb,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC;IACJ,CAAC;IAED,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAElC,OAAO;QACL,KAAK,EAAE,MAAM;QACb,KAAK,EAAE,MAAM,CAAC,YAAY;QAC1B,MAAM,EAAE,MAAM,CAAC,aAAa;KAC7B,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,gBAAgB,CAC7B,GAAW,EACX,OAAoC;IAEpC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;IAE1B,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACtC,KAAK,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC;IAEhB,MAAM,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAEjC,OAAO;QACL,KAAK;QACL,KAAK,EAAE,KAAK,CAAC,YAAY;QACzB,MAAM,EAAE,KAAK,CAAC,aAAa;KAC5B,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAuB;IAClD,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;QAC7C,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,UAAU,GAAG,GAAG,EAAE;YACtB,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QAEF,MAAM,WAAW,GAAG,GAAG,EAAE;YACvB,OAAO,EAAE,CAAC;YACV,MAAM,CAAC,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC,CAAC;QAC1D,CAAC,CAAC;QAEF,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,KAAK,CAAC,mBAAmB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAC9C,KAAK,CAAC,mBAAmB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAClD,CAAC,CAAC;QAEF,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,KAA6B;IAClD,OAAO,OAAO,WAAW,KAAK,WAAW,IAAI,KAAK,YAAY,WAAW,CAAC;AAC5E,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { createSpriteSheet } from "./sprite-sheet.js";
+export { createAnimationPlayer } from "./animation-player.js";
+export { loadSpriteSheetImage } from "./asset-loader.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,4 @@
+export { createSpriteSheet } from "./sprite-sheet.js";
+export { createAnimationPlayer } from "./animation-player.js";
+export { loadSpriteSheetImage } from "./asset-loader.js";
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/core/sprite-sheet.d.ts

@@ -0,0 +1,3 @@
+import type { SpriteSheet, SpriteSheetConfig } from "../types.js";
+export declare function createSpriteSheet(config: SpriteSheetConfig): SpriteSheet;
+//# sourceMappingURL=sprite-sheet.d.ts.map

package/dist/core/sprite-sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-sheet.d.ts","sourceRoot":"","sources":["../../src/core/sprite-sheet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE7E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAaxE"}

package/dist/core/sprite-sheet.js

@@ -0,0 +1,57 @@
+export function createSpriteSheet(config) {
+    const normalizedGrid = normalizeGrid(config);
+    return {
+        image: config.image,
+        grid: normalizedGrid,
+        getFrameCount() {
+            return normalizedGrid.totalFrames;
+        },
+        getFrameRect(frameIndex) {
+            return getFrameRect(normalizedGrid, frameIndex);
+        },
+    };
+}
+function normalizeGrid(config) {
+    const { frameWidth, frameHeight, columns, rows } = config.grid;
+    if (frameWidth <= 0 || frameHeight <= 0) {
+        throw new Error("frameWidth and frameHeight must be greater than 0.");
+    }
+    if (!Number.isInteger(columns) || columns <= 0) {
+        throw new Error("columns must be a positive integer.");
+    }
+    if (!Number.isInteger(rows) || rows <= 0) {
+        throw new Error("rows must be a positive integer.");
+    }
+    const totalFrames = config.grid.totalFrames ?? columns * rows;
+    if (!Number.isInteger(totalFrames) || totalFrames <= 0) {
+        throw new Error("totalFrames must be a positive integer when provided.");
+    }
+    if (totalFrames > columns * rows) {
+        throw new Error("totalFrames cannot exceed the capacity of the sprite sheet grid.");
+    }
+    return {
+        frameWidth,
+        frameHeight,
+        columns,
+        rows,
+        totalFrames,
+    };
+}
+function getFrameRect(grid, frameIndex) {
+    if (!Number.isInteger(frameIndex) || frameIndex < 0) {
+        throw new Error("frameIndex must be a non-negative integer.");
+    }
+    if (frameIndex >= grid.totalFrames) {
+        throw new Error("frameIndex is outside the configured totalFrames range.");
+    }
+    const columnIndex = frameIndex % grid.columns;
+    const rowIndex = Math.floor(frameIndex / grid.columns);
+    return {
+        x: columnIndex * grid.frameWidth,
+        y: rowIndex * grid.frameHeight,
+        width: grid.frameWidth,
+        height: grid.frameHeight,
+        index: frameIndex,
+    };
+}
+//# sourceMappingURL=sprite-sheet.js.map

package/dist/core/sprite-sheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-sheet.js","sourceRoot":"","sources":["../../src/core/sprite-sheet.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,iBAAiB,CAAC,MAAyB;IACzD,MAAM,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAE7C,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,IAAI,EAAE,cAAc;QACpB,aAAa;YACX,OAAO,cAAc,CAAC,WAAW,CAAC;QACpC,CAAC;QACD,YAAY,CAAC,UAAU;YACrB,OAAO,YAAY,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;QAClD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,MAAyB;IAC9C,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC;IAE/D,IAAI,UAAU,IAAI,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,OAAO,GAAG,IAAI,CAAC;IAE9D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,WAAW,GAAG,OAAO,GAAG,IAAI,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;IACtF,CAAC;IAED,OAAO;QACL,UAAU;QACV,WAAW;QACX,OAAO;QACP,IAAI;QACJ,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CACnB,IAAyC,EACzC,UAAkB;IAElB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAEvD,OAAO;QACL,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC,UAAU;QAChC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,WAAW;QAC9B,KAAK,EAAE,IAAI,CAAC,UAAU;QACtB,MAAM,EAAE,IAAI,CAAC,WAAW;QACxB,KAAK,EAAE,UAAU;KAClB,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./core/index.js";
+export * from "./renderers/index.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./core/index.js";
+export * from "./renderers/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}

package/dist/renderers/create-canvas-sprite-renderer.d.ts

@@ -0,0 +1,3 @@
+import type { CanvasSpriteRenderer } from "../types.js";
+export declare function createCanvasSpriteRenderer(): CanvasSpriteRenderer;
+//# sourceMappingURL=create-canvas-sprite-renderer.d.ts.map

package/dist/renderers/create-canvas-sprite-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-canvas-sprite-renderer.d.ts","sourceRoot":"","sources":["../../src/renderers/create-canvas-sprite-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAGrB,MAAM,aAAa,CAAC;AAErB,wBAAgB,0BAA0B,IAAI,oBAAoB,CA0BjE"}

package/dist/renderers/create-canvas-sprite-renderer.js

@@ -0,0 +1,12 @@
+export function createCanvasSpriteRenderer() {
+    return {
+        draw(context, spriteSheet, options) {
+            const frame = spriteSheet.getFrameRect(options.frameIndex);
+            const scale = options.scale ?? 1;
+            const destinationWidth = options.destinationWidth ?? frame.width * scale;
+            const destinationHeight = options.destinationHeight ?? frame.height * scale;
+            context.drawImage(spriteSheet.image, frame.x, frame.y, frame.width, frame.height, options.position.x, options.position.y, destinationWidth, destinationHeight);
+        },
+    };
+}
+//# sourceMappingURL=create-canvas-sprite-renderer.js.map

package/dist/renderers/create-canvas-sprite-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-canvas-sprite-renderer.js","sourceRoot":"","sources":["../../src/renderers/create-canvas-sprite-renderer.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,0BAA0B;IACxC,OAAO;QACL,IAAI,CACF,OAAiC,EACjC,WAAwB,EACxB,OAA0B;YAE1B,MAAM,KAAK,GAAG,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;YACjC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;YACzE,MAAM,iBAAiB,GACrB,OAAO,CAAC,iBAAiB,IAAI,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC;YAEpD,OAAO,CAAC,SAAS,CACf,WAAW,CAAC,KAAK,EACjB,KAAK,CAAC,CAAC,EACP,KAAK,CAAC,CAAC,EACP,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,MAAM,EACZ,OAAO,CAAC,QAAQ,CAAC,CAAC,EAClB,OAAO,CAAC,QAAQ,CAAC,CAAC,EAClB,gBAAgB,EAChB,iBAAiB,CAClB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/renderers/index.d.ts

@@ -0,0 +1,2 @@
+export { createCanvasSpriteRenderer } from "./create-canvas-sprite-renderer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/renderers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/renderers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/renderers/index.js

@@ -0,0 +1,2 @@
+export { createCanvasSpriteRenderer } from "./create-canvas-sprite-renderer.js";
+//# sourceMappingURL=index.js.map

package/dist/renderers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/renderers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+export interface SpriteSheetGrid {
+    frameWidth: number;
+    frameHeight: number;
+    columns: number;
+    rows: number;
+    totalFrames?: number;
+}
+export type SpriteSheetImageSource = string | HTMLImageElement | ImageBitmap;
+export interface LoadSpriteSheetImageOptions {
+    crossOrigin?: string;
+}
+export interface LoadedSpriteSheetImage {
+    image: HTMLImageElement | ImageBitmap;
+    width: number;
+    height: number;
+}
+export interface SpriteSheetConfig {
+    image: CanvasImageSource;
+    grid: SpriteSheetGrid;
+}
+export interface FrameRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    index: number;
+}
+export interface SpriteSheet {
+    readonly image: CanvasImageSource;
+    readonly grid: Required<SpriteSheetGrid>;
+    getFrameCount(): number;
+    getFrameRect(frameIndex: number): FrameRect;
+}
+export interface AnimationTimingConfig {
+    fps?: number;
+    duration?: number;
+    loop?: boolean;
+}
+export interface AnimationPlayerConfig extends AnimationTimingConfig {
+    totalFrames: number;
+    initialFrame?: number;
+}
+export type AnimationPlaybackState = "idle" | "playing" | "paused" | "stopped";
+export interface AnimationSnapshot {
+    frameIndex: number;
+    elapsedMs: number;
+    playbackState: AnimationPlaybackState;
+    completed: boolean;
+}
+export interface AnimationPlayer {
+    readonly config: Readonly<AnimationPlayerConfig>;
+    play(): void;
+    pause(): void;
+    stop(): void;
+    reset(): void;
+    update(deltaMs: number): AnimationSnapshot;
+    getSnapshot(): AnimationSnapshot;
+}
+export interface RenderPosition {
+    x: number;
+    y: number;
+}
+export interface DrawSpriteOptions {
+    scale?: number;
+    position: RenderPosition;
+    frameIndex: number;
+    destinationWidth?: number;
+    destinationHeight?: number;
+}
+export interface CanvasSpriteRenderer {
+    draw(context: CanvasRenderingContext2D, spriteSheet: SpriteSheet, options: DrawSpriteOptions): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAE7E,MAAM,WAAW,2BAA2B;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,iBAAiB,CAAC;IACzB,IAAI,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IACzC,aAAa,IAAI,MAAM,CAAC;IACxB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,qBAAsB,SAAQ,qBAAqB;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,sBAAsB,CAAC;IACtC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IACjD,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAAC;IAC3C,WAAW,IAAI,iBAAiB,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CACF,OAAO,EAAE,wBAAwB,EACjC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,iBAAiB,GACzB,IAAI,CAAC;CACT"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@vitykovskiy/canvas-sprite-animations",
+  "version": "0.1.0",
+  "description": "Framework-agnostic sprite animation library for HTML canvas.",
+  "type": "module",
+  "private": false,
+  "packageManager": "npm@11.6.1",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./renderers": {
+      "types": "./dist/renderers/index.d.ts",
+      "import": "./dist/renderers/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"import('node:fs/promises').then(fs => fs.rm('dist', { recursive: true, force: true }))\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "build:types": "tsc -p tsconfig.build.json",
+    "test": "npm run build && node --test tests/**/*.test.mjs",
+    "playground:dev": "vite",
+    "playground:build": "vite build --outDir playground-dist",
+    "check": "npm run typecheck && npm test && npm run playground:build",
+    "pack:check": "npm pack --dry-run",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "sprite",
+    "animation",
+    "canvas",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vitykovskiy/sprite-animations.git"
+  },
+  "homepage": "https://github.com/Vitykovskiy/sprite-animations",
+  "bugs": {
+    "url": "https://github.com/Vitykovskiy/sprite-animations/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "vite": "^7.1.5"
+  }
+}