@keeratita/heic-converter 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @keeratita/heic-converter
 
-A modern, lightweight TypeScript library to convert `.heic` and `.heif` images to standard web formats (JPEG, PNG, SVG) client-side in the browser or on the backend in Node.js.
+A modern, lightweight TypeScript library to convert `.heic` and `.heif` images to standard web formats (JPEG, PNG, WebP, SVG) client-side in the browser or on the backend in Node.js.
 
 Designed specifically for environments with strict **Content Security Policy (CSP)** rules, it is built with WebAssembly compiled **without** dynamic code execution (`eval()` or `new Function()`).
 
@@ -10,10 +10,13 @@ Designed specifically for environments with strict **Content Security Policy (CS
 
 - 🔒 **CSP Compliant**: Emscripten glue code is compiled with `-s DYNAMIC_EXECUTION=0`. Safe to run without `'unsafe-eval'`.
 - 🧩 **Dependency Injection Architecture**: Swap the decoder module easily by implementing a simple `IHeicDecoder` interface.
-- ⚡ **Optimized Performance**: Reuses a single shared WASM instance across calls by default. Decodes an image in milliseconds.
+- ⚡ **Optimized Performance**: A fresh decoder instance is created and released per conversion — memory is reclaimed promptly and concurrent conversions never share mutable WASM state.
 - 🌐 **Isomorphic / Universal**: Runs in Node.js (decoding) and browser (decoding & canvas-based encoding).
 - 📦 **No Bloat**: Zero external production dependencies. Small footprint.
-- 🎨 **Format Support**: Convert to `jpeg` (with quality configuration), `png`, and `svg` (embedded lossless vector).
+- 🎨 **Format Support**: Convert to `jpeg` (with quality configuration), `png`, `webp`, and `svg` (embedded lossless vector).
+- 📐 **Resize Support**: Downscale with `maxWidth`/`maxHeight` or apply a uniform `scale` factor during conversion.
+- 📚 **Batch Conversion**: Convert many images at once with bounded concurrency via `convertMany`.
+- 🧵 **Web Worker Helper**: Offload conversions to a Web Worker with `convertHeicInWorker` to keep the UI thread responsive.
 
 ---
 
@@ -56,7 +59,32 @@ const imageUrl = URL.createObjectURL(jpegBlob);
 document.querySelector('img').src = imageUrl;
 ```
 
-### 2. Browser: Serving and Locating WASM (Custom Assets Path)
+### 2. Browser: WebP Output
+
+WebP offers excellent compression with quality configuration:
+
+```typescript
+import { convertHeic } from '@keeratita/heic-converter';
+
+const webpBlob = await convertHeic(heicBlob, {
+  to: 'webp',
+  quality: 0.8,
+});
+```
+
+### 3. Browser: SVG Output
+
+SVG wraps the raster image as an embedded lossless PNG inside an SVG container:
+
+```typescript
+import { convertHeic } from '@keeratita/heic-converter';
+
+const svgBlob = await convertHeic(heicBlob, {
+  to: 'svg',
+});
+```
+
+### 4. Browser: Serving and Locating WASM (Custom Assets Path)
 
 By default, the library tries to fetch `heic-decoder.wasm` relative to the current module script path (`import.meta.url`).
 
@@ -93,7 +121,7 @@ const jpegBlob = await convertHeic(heicBlob, {
 });
 ```
 
-### 3. Node.js: Decoding Raw Pixel Data
+### 5. Node.js: Decoding Raw Pixel Data
 
 Since Node.js lacks the native browser Canvas API, `convertHeic` (which relies on Canvas to encode raster formats) will throw an error on the backend.
 
@@ -110,11 +138,12 @@ async function convertNode() {
   const decoder = new LibheifDecoder();
   await decoder.initialize();
 
-  // Decodes to { width, height, data: Uint8ClampedArray (RGBA) }
+  // Decodes to { width, height, data: Uint8ClampedArray (RGBA) }.
+  // data is an independent copy — safe to use after decoder.free().
   const { width, height, data } = await decoder.decode(heicData);
 
   // Process raw pixels using sharp
-  await sharp(Buffer.from(data.buffer), {
+  await sharp(Buffer.from(data), {
     raw: { width, height, channels: 4 },
   })
     .toFormat('jpeg')
@@ -125,7 +154,7 @@ async function convertNode() {
 }
 ```
 
-### 4. Progress Tracking (e.g. for Large Images)
+### 6. Progress Tracking (e.g. for Large Images)
 
 For large images, you can pass an `onProgress` callback to track the conversion progress (0% to 100%):
 
@@ -145,6 +174,89 @@ const jpegBlob = await convertHeic(heicBlob, {
 > [!TIP]
 > Since the WebAssembly module runs on the main browser thread, the UI thread will be occupied during conversion. For maximum responsiveness when converting large images, it is highly recommended to run this library inside a standard JS **Web Worker** and communicate progress back to the main thread.
 
+### 7. Resizing Images
+
+Downscale to fit within maximum dimensions (aspect ratio is preserved, images smaller than the bounds are never upscaled):
+
+```typescript
+import { convertHeic } from '@keeratita/heic-converter';
+
+const thumbnailBlob = await convertHeic(heicBlob, {
+  to: 'jpeg',
+  maxWidth: 800,
+  maxHeight: 600,
+});
+```
+
+Or apply a uniform scale factor (can also upscale):
+
+```typescript
+const halfSizeBlob = await convertHeic(heicBlob, {
+  to: 'webp',
+  scale: 0.5,
+});
+```
+
+### 8. Batch Conversion
+
+Convert many images at once with bounded concurrency (default `4`). Results are returned in input order; if any conversion fails, the promise rejects as soon as the failure is known with an error that identifies the failing item:
+
+```typescript
+import { convertMany } from '@keeratita/heic-converter';
+
+const blobs = await convertMany(heicFiles, {
+  to: 'png',
+  concurrency: 3,
+  onProgress: (index, percent) => {
+    console.log(`Image ${index}: ${Math.round(percent)}%`);
+  },
+});
+```
+
+### 9. Web Worker Conversion
+
+Run the conversion inside a Web Worker so the main thread stays responsive. Create a worker script that uses this library:
+
+```js
+// converter.worker.js
+import { convertHeic } from '@keeratita/heic-converter';
+
+self.onmessage = async (event) => {
+  const { input, options } = event.data;
+  try {
+    const blob = await convertHeic(input, {
+      ...options,
+      onProgress: (percent) => self.postMessage({ type: 'progress', percent }),
+    });
+    self.postMessage({ type: 'result', ok: true, blob });
+  } catch (error) {
+    self.postMessage({ type: 'result', ok: false, error: error?.stack ?? error?.message ?? String(error) });
+  }
+};
+```
+
+Then convert from the main thread:
+
+```typescript
+import { convertHeicInWorker } from '@keeratita/heic-converter';
+
+const jpegBlob = await convertHeicInWorker(heicBlob, {
+  workerUrl: new URL('./converter.worker.js', import.meta.url),
+  workerType: 'module',
+  to: 'jpeg',
+  quality: 0.9,
+  onProgress: (percent) => console.log(`${Math.round(percent)}%`),
+});
+```
+
+> [!NOTE]
+> - Use `workerType: 'module'` when the worker script uses ES module imports (as in the example above). The default is `'classic'`, which requires the script to be pre-bundled (e.g. by Vite or webpack) — static ES imports are not supported in classic workers.
+> - `workerUrl` should be a compile-time constant; the script runs with the page's privileges.
+> - Only `progress` and `result` messages are understood; any other message type is ignored.
+> - `decoder`, `onProgress`, and `workerUrl` are not structured-cloneable, so they are not sent to the worker. Progress is forwarded through `{ type: 'progress', percent }` messages instead.
+> - `timeoutMs` (default `60000`) bounds how long the promise waits for a result; set `0` to disable.
+> - This helper is **browser-only**: it rejects in Node.js, where there is no global `Worker`.
+
 ---
 
 ## 🔒 Content Security Policy (CSP)
@@ -168,10 +280,35 @@ Converts a HEIC image file to a standard web format.
 
 - **`input`**: `Blob | File | ArrayBuffer | Uint8Array`
 - **`options`**: (optional) `ConvertOptions`
-  - `to`: `'jpeg' | 'jpg' | 'png' | 'svg'` (Default: `'jpeg'`)
-  - `quality`: `number` (0.0 to 1.0, only applicable to JPEG. Default: `0.92`)
+  - `to`: `'jpeg' | 'jpg' | 'png' | 'webp' | 'svg'` (Default: `'jpeg'`)
+  - `quality`: `number` (0.0 to 1.0, applicable to JPEG and WebP. Default: `0.92`)
   - `decoder`: `IHeicDecoder` (Inject custom decoder instance)
   - `onProgress`: `(percent: number) => void` (Optional callback, receives progress percentage from `0` to `100` during decoding)
+  - `maxWidth`: `number` (Downscale to fit within this width, preserving aspect ratio. Never upscales)
+  - `maxHeight`: `number` (Downscale to fit within this height, preserving aspect ratio. Never upscales)
+  - `scale`: `number` (Uniform scale factor, e.g. `0.5` halves the image. Takes precedence over `maxWidth`/`maxHeight`)
+- **Returns**: `Promise<Blob>`
+
+### `convertMany(inputs, options?)`
+
+Converts multiple HEIC images with bounded concurrency. Results are returned in input order; rejects as soon as a conversion fails, with an error identifying the failing item index.
+
+- **`inputs`**: `Array<Blob | File | ArrayBuffer | Uint8Array>`
+- **`options`**: (optional) `ConvertManyOptions` — same as `ConvertOptions`, except `onProgress` uses the batch signature below; plus:
+  - `concurrency`: `number` (Maximum concurrent conversions. Default: `4`)
+  - `onProgress`: `(index: number, percent: number) => void` (Per-item progress callback)
+  - `decoder`: `IHeicDecoder` (Optional. When provided, the same instance is shared by all concurrent conversions and must be safe for concurrent `decode()` calls)
+- **Returns**: `Promise<Blob[]>`
+
+### `convertHeicInWorker(input, options)`
+
+Converts a HEIC image inside a Web Worker. The worker script must implement the message protocol shown in [Usage section 9](#9-web-worker-conversion). Browser-only; rejects in Node.js.
+
+- **`input`**: `Blob | File | ArrayBuffer | Uint8Array`
+- **`options`**: `WorkerConvertOptions` — same as `ConvertOptions`, plus:
+  - `workerUrl`: `string | URL` (URL of the worker script; should be a compile-time constant)
+  - `workerType`: `'classic' | 'module'` (Worker script type. Default: `'classic'`; use `'module'` for scripts with ES imports)
+  - `timeoutMs`: `number` (Maximum wait for the result in milliseconds. Default: `60000`; `0` disables)
 - **Returns**: `Promise<Blob>`
 
 ### `LibheifDecoder(options?)`
@@ -182,13 +319,13 @@ The default WASM-based implementation of `IHeicDecoder`.
   - `locateFile`: `(path: string, prefix: string) => string`
   - `wasmBinary`: `ArrayBuffer`
 - **Methods**:
-  - `initialize(): Promise<void>`: Loads and initializes the WASM wrapper.
-  - `decode(data: Uint8Array, onProgress?: (percent: number) => void): Promise<DecodedImage>`: Decodes the HEIC bytes to raw RGBA, with optional progress callback.
-  - `free(): void`: Releases allocated WebAssembly heap memory.
+  - `initialize(): Promise<void>`: Loads and initializes the WASM wrapper. Safe to call concurrently; the module loads at most once per instance.
+  - `decode(data: Uint8Array, onProgress?: (percent: number) => void): Promise<DecodedImage>`: Decodes the HEIC bytes to raw RGBA, with optional progress callback. Returns an independent copy of the pixel data — safe to use after `free()`.
+  - `free(): void`: Releases allocated WebAssembly heap memory. Idempotent.
 
 ### `freeSharedDecoder()`
 
-The library keeps a shared instance of `LibheifDecoder` to speed up subsequent calls. Call `freeSharedDecoder()` when your application is done converting images to release memory.
+Kept for **API compatibility**. Decoders are now created and released per conversion, so there is no shared instance to release — calling this function is a no-op.
 
 ```typescript
 import { freeSharedDecoder } from '@keeratita/heic-converter';
@@ -225,6 +362,15 @@ npm run build
 npm run test
 ```
 
+### Run Browser E2E Tests
+
+Real browser conversions against the CSP sandbox and the GitHub Pages demo (`docs/`):
+
+```bash
+npx playwright install chromium   # one-time
+npm run test:e2e
+```
+
 ### Run Interactive CSP Sandbox
 
 To test the converter in a local browser running under a strict Content Security Policy, start the sandbox server:

package/dist/index.d.mts

@@ -19,8 +19,28 @@ interface IHeicDecoder {
      */
     free(): void;
 }
-type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg';
-interface ConvertOptions {
+type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg' | 'webp';
+type HeicInput = Blob | File | ArrayBuffer | Uint8Array;
+interface ResizeOptions {
+    /**
+     * Maximum width in pixels. The image is downscaled to fit within this
+     * bound while preserving the aspect ratio. Images smaller than the bound
+     * are never upscaled.
+     */
+    maxWidth?: number;
+    /**
+     * Maximum height in pixels. The image is downscaled to fit within this
+     * bound while preserving the aspect ratio. Images smaller than the bound
+     * are never upscaled.
+     */
+    maxHeight?: number;
+    /**
+     * Uniform scale factor applied to both dimensions (e.g. 0.5 halves the
+     * image). Takes precedence over `maxWidth` and `maxHeight` when set.
+     */
+    scale?: number;
+}
+interface ConvertOptions extends ResizeOptions {
     /**
      * Target format for the conversion.
      * @default 'jpeg'
@@ -28,7 +48,7 @@ interface ConvertOptions {
     to?: ImageFormat;
     /**
      * Quality of the converted image (between 0.0 and 1.0).
-     * Only applicable for 'jpeg' (and 'jpg') format.
+     * Applicable for 'jpeg', 'jpg', and 'webp' formats.
      * @default 0.92
      */
     quality?: number;
@@ -42,6 +62,25 @@ interface ConvertOptions {
      */
     onProgress?: (percent: number) => void;
 }
+interface ConvertManyOptions extends Omit<ConvertOptions, 'onProgress'> {
+    /**
+     * Maximum number of conversions running concurrently.
+     * @default 4
+     */
+    concurrency?: number;
+    /**
+     * Optional progress callback that receives the item index and its
+     * progress percentage (0 to 100) during decoding.
+     */
+    onProgress?: (index: number, percent: number) => void;
+    /**
+     * Optional custom decoder implementation to inject. When provided, the
+     * same instance is shared by all concurrent conversions, so it must be
+     * safe for concurrent `decode()` calls. If not provided, a fresh
+     * default LibheifDecoder is created per item.
+     */
+    decoder?: IHeicDecoder;
+}
 
 interface LibheifDecoderOptions {
     /**
@@ -59,9 +98,15 @@ declare class LibheifDecoder implements IHeicDecoder {
     private options?;
     private module;
     private decoderInstance;
+    /**
+     * Memoized module-loading promise so concurrent initialize()/decode() calls
+     * on the same instance never instantiate (or mutate) the module twice.
+     */
+    private initPromise;
     constructor(options?: LibheifDecoderOptions);
     /**
      * Initializes the WebAssembly module and instantiates the HEIC decoder.
+     * Safe to call concurrently: the module is loaded at most once per instance.
      */
     initialize(): Promise<void>;
     /**
@@ -72,22 +117,105 @@ declare class LibheifDecoder implements IHeicDecoder {
     decode(data: Uint8Array, onProgress?: (percent: number) => void): Promise<DecodedImage>;
     /**
      * Cleans up the WebAssembly decoder instance and resources.
+     * Idempotent: safe to call multiple times. After free(), the instance must
+     * be re-initialized (createHeicDecoderModule runs again on the next call).
      */
     free(): void;
 }
 
+interface WorkerConvertOptions extends ConvertOptions {
+    /**
+     * URL of the worker script that performs the conversion. Should be a
+     * compile-time constant (e.g. `new URL('./worker.js', import.meta.url)`
+     * under a bundler); the script runs with the page's privileges.
+     */
+    workerUrl: string | URL;
+    /**
+     * Maximum time in milliseconds to wait for the worker result before
+     * rejecting with a timeout. Defaults to 60000 (60s). Set to 0 to
+     * disable the timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Worker script type. Use `'module'` when the script uses ES module
+     * imports (e.g. `import { convertHeic } from ...`); `'classic'`
+     * scripts must be pre-bundled.
+     * @default 'classic'
+     */
+    workerType?: 'classic' | 'module';
+}
+/**
+ * Converts a HEIC image inside a Web Worker so the main thread stays
+ * responsive during the (potentially slow) WASM decode.
+ *
+ * The worker script is user-provided and must handle the following message
+ * protocol:
+ *
+ * ```js
+ * // converter.worker.js
+ * import { convertHeic } from '@keeratita/heic-converter';
+ *
+ * self.onmessage = async (event) => {
+ *   const { input, options } = event.data;
+ *   try {
+ *     const blob = await convertHeic(input, {
+ *       ...options,
+ *       onProgress: (percent) => self.postMessage({ type: 'progress', percent }),
+ *     });
+ *     self.postMessage({ type: 'result', ok: true, blob });
+ *   } catch (error) {
+ *     self.postMessage({ type: 'result', ok: false, error: error?.stack ?? error?.message ?? String(error) });
+ *   }
+ * };
+ * ```
+ *
+ * ```ts
+ * const jpegBlob = await convertHeicInWorker(heicBlob, {
+ *   workerUrl: new URL('./converter.worker.js', import.meta.url),
+ *   workerType: 'module',
+ *   to: 'jpeg',
+ * });
+ * ```
+ *
+ * Only `progress` and `result` messages are understood; any other message
+ * type is ignored. Use `workerType: 'module'` when the script uses ES
+ * module imports (as in the example above); `'classic'` scripts must be
+ * pre-bundled, since static ES imports are not supported there.
+ *
+ * @param input HEIC image as a Blob, File, ArrayBuffer, or Uint8Array.
+ * @param options Conversion options plus the worker script URL.
+ * @returns A Promise resolving to the converted image as a Blob.
+ */
+declare function convertHeicInWorker(input: HeicInput, options: WorkerConvertOptions): Promise<Blob>;
+
 /**
- * Releases the resources allocated for the shared default decoder instance.
- * Call this when no further HEIC conversions are needed to free memory.
+ * Releases any cached decoder resources.
+ *
+ * Decoders are now created and released per conversion, so there is no shared
+ * instance to free. This function is kept for API compatibility.
  */
 declare function freeSharedDecoder(): void;
 /**
- * Converts HEIC image data to a standard web format (JPEG, PNG, or SVG).
+ * Converts HEIC image data to a standard web format (JPEG, PNG, WebP, or SVG).
  *
  * @param input HEIC image as a Blob, File, ArrayBuffer, or Uint8Array.
  * @param options Conversion configuration options.
  * @returns A Promise resolving to the converted image as a Blob.
  */
-declare function convertHeic(input: Blob | File | ArrayBuffer | Uint8Array, options?: ConvertOptions): Promise<Blob>;
+declare function convertHeic(input: HeicInput, options?: ConvertOptions): Promise<Blob>;
+/**
+ * Converts multiple HEIC images to a standard web format.
+ *
+ * Conversions run with a bounded concurrency (default 4) and results are
+ * returned in the same order as the inputs. If any conversion fails, the
+ * returned promise rejects as soon as the failure is known (in-flight
+ * conversions are allowed to finish in the background) with an error that
+ * identifies the failing item index.
+ *
+ * @param inputs HEIC images as Blobs, Files, ArrayBuffers, or Uint8Arrays.
+ * @param options Batch conversion options.
+ * @returns A Promise resolving to the converted images as Blobs, in input order.
+ */
+declare function convertMany(inputs: HeicInput[], options?: ConvertManyOptions): Promise<Blob[]>;
 
-export { type ConvertOptions, type DecodedImage, type IHeicDecoder, type ImageFormat, LibheifDecoder, type LibheifDecoderOptions, convertHeic, freeSharedDecoder };
+export { type ConvertManyOptions, type ConvertOptions, type DecodedImage, type HeicInput, type IHeicDecoder, type ImageFormat, LibheifDecoder, type LibheifDecoderOptions, type ResizeOptions, type WorkerConvertOptions, convertHeic, convertHeicInWorker, convertMany, freeSharedDecoder };

package/dist/index.d.ts

@@ -19,8 +19,28 @@ interface IHeicDecoder {
      */
     free(): void;
 }
-type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg';
-interface ConvertOptions {
+type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg' | 'webp';
+type HeicInput = Blob | File | ArrayBuffer | Uint8Array;
+interface ResizeOptions {
+    /**
+     * Maximum width in pixels. The image is downscaled to fit within this
+     * bound while preserving the aspect ratio. Images smaller than the bound
+     * are never upscaled.
+     */
+    maxWidth?: number;
+    /**
+     * Maximum height in pixels. The image is downscaled to fit within this
+     * bound while preserving the aspect ratio. Images smaller than the bound
+     * are never upscaled.
+     */
+    maxHeight?: number;
+    /**
+     * Uniform scale factor applied to both dimensions (e.g. 0.5 halves the
+     * image). Takes precedence over `maxWidth` and `maxHeight` when set.
+     */
+    scale?: number;
+}
+interface ConvertOptions extends ResizeOptions {
     /**
      * Target format for the conversion.
      * @default 'jpeg'
@@ -28,7 +48,7 @@ interface ConvertOptions {
     to?: ImageFormat;
     /**
      * Quality of the converted image (between 0.0 and 1.0).
-     * Only applicable for 'jpeg' (and 'jpg') format.
+     * Applicable for 'jpeg', 'jpg', and 'webp' formats.
      * @default 0.92
      */
     quality?: number;
@@ -42,6 +62,25 @@ interface ConvertOptions {
      */
     onProgress?: (percent: number) => void;
 }
+interface ConvertManyOptions extends Omit<ConvertOptions, 'onProgress'> {
+    /**
+     * Maximum number of conversions running concurrently.
+     * @default 4
+     */
+    concurrency?: number;
+    /**
+     * Optional progress callback that receives the item index and its
+     * progress percentage (0 to 100) during decoding.
+     */
+    onProgress?: (index: number, percent: number) => void;
+    /**
+     * Optional custom decoder implementation to inject. When provided, the
+     * same instance is shared by all concurrent conversions, so it must be
+     * safe for concurrent `decode()` calls. If not provided, a fresh
+     * default LibheifDecoder is created per item.
+     */
+    decoder?: IHeicDecoder;
+}
 
 interface LibheifDecoderOptions {
     /**
@@ -59,9 +98,15 @@ declare class LibheifDecoder implements IHeicDecoder {
     private options?;
     private module;
     private decoderInstance;
+    /**
+     * Memoized module-loading promise so concurrent initialize()/decode() calls
+     * on the same instance never instantiate (or mutate) the module twice.
+     */
+    private initPromise;
     constructor(options?: LibheifDecoderOptions);
     /**
      * Initializes the WebAssembly module and instantiates the HEIC decoder.
+     * Safe to call concurrently: the module is loaded at most once per instance.
      */
     initialize(): Promise<void>;
     /**
@@ -72,22 +117,105 @@ declare class LibheifDecoder implements IHeicDecoder {
     decode(data: Uint8Array, onProgress?: (percent: number) => void): Promise<DecodedImage>;
     /**
      * Cleans up the WebAssembly decoder instance and resources.
+     * Idempotent: safe to call multiple times. After free(), the instance must
+     * be re-initialized (createHeicDecoderModule runs again on the next call).
      */
     free(): void;
 }
 
+interface WorkerConvertOptions extends ConvertOptions {
+    /**
+     * URL of the worker script that performs the conversion. Should be a
+     * compile-time constant (e.g. `new URL('./worker.js', import.meta.url)`
+     * under a bundler); the script runs with the page's privileges.
+     */
+    workerUrl: string | URL;
+    /**
+     * Maximum time in milliseconds to wait for the worker result before
+     * rejecting with a timeout. Defaults to 60000 (60s). Set to 0 to
+     * disable the timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Worker script type. Use `'module'` when the script uses ES module
+     * imports (e.g. `import { convertHeic } from ...`); `'classic'`
+     * scripts must be pre-bundled.
+     * @default 'classic'
+     */
+    workerType?: 'classic' | 'module';
+}
+/**
+ * Converts a HEIC image inside a Web Worker so the main thread stays
+ * responsive during the (potentially slow) WASM decode.
+ *
+ * The worker script is user-provided and must handle the following message
+ * protocol:
+ *
+ * ```js
+ * // converter.worker.js
+ * import { convertHeic } from '@keeratita/heic-converter';
+ *
+ * self.onmessage = async (event) => {
+ *   const { input, options } = event.data;
+ *   try {
+ *     const blob = await convertHeic(input, {
+ *       ...options,
+ *       onProgress: (percent) => self.postMessage({ type: 'progress', percent }),
+ *     });
+ *     self.postMessage({ type: 'result', ok: true, blob });
+ *   } catch (error) {
+ *     self.postMessage({ type: 'result', ok: false, error: error?.stack ?? error?.message ?? String(error) });
+ *   }
+ * };
+ * ```
+ *
+ * ```ts
+ * const jpegBlob = await convertHeicInWorker(heicBlob, {
+ *   workerUrl: new URL('./converter.worker.js', import.meta.url),
+ *   workerType: 'module',
+ *   to: 'jpeg',
+ * });
+ * ```
+ *
+ * Only `progress` and `result` messages are understood; any other message
+ * type is ignored. Use `workerType: 'module'` when the script uses ES
+ * module imports (as in the example above); `'classic'` scripts must be
+ * pre-bundled, since static ES imports are not supported there.
+ *
+ * @param input HEIC image as a Blob, File, ArrayBuffer, or Uint8Array.
+ * @param options Conversion options plus the worker script URL.
+ * @returns A Promise resolving to the converted image as a Blob.
+ */
+declare function convertHeicInWorker(input: HeicInput, options: WorkerConvertOptions): Promise<Blob>;
+
 /**
- * Releases the resources allocated for the shared default decoder instance.
- * Call this when no further HEIC conversions are needed to free memory.
+ * Releases any cached decoder resources.
+ *
+ * Decoders are now created and released per conversion, so there is no shared
+ * instance to free. This function is kept for API compatibility.
  */
 declare function freeSharedDecoder(): void;
 /**
- * Converts HEIC image data to a standard web format (JPEG, PNG, or SVG).
+ * Converts HEIC image data to a standard web format (JPEG, PNG, WebP, or SVG).
  *
  * @param input HEIC image as a Blob, File, ArrayBuffer, or Uint8Array.
  * @param options Conversion configuration options.
  * @returns A Promise resolving to the converted image as a Blob.
  */
-declare function convertHeic(input: Blob | File | ArrayBuffer | Uint8Array, options?: ConvertOptions): Promise<Blob>;
+declare function convertHeic(input: HeicInput, options?: ConvertOptions): Promise<Blob>;
+/**
+ * Converts multiple HEIC images to a standard web format.
+ *
+ * Conversions run with a bounded concurrency (default 4) and results are
+ * returned in the same order as the inputs. If any conversion fails, the
+ * returned promise rejects as soon as the failure is known (in-flight
+ * conversions are allowed to finish in the background) with an error that
+ * identifies the failing item index.
+ *
+ * @param inputs HEIC images as Blobs, Files, ArrayBuffers, or Uint8Arrays.
+ * @param options Batch conversion options.
+ * @returns A Promise resolving to the converted images as Blobs, in input order.
+ */
+declare function convertMany(inputs: HeicInput[], options?: ConvertManyOptions): Promise<Blob[]>;
 
-export { type ConvertOptions, type DecodedImage, type IHeicDecoder, type ImageFormat, LibheifDecoder, type LibheifDecoderOptions, convertHeic, freeSharedDecoder };
+export { type ConvertManyOptions, type ConvertOptions, type DecodedImage, type HeicInput, type IHeicDecoder, type ImageFormat, LibheifDecoder, type LibheifDecoderOptions, type ResizeOptions, type WorkerConvertOptions, convertHeic, convertHeicInWorker, convertMany, freeSharedDecoder };