@dava96/osrs-icons 1.0.16 → 1.0.17

package/LICENSE

@@ -0,0 +1,25 @@
+Attribution — NonCommercial — ShareAlike 3.0 Unported
+(CC BY-NC-SA 3.0)
+
+Full licence text: https://creativecommons.org/licenses/by-nc-sa/3.0/legalcode
+
+You are free to:
+
+  Share — copy and redistribute the material in any medium or format.
+  Adapt — remix, transform, and build upon the material.
+
+Under the following terms:
+
+  Attribution — You must give appropriate credit, provide a link to
+  the licence, and indicate if changes were made.
+
+  NonCommercial — You may not use the material for commercial purposes.
+
+  ShareAlike — If you remix, transform, or build upon the material, you
+  must distribute your contributions under the same licence.
+
+---
+
+This project is not affiliated with Jagex Ltd.
+OSRS icons are sourced from the Old School RuneScape Wiki and are the
+property of Jagex / the Wiki contributors.

package/README.md

@@ -8,12 +8,47 @@ Designed for easy integration with modern web apps, with full tree-shaking suppo
 [![license](https://img.shields.io/npm/l/@dava96/osrs-icons)](./LICENSE)
 [![GitHub stars](https://img.shields.io/github/stars/Dava96/osrs-icons)](https://github.com/Dava96/osrs-icons)
 
+📖 **[Browse icons & build packs →](https://dava96.github.io/osrs-icons/)**
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [CSS Cursor](#css-cursor-tree-shaking-supported)
+  - [As an Image](#as-an-image)
+  - [Icon Discovery](#icon-discovery)
+  - [CDN (No Build Step)](#cdn-usage-no-build-step)
+- [Cursor Packs](#cursor-packs)
+- [Utilities](#utilities)
+  - [flipCursor](#flip-cursor)
+  - [applyCursors](#apply-cursors)
+  - [errorCursor](#error-cursor-)
+- [API Reference](#api-reference)
+- [Browser Compatibility](#browser-compatibility)
+- [How It Works](#how-it-works)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 ```bash
 npm install @dava96/osrs-icons
 ```
 
+## Quick Start
+
+```tsx
+import { abyssalWhip } from '@dava96/osrs-icons';
+
+// As a cursor
+<div style={{ cursor: abyssalWhip }}>Hover me!</div>;
+
+// As an image
+import { toDataUrl } from '@dava96/osrs-icons';
+<img src={toDataUrl(abyssalWhip)} alt="Abyssal Whip" />;
+```
+
 ## Usage
 
 ### CSS Cursor (Tree-Shaking Supported)
@@ -38,7 +73,7 @@ Use the `toDataUrl` helper to extract the raw data URL for use outside of CSS:
 import { abyssalWhip, dragonScimitar, toDataUrl } from '@dava96/osrs-icons';
 
 // Single icon
-<img src={toDataUrl(abyssalWhip)} alt="Abyssal Whip" />
+<img src={toDataUrl(abyssalWhip)} alt="Abyssal Whip" />;
 
 // Multiple icons at once
 const urls = toDataUrl({
@@ -57,10 +92,12 @@ Browse all available icons programmatically with `iconNames`, or restrict values
 import { iconNames, type IconName } from '@dava96/osrs-icons';
 
 // Search / autocomplete
-const results = iconNames.filter(name => name.includes('dragon'));
+const results = iconNames.filter((name) => name.includes('dragon'));
 
 // Type-safe icon references
-function setCustomCursor(name: IconName) { /* ... */ }
+function setCustomCursor(name: IconName) {
+  /* ... */
+}
 ```
 
 ### CDN Usage (No Build Step)
@@ -70,52 +107,52 @@ You can use the package directly in the browser via ESM.sh:
 ```html
 <script type="module">
   import { AbyssalWhip } from 'https://esm.sh/@dava96/osrs-icons';
-  
+
   document.body.style.cursor = AbyssalWhip;
 </script>
 ```
 
-### Cursor Packs
+## Cursor Packs
 
 Pre-built thematic icon groups — each pack groups related icons by their in-game state:
 
 ```ts
-import { sharkPack, dragonDaggerPack, bucketPack } from '@dava96/osrs-icons';
-
-// Fish: raw → cooked → burnt
-element.style.cursor = sharkPack.cooked;
+import { runePack, bucketPack, coinsPack } from '@dava96/osrs-icons';
 
-// Dragon dagger: base → poisoned → p+ → p++
-element.style.cursor = dragonDaggerPack.poisonedPlusPlus;
+// Rune pack — all 10 F2P runes
+element.style.cursor = runePack.air;
 
 // Bucket fill progression — great for loading states
 const stages = bucketPack.stages; // [empty, 1/5, 2/5, 3/5, 4/5, full]
-const index = Math.min(Math.floor(progress / 100 * stages.length), stages.length - 1);
+const index = Math.min(Math.floor((progress / 100) * stages.length), stages.length - 1);
 element.style.cursor = stages[index];
 ```
 
 **Available packs:**
 
-| Pack | Keys |
-|------|------|
-| `sharkPack` | `raw`, `cooked`, `burnt` |
-| `herringPack` | `raw`, `cooked`, `burnt`, `error` |
-| `anglerfishPack` | `raw`, `cooked`, `burnt` |
-| `dragonDaggerPack` | `base`, `poisoned`, `poisonedPlus`, `poisonedPlusPlus` |
-| `goldPack` | `ore`, `bar` |
-| `ironPack` | `ore`, `bar` |
-| `coinsPack` | `_1` to `_10000` + `stages[]` |
-| `bucketPack` | `empty` to `full` + `stages[]` |
+| Pack         | Keys                                                                                            |
+| ------------ | ----------------------------------------------------------------------------------------------- |
+| `coinsPack`  | `_1` to `_10000` + `stages[]`                                                                   |
+| `bucketPack` | `empty` to `full` + `stages[]`                                                                  |
+| `runePack`   | `air`, `fire`, `water`, `earth`, `chaos`, `mind`, `death`, `law`, `nature`, `body` + `stages[]` |
+
+## Utilities
 
 ### Flip Cursor
 
-Many OSRS icons face right, but cursors typically point left. Flip any icon horizontally at runtime:
+Many OSRS icons face right, but cursors typically point left. Flip one icon, an array, or an entire pack:
 
 ```ts
-import { abyssalWhip, flipCursor } from '@dava96/osrs-icons';
+import { abyssalWhip, runePack, flipCursor } from '@dava96/osrs-icons';
 
+// Single icon
 const leftFacing = await flipCursor(abyssalWhip);
-document.body.style.cursor = leftFacing;
+
+// Array of icons
+const [flippedAir, flippedFire] = await flipCursor([runePack.air, runePack.fire]);
+
+// Entire pack — flips all values and stages in one call
+const flippedRunes = await flipCursor(runePack);
 ```
 
 Results are cached internally — flipping the same icon twice returns instantly. Browser-only (uses Canvas API); returns the original value in Node.js/SSR.
@@ -154,6 +191,45 @@ import { errorCursor } from '@dava96/osrs-icons';
 element.style.cursor = errorCursor;
 ```
 
+## API Reference
+
+### Types
+
+| Type            | Description                                                                                |
+| --------------- | ------------------------------------------------------------------------------------------ |
+| `IconName`      | Union of all valid icon name strings (for type-safe references)                            |
+| `CursorMapping` | `Partial<Record<CursorState, string>>` — maps CSS cursor states to icon values             |
+| `CursorState`   | `'default' \| 'pointer' \| 'wait' \| 'text' \| 'move' \| ...` — standard CSS cursor states |
+
+### Functions
+
+| Function       | Signature                                                     | Description                                                                              |
+| -------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `toDataUrl`    | `(cursor: string) → string`                                   | Extracts the raw `data:image/png;base64,...` URL from a CSS cursor value                 |
+| `toDataUrl`    | `(cursors: Record<K, string>) → Record<K, string>`            | Batch version — extracts URLs from multiple cursor values                                |
+| `flipCursor`   | `(cursor: string) → Promise<string>`                          | Horizontally flips a cursor icon at runtime via Canvas API. Cached. Browser-only.        |
+| `applyCursors` | `(mapping: CursorMapping, target?: HTMLElement) → () => void` | Injects a `<style>` tag mapping cursor states to OSRS icons. Returns a cleanup function. |
+
+### Constants
+
+| Export        | Type                     | Description                                                |
+| ------------- | ------------------------ | ---------------------------------------------------------- |
+| `iconNames`   | `readonly string[]`      | Array of all available icon name strings                   |
+| `errorCursor` | `string`                 | Semantic alias for `redHerring`                            |
+| `*Pack`       | `Record<string, string>` | Pre-built cursor packs (see [Cursor Packs](#cursor-packs)) |
+
+## Browser Compatibility
+
+| Feature        | Browser                | Node.js / SSR             |
+| -------------- | ---------------------- | ------------------------- |
+| Icon imports   | ✅ All                 | ✅ All                    |
+| `toDataUrl`    | ✅ All                 | ✅ All                    |
+| `applyCursors` | ✅ All modern          | ⚠️ Returns no-op cleanup  |
+| `flipCursor`   | ✅ Canvas API required | ⚠️ Returns original value |
+| Cursor packs   | ✅ All                 | ✅ All                    |
+
+All features are SSR-safe — browser-only features degrade gracefully in Node.js environments by returning safe fallback values.
+
 ## How It Works
 
 The build script fetches every inventory sprite (~17,400 icons) from the
@@ -162,9 +238,19 @@ compresses them as palette PNGs, and generates a TypeScript file of named export
 
 Each icon is a small ~32×32 pixel sprite, base64-encoded inline — no external assets to host.
 
+### Package Output
+
+| Format | Path                  | Use                                  |
+| ------ | --------------------- | ------------------------------------ |
+| ESM    | `dist/esm/index.js`   | `import` (bundlers, modern browsers) |
+| CJS    | `dist/cjs/index.js`   | `require()` (Node.js, legacy)        |
+| Types  | `dist/cjs/index.d.ts` | TypeScript definitions               |
+
+The package has `"sideEffects": false` for optimal tree-shaking in Webpack, Rollup, Vite, and esbuild.
+
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on updating icons and publishing new versions.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on local development, updating icons, and publishing new versions.
 
 ## License
 

package/dist/cjs/animateCursor.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Options for {@link animateCursor}.
+ */
+export interface AnimateCursorOptions {
+    /**
+     * Total duration of one full animation cycle in milliseconds.
+     * Each frame occupies `duration / frames.length` of the cycle.
+     *
+     * @default 1000
+     */
+    duration?: number;
+    /**
+     * Element to scope the animated cursor to.
+     * When omitted the cursor animates on the entire page (`*`).
+     */
+    target?: HTMLElement;
+    /**
+     * How many times the cycle should repeat.
+     * Use `Infinity` (the default) for a continuous loop.
+     *
+     * @default Infinity
+     */
+    iterations?: number;
+}
+/**
+ * Animates a cursor by cycling through an ordered array of OSRS icon
+ * strings using a pure‑CSS `@keyframes` rule.
+ *
+ * Each frame is assigned an equal slice of the total `duration` and
+ * transitions are **discrete** (`step-end`), producing a clean
+ * frame‑by‑frame sprite animation — no JavaScript timers required.
+ *
+ * **Browser‑only** — in non‑browser environments (Node / SSR) this
+ * is a no‑op that returns an empty cleanup function.
+ *
+ * @param frames  - An ordered array of CSS cursor strings (≥ 2).
+ * @param options - Optional configuration for duration, target, and iterations.
+ * @returns A cleanup function that removes the injected styles and
+ *          stops the animation.
+ *
+ * @throws {Error} If fewer than 2 frames are provided.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   coins1, coins2, coins3, coins4, coins5,
+ *   animateCursor,
+ * } from '@dava96/osrs-icons';
+ *
+ * // Animate a growing coin stack on the whole page
+ * const stop = animateCursor(
+ *   [coins1, coins2, coins3, coins4, coins5],
+ *   { duration: 1200 },
+ * );
+ *
+ * // Later, stop the animation and clean up
+ * stop();
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { lobsterRaw, lobsterCooked, lobsterBurnt, animateCursor } from '@dava96/osrs-icons';
+ *
+ * // Scope to a specific element, play 3 times
+ * const stop = animateCursor(
+ *   [lobsterRaw, lobsterCooked, lobsterBurnt],
+ *   { duration: 900, target: document.getElementById('cooking')!, iterations: 3 },
+ * );
+ * ```
+ */
+export declare function animateCursor(frames: string[], options?: AnimateCursorOptions): () => void;
+//# sourceMappingURL=animateCursor.d.ts.map

package/dist/cjs/animateCursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animateCursor.d.ts","sourceRoot":"","sources":["../../src/animateCursor.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,IAAI,CAiD9F"}

package/dist/cjs/animateCursor.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.animateCursor = animateCursor;
+/**
+ * Animates a cursor by cycling through an ordered array of OSRS icon
+ * strings using a pure‑CSS `@keyframes` rule.
+ *
+ * Each frame is assigned an equal slice of the total `duration` and
+ * transitions are **discrete** (`step-end`), producing a clean
+ * frame‑by‑frame sprite animation — no JavaScript timers required.
+ *
+ * **Browser‑only** — in non‑browser environments (Node / SSR) this
+ * is a no‑op that returns an empty cleanup function.
+ *
+ * @param frames  - An ordered array of CSS cursor strings (≥ 2).
+ * @param options - Optional configuration for duration, target, and iterations.
+ * @returns A cleanup function that removes the injected styles and
+ *          stops the animation.
+ *
+ * @throws {Error} If fewer than 2 frames are provided.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   coins1, coins2, coins3, coins4, coins5,
+ *   animateCursor,
+ * } from '@dava96/osrs-icons';
+ *
+ * // Animate a growing coin stack on the whole page
+ * const stop = animateCursor(
+ *   [coins1, coins2, coins3, coins4, coins5],
+ *   { duration: 1200 },
+ * );
+ *
+ * // Later, stop the animation and clean up
+ * stop();
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { lobsterRaw, lobsterCooked, lobsterBurnt, animateCursor } from '@dava96/osrs-icons';
+ *
+ * // Scope to a specific element, play 3 times
+ * const stop = animateCursor(
+ *   [lobsterRaw, lobsterCooked, lobsterBurnt],
+ *   { duration: 900, target: document.getElementById('cooking')!, iterations: 3 },
+ * );
+ * ```
+ */
+function animateCursor(frames, options = {}) {
+    if (frames.length < 2) {
+        throw new Error(`animateCursor requires at least 2 frames, received ${frames.length}.`);
+    }
+    if (typeof document === 'undefined') {
+        return () => { };
+    }
+    const { duration = 1000, target, iterations = Infinity } = options;
+    const animationName = generateAnimationName();
+    const scopeId = `${animationName}-scope`;
+    const selector = target ? `[data-osrs-anim-id="${scopeId}"]` : '*';
+    if (target) {
+        target.setAttribute('data-osrs-anim-id', scopeId);
+    }
+    const keyframeSteps = frames
+        .map((cursorValue, index) => {
+        const percentage = ((index / frames.length) * 100).toFixed(2);
+        return `  ${percentage}% { cursor: ${cursorValue}; }`;
+    })
+        .join('\n');
+    const iterationCount = iterations === Infinity ? 'infinite' : String(iterations);
+    const css = [
+        `@keyframes ${animationName} {`,
+        keyframeSteps,
+        '}',
+        `${selector} {`,
+        `  animation: ${animationName} ${duration}ms step-end ${iterationCount};`,
+        '}',
+    ].join('\n');
+    const styleElement = document.createElement('style');
+    styleElement.textContent = css;
+    styleElement.setAttribute('data-osrs-animate', 'true');
+    document.head.appendChild(styleElement);
+    return () => {
+        styleElement.remove();
+        if (target) {
+            target.removeAttribute('data-osrs-anim-id');
+        }
+    };
+}
+/** Generates a short unique ID for animation scoping. */
+let animCounter = 0;
+function generateAnimationName() {
+    return `osrs-anim-${++animCounter}-${Date.now().toString(36)}`;
+}

package/dist/cjs/applyCursors.d.ts

@@ -61,3 +61,4 @@ export type CursorMapping = Partial<Record<CursorState, string>>;
  * ```
  */
 export declare function applyCursors(mapping: CursorMapping, target?: HTMLElement): () => void;
+//# sourceMappingURL=applyCursors.d.ts.map

package/dist/cjs/applyCursors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyCursors.d.ts","sourceRoot":"","sources":["../../src/applyCursors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,SAAS,GACT,MAAM,GACN,MAAM,GACN,MAAM,GACN,WAAW,GACX,MAAM,GACN,UAAU,GACV,aAAa,GACb,MAAM,GACN,UAAU,GACV,MAAM,GACN,MAAM,GACN,OAAO,GACP,SAAS,GACT,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,UAAU,GACV,UAAU,GACV,UAAU,GACV,SAAS,GACT,UAAU,CAAC;AAEf;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,IAAI,CA6BrF"}

package/dist/cjs/flip.d.ts

@@ -1,33 +1,55 @@
 /**
- * Horizontally flips a CSS cursor icon so it points in the opposite direction.
+ * Horizontally flips CSS cursor icons so they point in the opposite direction.
  *
  * Many OSRS inventory icons face right, but cursor conventions typically
  * expect left-facing images. This helper mirrors the embedded base64 PNG
- * using the Canvas API and returns a new, ready-to-use CSS cursor string.
+ * using the Canvas API and returns new, ready-to-use CSS cursor strings.
  *
  * Results are cached internally — flipping the same icon twice returns
  * the cached value instantly.
  *
  * **Browser-only** — requires the Canvas API. In non-browser environments
- * (Node.js, SSR) the original cursor string is returned unchanged.
+ * (Node.js, SSR) the original cursor strings are returned unchanged.
  *
- * @param cursorValue - A CSS cursor string (e.g. `url('data:image/png;base64,...'), auto`).
- * @returns A promise that resolves to a new cursor string with the image flipped.
+ * Supports three input shapes:
+ * - **Single string** → returns a single flipped string.
+ * - **Array of strings** → returns an array of flipped strings (same order).
+ * - **Record of strings** → returns a record with the same keys, values flipped.
+ *   Perfect for flipping an entire pack in one call.
  *
  * @example
  * ```ts
  * import { abyssalWhip, flipCursor } from '@dava96/osrs-icons';
  *
- * const leftFacingWhip = await flipCursor(abyssalWhip);
- * document.body.style.cursor = leftFacingWhip;
+ * // Single icon
+ * const flipped = await flipCursor(abyssalWhip);
+ * document.body.style.cursor = flipped;
  * ```
  *
  * @example
  * ```ts
- * import { dragonDaggerPack, flipCursor } from '@dava96/osrs-icons';
+ * import { coinsPack, flipCursor } from '@dava96/osrs-icons';
  *
  * // Flip an entire pack
- * const flippedDagger = await flipCursor(dragonDaggerPack.base);
+ * const flippedPack = await flipCursor(coinsPack);
+ * // flippedPack._1, flippedPack._2, ... are all flipped
+ * // flippedPack.stages is a flipped array
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { airRune, fireRune, flipCursor } from '@dava96/osrs-icons';
+ *
+ * // Flip an array of cursors
+ * const [flippedAir, flippedFire] = await flipCursor([airRune, fireRune]);
  * ```
  */
+/** Flip a single CSS cursor string. */
 export declare function flipCursor(cursorValue: string): Promise<string>;
+/** Flip an array of CSS cursor strings, preserving order. */
+export declare function flipCursor(cursorValues: readonly string[]): Promise<string[]>;
+/** Flip every string value in a record (e.g. a pack object), preserving keys. */
+export declare function flipCursor<T extends Record<string, unknown>>(pack: T): Promise<{
+    [K in keyof T]: T[K] extends string ? string : T[K] extends readonly string[] ? string[] : T[K];
+}>;
+//# sourceMappingURL=flip.d.ts.map

package/dist/cjs/flip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flip.d.ts","sourceRoot":"","sources":["../../src/flip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAUH,uCAAuC;AACvC,wBAAsB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEvE,6DAA6D;AAC7D,wBAAsB,UAAU,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAErF,iFAAiF;AACjF,wBAAsB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,IAAI,EAAE,CAAC,GACN,OAAO,CAAC;KACR,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;CAChG,CAAC,CAAC"}

package/dist/cjs/flip.js

@@ -1,46 +1,86 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.flipCursor = flipCursor;
 /**
- * Horizontally flips a CSS cursor icon so it points in the opposite direction.
+ * Horizontally flips CSS cursor icons so they point in the opposite direction.
  *
  * Many OSRS inventory icons face right, but cursor conventions typically
  * expect left-facing images. This helper mirrors the embedded base64 PNG
- * using the Canvas API and returns a new, ready-to-use CSS cursor string.
+ * using the Canvas API and returns new, ready-to-use CSS cursor strings.
  *
  * Results are cached internally — flipping the same icon twice returns
  * the cached value instantly.
  *
  * **Browser-only** — requires the Canvas API. In non-browser environments
- * (Node.js, SSR) the original cursor string is returned unchanged.
+ * (Node.js, SSR) the original cursor strings are returned unchanged.
  *
- * @param cursorValue - A CSS cursor string (e.g. `url('data:image/png;base64,...'), auto`).
- * @returns A promise that resolves to a new cursor string with the image flipped.
+ * Supports three input shapes:
+ * - **Single string** → returns a single flipped string.
+ * - **Array of strings** → returns an array of flipped strings (same order).
+ * - **Record of strings** → returns a record with the same keys, values flipped.
+ *   Perfect for flipping an entire pack in one call.
  *
  * @example
  * ```ts
  * import { abyssalWhip, flipCursor } from '@dava96/osrs-icons';
  *
- * const leftFacingWhip = await flipCursor(abyssalWhip);
- * document.body.style.cursor = leftFacingWhip;
+ * // Single icon
+ * const flipped = await flipCursor(abyssalWhip);
+ * document.body.style.cursor = flipped;
  * ```
  *
  * @example
  * ```ts
- * import { dragonDaggerPack, flipCursor } from '@dava96/osrs-icons';
+ * import { coinsPack, flipCursor } from '@dava96/osrs-icons';
  *
  * // Flip an entire pack
- * const flippedDagger = await flipCursor(dragonDaggerPack.base);
+ * const flippedPack = await flipCursor(coinsPack);
+ * // flippedPack._1, flippedPack._2, ... are all flipped
+ * // flippedPack.stages is a flipped array
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { airRune, fireRune, flipCursor } from '@dava96/osrs-icons';
+ *
+ * // Flip an array of cursors
+ * const [flippedAir, flippedFire] = await flipCursor([airRune, fireRune]);
  * ```
  */
-async function flipCursor(cursorValue) {
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flipCursor = flipCursor;
+/** Matches `url('...')` in a CSS cursor value. Precompiled to avoid re-creation per call. */
+const FLIP_URL_REGEX = /url\('(.*?)'\)/;
+/** Internal cache to avoid re-processing the same icon. */
+const flipCache = new Map();
+// ── Implementation ─────────────────────────────────────────────────
+async function flipCursor(input) {
+    if (typeof input === 'string') {
+        return flipSingleCursor(input);
+    }
+    if (Array.isArray(input)) {
+        return Promise.all(input.map(flipSingleCursor));
+    }
+    const entries = Object.entries(input);
+    const flippedEntries = await Promise.all(entries.map(async ([key, value]) => {
+        if (typeof value === 'string') {
+            return [key, await flipSingleCursor(value)];
+        }
+        if (Array.isArray(value) && value.every((v) => typeof v === 'string')) {
+            return [key, await Promise.all(value.map(flipSingleCursor))];
+        }
+        return [key, value];
+    }));
+    return Object.fromEntries(flippedEntries);
+}
+// ── Internal helpers ───────────────────────────────────────────────
+/** Flips a single CSS cursor string, using the cache. */
+async function flipSingleCursor(cursorValue) {
     if (flipCache.has(cursorValue)) {
         return flipCache.get(cursorValue);
     }
     if (typeof document === 'undefined') {
         return cursorValue;
     }
-    const dataUrlMatch = cursorValue.match(/url\('(.*?)'\)/);
+    const dataUrlMatch = cursorValue.match(FLIP_URL_REGEX);
     if (!dataUrlMatch) {
         return cursorValue;
     }
@@ -50,8 +90,6 @@ async function flipCursor(cursorValue) {
     flipCache.set(cursorValue, flippedCursor);
     return flippedCursor;
 }
-/** Internal cache to avoid re-processing the same icon. */
-const flipCache = new Map();
 /**
  * Loads a data URL into an off-screen canvas, mirrors it horizontally,
  * and returns the flipped image as a new data URL.

package/dist/cjs/generated/icons.d.ts

@@ -17413,3 +17413,4 @@ export declare const zurielsStaff = "url('data:image/png;base64,iVBORw0KGgoAAAAN
 export declare const zurielsStaffLastManStanding = "url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB0AAAAeCAMAAADn2eWTAAAAulBMVEVMaXFsZGRdV1dYUlJnYGBza2tOSUgAAAFIQ0NMRkZbVVV5cXCEenpqYmI8NzdWUFBjXFs5NDSJYF1dNzWkcm9UMC50Q0KFTkqKUU6JgH8/OjpwaWlFQEBQLiyHUExUTU2PVVGTZWNnPTpxQj99V1VkOjl/SkhmMi5hOTeMUlB5SEVXNDB2OjdzOTVcPz1CPT1MJCI1MDBmbmZye3JITkh2RkOU2sS75thboIx807mK1sBwxaxrvaWP2MLZgia+AAAAAXRSTlMAQObYZgAAAAlwSFlzAAALEwAACxMBAJqcGAAAAKxJREFUeNp902cCgyAMBWCU6lPr1qrde++973+t9gBJ+PsRHgRQih2AEvD15BgK9++HUWQ4394P0IEoytOFzkWaZpV2jqRi2AByNymqK8FYAeVh959C1k6Rx3tgQcfOJts1MKKPg56eb5aDLqNGNAbAoc03GJbLNx91CeFIlRJaEgYS1niEiIaEcdQSlvXckHti8Jt2wmHbt0w2FGbgCTvSdodHs++E0r3w3+kHfw4LUj07+AMAAAAASUVORK5CYII='), auto";
 export declare const zurielsStaffBh = "url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB0AAAAeCAMAAADn2eWTAAAAulBMVEVMaXFsZGRdV1dYUlJnYGBza2tOSUgAAAFIQ0NMRkZbVVV5cXCEenpqYmI8NzdWUFBjXFs5NDSJYF1dNzWkcm9UMC50Q0KFTkqKUU6JgH8/OjpwaWlFQEBQLiyHUExUTU2PVVGTZWNnPTpxQj99V1VkOjl/SkhmMi5hOTeMUlB5SEVXNDB2OjdzOTVcPz1CPT1MJCI1MDBmbmZye3JITkh2RkOU2sS75thboIx807mK1sBwxaxrvaWP2MLZgia+AAAAAXRSTlMAQObYZgAAAAlwSFlzAAALEwAACxMBAJqcGAAAAKxJREFUeNp902cCgyAMBWCU6lPr1qrde++973+t9gBJ+PsRHgRQih2AEvD15BgK9++HUWQ4394P0IEoytOFzkWaZpV2jqRi2AByNymqK8FYAeVh959C1k6Rx3tgQcfOJts1MKKPg56eb5aDLqNGNAbAoc03GJbLNx91CeFIlRJaEgYS1niEiIaEcdQSlvXckHti8Jt2wmHbt0w2FGbgCTvSdodHs++E0r3w3+kHfw4LUj07+AMAAAAASUVORK5CYII='), auto";
 export declare const zurielsStaffBhinactive = "url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB0AAAAeCAMAAADn2eWTAAAAsVBMVEVMaXFFQEA5NDQ3IB0oJiZjXFtMRkYAAAEyLi5UTU15SEVhOTdhWlpqYmI1MDBza2ssKipYUlJCPT1bVVU/OjpRSkpMLCpIKihmMi6VZ2V4VFE8NzdWUFBIQ0MkIiJOSUh5cXB/Skh2RkNUMC5dNzVuQD1xQj9nSEZALCqAWFZnPTo/JCRUKCY0GBh0Q0JVW1UgHR1kbGQ0OTRxx65uwahDdmdWmYWW2sZvw6tcoo5mtJ6pW+hyAAAAAXRSTlMAQObYZgAAAAlwSFlzAAALEwAACxMBAJqcGAAAAK9JREFUeNp901cCgyAMBmBU9K9oa7VaR4fde+/2/gerB0jCCw8fISGAUuwAlICPH8dQeH9ejCLH9f59gk6I4HS+0XlRVbnx7Aup2DpAmerABARjB6yOm2YJGdtHmWk0E5l2uS72wJw+DmbWoTBTh9FesgDAoc03GG6Hbz7aEqIlRUoYShhL6PMIEUMJh6OusG090NwTQzRJxhy6keuxSZHFllCRlwoV+ZatpXvhv9Mfx6IK2oVBcCAAAAAASUVORK5CYII='), auto";
+//# sourceMappingURL=icons.d.ts.map