rn-remove-image-bg 0.0.22 → 0.0.24

package/README.md

@@ -324,22 +324,48 @@ try {
 
 > **First-time Use**: On Android, the ML Kit model downloads automatically on first use. The library waits for the download to complete (up to ~15 seconds with retries) before processing. Subsequent calls are instant.
 
-### Web
+### Web (React Native Web)
 
-1. **Add the Script**: You must add the `@imgly/background-removal` script to your web `index.html`:
-   ```html
-   <script src="https://cdn.jsdelivr.net/npm/@imgly/background-removal@1.7.0/dist/imgly-background-removal.min.js"></script>
-   ```
+This package supports **React Native Web** via the `@imgly/background-removal` library.
+
+#### Setup
+
+No manual setup is required! The library is installed automatically via npm and works with Metro bundler out of the box.
+
+#### Usage
+
+Use `removeBgImage` exactly like on native platforms.
+
+```typescript
+import { removeBgImage } from 'rn-remove-image-bg';
+
+const result = await removeBgImage(uri, {
+  maxDimension: 1024,
+  onProgress: (p) => console.log(p),
+  // Web-specific: Path to custom hosted models (optional)
+  // If omitted, models are downloaded from @imgly CDN (~30MB)
+  publicPath: '/assets/models/' 
+});
+```
+
+#### Asset Handling & Offline Support
+
+By default, the library downloads AI models (~30MB) from the **Internet (CDN)** on the first run and caches them in the browser (IndexedDB). This keeps your app bundle small (~2MB).
+
+**For Offline Support / Self-Hosting:**
+1.  Copy the `.wasm` and `.onnx` files from `node_modules/@imgly/background-removal/dist/` to your web `public/models` folder.
+2.  Pass `publicPath: '/models/'` (or your chosen path) in the options.
+
+#### Compatibility
 
-2. **Usage**: The library will automatically detect the global `imglyBackgroundRemoval` object.
+- **Browsers**: Chrome, Edge, Firefox, Safari (versions with WebGPU or WebGL2 support).
+- **Bundlers**: Works with **Metro** (Expo) out of the box.
+- **CORS**: If loading images from remote URLs, ensure they have `Access-Control-Allow-Origin: *` headers.
 
-- **Technology**: [@imgly/background-removal](https://github.com/imgly/background-removal-js) running in a Web Worker (managed by the library).
-- **Performance**: Zero UI blocking.
-- **Output**: Data URL (`data:image/png;base64,...`) or WEBP Blob.
-- **Requirements**:
-  - **CORS**: Images loaded from external URLs must be CORS-enabled (`Access-Control-Allow-Origin: *`).
+#### Troubleshooting (Web)
 
-> **Note**: The first call will download the WASM model files (~10MB) from the CDN. Ensure your CSP allows `cdn.jsdelivr.net`.
+- **"Resource not found"**: If you see 404s for `.wasm` files, ensure you have internet access (for CDN) or have correctly configured `publicPath`.
+- **CORS Errors**: "Tainted canvas" or "SecurityError" means the image server didn't send CORS headers. Proxy the image or configure your S3 bucket/server.
 
 ---
 

package/lib/ImageProcessing.web.d.ts

@@ -1,32 +1,25 @@
+import type { RemoveBgImageOptions, CompressImageOptions, GenerateThumbhashOptions, OutputFormat } from './web/core/types';
+export type { RemoveBgImageOptions, CompressImageOptions, GenerateThumbhashOptions, OutputFormat };
+export type NativeRemoveBackgroundOptions = RemoveBgImageOptions;
 /**
- * Web implementation using @imgly/background-removal via Script Tag.
- * Requires the script to be added manually to index.html.
+ * Remove background from image (Web Implementation)
  */
-export type OutputFormat = 'PNG' | 'WEBP';
-export interface RemoveBgImageOptions {
-    format?: OutputFormat;
-    quality?: number;
-    onProgress?: (progress: number) => void;
-    debug?: boolean;
-}
 export declare function removeBgImage(uri: string, options?: RemoveBgImageOptions): Promise<string>;
+/**
+ * Backward compatibility alias
+ * @deprecated Use removeBgImage
+ */
 export declare const removeBackground: typeof removeBgImage;
-export interface CompressImageOptions {
-    maxSizeKB?: number;
-    width?: number;
-    height?: number;
-    quality?: number;
-    format?: 'webp' | 'png' | 'jpeg';
-}
-export interface GenerateThumbhashOptions {
-    size?: number;
-}
+/**
+ * Compress image (Web Implementation)
+ */
 export declare function compressImage(uri: string, options?: CompressImageOptions): Promise<string>;
-export declare function generateThumbhash(imageUri: string, options?: GenerateThumbhashOptions): Promise<string>;
-export declare function clearCache(): Promise<void>;
+/**
+ * Generate thumbhash (Web Implementation)
+ */
+export declare function generateThumbhash(uri: string, _options?: GenerateThumbhashOptions): Promise<string>;
+export declare function clearCache(_deleteFiles?: boolean): Promise<void>;
 export declare function getCacheSize(): number;
-export declare function onLowMemory(): Promise<number>;
-export declare function configureCache(_config: {
-    maxEntries?: number;
-}): void;
+export declare function onLowMemory(_deleteFiles?: boolean): Promise<number>;
+export declare function configureCache(_config: Record<string, unknown>): void;
 export declare function getCacheDirectory(): string;

package/lib/ImageProcessing.web.js

@@ -1,116 +1,80 @@
+import { BackgroundRemover } from './web/core/BackgroundRemover';
+import { cacheManager } from './web/core/CacheManager';
+import { compressImage as compressImageWeb } from './web/utils/CompressImage';
+import { generateThumbhash as generateThumbhashWeb } from './web/utils/ThumbhashGenerator';
+import { blobToDataUrl } from './web/utils/formatConverter';
 /**
- * Web implementation using @imgly/background-removal via Script Tag.
- * Requires the script to be added manually to index.html.
+ * Remove background from image (Web Implementation)
  */
 export async function removeBgImage(uri, options = {}) {
-    const { onProgress, debug = false } = options;
-    // Safety check
-    if (typeof imglyBackgroundRemoval === 'undefined') {
-        throw new Error('[rn-remove-image-bg] Library not found. Please add the following script to your web index.html:\n' +
-            '<script src="https://cdn.jsdelivr.net/npm/@imgly/background-removal@1.7.0/dist/imgly-background-removal.min.js"></script>');
-    }
+    const { onProgress, useCache = true, debug = false } = options;
     if (debug)
-        console.log('[rmbg] Starting...');
-    onProgress?.(1);
-    // Config for imgly
-    const config = {
-        debug: debug,
-        // Point publicPath to CDN for assets (wasm/models)
-        // This is crucial for UMD build to find its dependencies on the CDN
-        publicPath: 'https://cdn.jsdelivr.net/npm/@imgly/background-removal@1.7.0/dist/',
-        progress: (_key, current, total) => {
-            if (onProgress && total > 0) {
-                onProgress((current / total) * 100);
-            }
+        console.log('[Web] removeBgImage called with:', uri, options);
+    // 1. Check Cache
+    if (useCache) {
+        const cached = cacheManager.get(uri, options);
+        if (cached) {
+            if (debug)
+                console.log('[Web] Cache hit');
+            onProgress?.(100);
+            return cached;
+        }
+    }
+    // 2. Process
+    onProgress?.(10); // Start
+    const blob = await BackgroundRemover.remove(uri, {
+        ...options,
+        onProgress: (p) => {
+            // Map progress to 10-90 range to leave room for start/end
+            const mapped = 10 + Math.round((p * 0.8));
+            onProgress?.(mapped);
         }
-    };
-    const blob = await imglyBackgroundRemoval.removeBackground(uri, config);
-    onProgress?.(100);
-    // Convert blob to DataURL
-    return new Promise((resolve, reject) => {
-        const reader = new FileReader();
-        reader.onloadend = () => resolve(reader.result);
-        reader.onerror = reject;
-        reader.readAsDataURL(blob);
     });
+    // 3. Convert to Data URL
+    const dataUrl = await blobToDataUrl(blob);
+    onProgress?.(100);
+    // 4. Cache Result
+    if (useCache) {
+        cacheManager.set(uri, options, dataUrl);
+    }
+    return dataUrl;
 }
+/**
+ * Backward compatibility alias
+ * @deprecated Use removeBgImage
+ */
 export const removeBackground = removeBgImage;
-// ==========================================
-// UTILITIES (Main Thread - lightweight)
-// ==========================================
-// Helper to load image
-function loadImage(src) {
-    return new Promise((resolve, reject) => {
-        const img = new Image();
-        img.crossOrigin = 'anonymous';
-        img.onload = () => resolve(img);
-        img.onerror = reject;
-        img.src = src;
-    });
-}
+/**
+ * Compress image (Web Implementation)
+ */
 export async function compressImage(uri, options = {}) {
-    const { maxSizeKB = 250, width = 1024, height = 1024, quality = 0.85, format = 'webp', } = options;
-    try {
-        const img = await loadImage(uri);
-        const scale = Math.min(width / img.width, height / img.height, 1);
-        const targetWidth = Math.round(img.width * scale);
-        const targetHeight = Math.round(img.height * scale);
-        const canvas = document.createElement('canvas');
-        canvas.width = targetWidth;
-        canvas.height = targetHeight;
-        const ctx = canvas.getContext('2d');
-        if (!ctx)
-            throw new Error('Could not get canvas context');
-        ctx.drawImage(img, 0, 0, targetWidth, targetHeight);
-        const mimeType = format === 'png' ? 'image/png' : format === 'jpeg' ? 'image/jpeg' : 'image/webp';
-        let dataUrl = canvas.toDataURL(mimeType, quality);
-        // Reduce quality if over size limit
-        let currentQuality = quality;
-        const getSize = (url) => ((url.split(',')[1] || '').length * 3) / 4 / 1024;
-        while (getSize(dataUrl) > maxSizeKB && currentQuality > 0.5) {
-            currentQuality -= 0.1;
-            dataUrl = canvas.toDataURL(mimeType, currentQuality);
-        }
-        return dataUrl;
-    }
-    catch (error) {
-        console.warn('[rmbg] compressImage failed:', error);
-        return uri;
-    }
+    return compressImageWeb(uri, options);
 }
-export async function generateThumbhash(imageUri, options = {}) {
-    const { size = 32 } = options;
-    try {
-        const img = await loadImage(imageUri);
-        const canvas = document.createElement('canvas');
-        canvas.width = size;
-        canvas.height = size;
-        const ctx = canvas.getContext('2d');
-        if (!ctx)
-            throw new Error('Could not get canvas context');
-        ctx.drawImage(img, 0, 0, size, size);
-        const imageData = ctx.getImageData(0, 0, size, size);
-        // Load thumbhash from CDN
-        // @ts-ignore
-        const { rgbaToThumbHash } = await import(/* webpackIgnore: true */ 'https://cdn.jsdelivr.net/npm/thumbhash@0.1/+esm');
-        const hash = rgbaToThumbHash(size, size, imageData.data);
-        return btoa(String.fromCharCode(...hash));
-    }
-    catch (error) {
-        console.warn('[rmbg] generateThumbhash failed:', error);
-        return '';
-    }
+/**
+ * Generate thumbhash (Web Implementation)
+ */
+export async function generateThumbhash(uri, _options = {}) {
+    // Web implementation currently doesn't use options (size hardcoded or auto-scaled)
+    return generateThumbhashWeb(uri);
 }
-export async function clearCache() {
-    // @ts-ignore
-    if (typeof imglyBackgroundRemoval !== 'undefined' && imglyBackgroundRemoval.preload) {
-        // no explicit clear cache in uMD version usually
-    }
+// Cache Management APIs
+export async function clearCache(_deleteFiles = false) {
+    cacheManager.clear();
+    console.log('[Web] Cache cleared');
+}
+export function getCacheSize() {
+    return cacheManager.size();
+}
+export async function onLowMemory(_deleteFiles = true) {
+    const size = cacheManager.size();
+    cacheManager.clear();
+    console.log(`[Web] Cleared ${size} items due to low memory`);
+    return size;
+}
+export function configureCache(_config) {
+    // Web cache is simple in-memory LRU, config not fully supported yet but stubbed
+    console.log('[Web] Cache configuration updated (no-op on web)');
 }
-export function getCacheSize() { return 0; }
-export async function onLowMemory() {
-    await clearCache();
-    return 0;
+export function getCacheDirectory() {
+    return ''; // No file system on web
 }
-export function configureCache(_config) { }
-export function getCacheDirectory() { return ''; }

package/lib/web/core/BackgroundRemover.d.ts

@@ -0,0 +1,8 @@
+import type { RemoveBgImageOptions } from './types';
+export declare const BackgroundRemover: {
+    /**
+     * Removes background from an image.
+     * Returns a Blobl of the processed image (PNG).
+     */
+    remove(uri: string, options: RemoveBgImageOptions): Promise<Blob>;
+};

package/lib/web/core/BackgroundRemover.js

@@ -0,0 +1,33 @@
+import { removeBackground as imglyRemove } from '@imgly/background-removal';
+import { mapErrorToBackgroundRemovalError } from '../errors/WebErrorAdapter';
+import { normalizeUri } from '../utils/uriHelper';
+export const BackgroundRemover = {
+    /**
+     * Removes background from an image.
+     * Returns a Blobl of the processed image (PNG).
+     */
+    async remove(uri, options) {
+        try {
+            const normalizedUri = await normalizeUri(uri);
+            const config = {
+                // Pass publicPath if provided (for self-hosted assets)
+                publicPath: options.publicPath,
+                // Map progress callback
+                progress: (_key, current, total) => {
+                    if (options.onProgress && total > 0) {
+                        const p = Math.min(100, Math.round((current / total) * 100));
+                        options.onProgress(p);
+                    }
+                },
+                // Enable debug logging if requested
+                debug: options.debug ?? false,
+            };
+            // Execute removal
+            const blob = await imglyRemove(normalizedUri, config);
+            return blob;
+        }
+        catch (error) {
+            throw mapErrorToBackgroundRemovalError(error);
+        }
+    }
+};

package/lib/web/core/CacheManager.d.ts

@@ -0,0 +1,16 @@
+import type { RemoveBgImageOptions } from './types';
+export declare class CacheManager {
+    private cache;
+    private readonly MAX_SIZE;
+    constructor();
+    /**
+     * Generates a unique cache key based on input URI and processing options
+     */
+    private generateKey;
+    get(uri: string, options: RemoveBgImageOptions): string | null;
+    set(uri: string, options: RemoveBgImageOptions, dataUrl: string): void;
+    clear(): void;
+    size(): number;
+    private evictOldest;
+}
+export declare const cacheManager: CacheManager;

package/lib/web/core/CacheManager.js

@@ -0,0 +1,57 @@
+export class CacheManager {
+    cache;
+    MAX_SIZE = 50; // Limit to 50 items to avoid memory leaks
+    constructor() {
+        this.cache = new Map();
+    }
+    /**
+     * Generates a unique cache key based on input URI and processing options
+     */
+    generateKey(uri, options) {
+        // We include relevant options that affect output
+        const { format = 'PNG', quality = 100, maxDimension = 0 } = options;
+        return `${uri}|${format}|${quality}|${maxDimension}`;
+    }
+    get(uri, options) {
+        const key = this.generateKey(uri, options);
+        const entry = this.cache.get(key);
+        if (entry) {
+            entry.timestamp = Date.now(); // Update usage timestamp (simple LRU)
+            return entry.dataUrl;
+        }
+        return null;
+    }
+    set(uri, options, dataUrl) {
+        const key = this.generateKey(uri, options);
+        // Evict if full
+        if (this.cache.size >= this.MAX_SIZE) {
+            this.evictOldest();
+        }
+        this.cache.set(key, {
+            dataUrl,
+            timestamp: Date.now()
+        });
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+    evictOldest() {
+        // Find oldest entry
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.timestamp < oldestTime) {
+                oldestTime = entry.timestamp;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+        }
+    }
+}
+// Singleton instance
+export const cacheManager = new CacheManager();

package/lib/web/core/types.d.ts

@@ -0,0 +1,47 @@
+export type OutputFormat = 'PNG' | 'WEBP';
+export interface RemoveBgImageOptions {
+    /**
+     * Output format of the processed image.
+     * Default: 'PNG'
+     */
+    format?: OutputFormat;
+    /**
+     * Quality of the output image (0-100). Only applies to WEBP/JPEG.
+     * Default: 100
+     */
+    quality?: number;
+    /**
+     * Callback to track download and processing progress (0-100).
+     */
+    onProgress?: (progress: number) => void;
+    /**
+     * Enable debug logging.
+     * Default: false
+     */
+    debug?: boolean;
+    /**
+     * Maximum dimension for the output image. Use this to resize large images before processing.
+     */
+    maxDimension?: number;
+    /**
+     * Public path to serve the model assets from.
+     * If not provided, it will attempt to fetch from @imgly CDN.
+     * Important for Metro bundler compatibility if not using CDN.
+     */
+    publicPath?: string;
+    /**
+     * Whether to use the cache for this request.
+     * Default: true
+     */
+    useCache?: boolean;
+}
+export interface CompressImageOptions {
+    maxSizeKB?: number;
+    width?: number;
+    height?: number;
+    quality?: number;
+    format?: 'webp' | 'png' | 'jpeg';
+}
+export interface GenerateThumbhashOptions {
+    size?: number;
+}

package/lib/web/core/types.js

@@ -0,0 +1 @@
+export {};

package/lib/web/errors/WebErrorAdapter.d.ts

@@ -0,0 +1,8 @@
+export declare class BackgroundRemovalError extends Error {
+    code: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Maps library errors to standardized BackgroundRemovalError
+ */
+export declare function mapErrorToBackgroundRemovalError(error: unknown): BackgroundRemovalError;

package/lib/web/errors/WebErrorAdapter.js

@@ -0,0 +1,29 @@
+export class BackgroundRemovalError extends Error {
+    code;
+    constructor(message, code = 'UNKNOWN_ERROR') {
+        super(message);
+        this.name = 'BackgroundRemovalError';
+        this.code = code;
+    }
+}
+/**
+ * Maps library errors to standardized BackgroundRemovalError
+ */
+export function mapErrorToBackgroundRemovalError(error) {
+    if (error instanceof BackgroundRemovalError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    // Model loading errors
+    if (message.includes('fetch') || message.includes('network') || message.includes('Failed to load resource')) {
+        return new BackgroundRemovalError(`Failed to download AI model. Please check your internet connection. (Details: ${message})`, 'MODEL_DOWNLOAD_ERROR');
+    }
+    // WASM errors
+    if (message.includes('wasm') || message.includes('WebAssembly')) {
+        return new BackgroundRemovalError(`WebAssembly failed to initialize. Your browser might not support it. (Details: ${message})`, 'WASM_INIT_ERROR');
+    }
+    // Processing errors
+    if (message.includes('memory') || message.includes('allocation')) {
+        return new BackgroundRemovalError('Out of memory. Try using a smaller maxDimension or closing other tabs.', 'MEMORY_ERROR');
+    }
+    return new BackgroundRemovalError(message);
+}

package/lib/web/utils/CompressImage.d.ts

@@ -0,0 +1,2 @@
+import type { CompressImageOptions } from '../core/types';
+export declare function compressImage(uri: string, options: CompressImageOptions): Promise<string>;

package/lib/web/utils/CompressImage.js

@@ -0,0 +1,32 @@
+import { loadImage } from './uriHelper';
+export async function compressImage(uri, options) {
+    const img = await loadImage(uri);
+    let { width, height, quality = 0.8, format = 'jpeg' } = options;
+    // Default dimensions to original if not specified
+    if (!width)
+        width = img.naturalWidth;
+    if (!height)
+        height = img.naturalHeight;
+    // Calculate aspect ratio if one dimension is missing (though simpler to just use natural if both default)
+    const ratio = img.naturalWidth / img.naturalHeight;
+    if (options.width && !options.height)
+        height = Math.round(width / ratio);
+    if (options.height && !options.width)
+        width = Math.round(height * ratio);
+    // Normalize format
+    const mimeType = format === 'png' ? 'image/png' : format === 'webp' ? 'image/webp' : 'image/jpeg';
+    // Create canvas
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        throw new Error('Canvas 2D context not available');
+    }
+    // Draw image
+    ctx.drawImage(img, 0, 0, width, height);
+    // Export
+    // Note: quality (0-1) is ignored for PNG
+    const dataUrl = canvas.toDataURL(mimeType, quality);
+    return dataUrl;
+}

package/lib/web/utils/ThumbhashGenerator.d.ts

@@ -0,0 +1 @@
+export declare function generateThumbhash(uri: string): Promise<string>;

package/lib/web/utils/ThumbhashGenerator.js

@@ -0,0 +1,31 @@
+import * as ThumbHash from 'thumbhash';
+import { loadImage } from './uriHelper';
+export async function generateThumbhash(uri) {
+    const img = await loadImage(uri);
+    // Thumbhash works best with images < 100x100
+    const maxSize = 100;
+    let width = img.naturalWidth;
+    let height = img.naturalHeight;
+    const scale = Math.min(maxSize / width, maxSize / height);
+    if (scale < 1) {
+        width = Math.round(width * scale);
+        height = Math.round(height * scale);
+    }
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        throw new Error('Canvas 2D context not available');
+    }
+    ctx.drawImage(img, 0, 0, width, height);
+    // Get RGBA data
+    const imageData = ctx.getImageData(0, 0, width, height);
+    const rgba = imageData.data;
+    // Generate binary hash
+    const hash = ThumbHash.rgbaToThumbHash(width, height, rgba);
+    // Convert to base64 using browser API
+    // hash is Uint8Array, spread into String.fromCharCode is safe for small thumbhashes (~30 bytes)
+    const binary = String.fromCharCode(...hash);
+    return window.btoa(binary);
+}

package/lib/web/utils/formatConverter.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Converts a Blob to a Data URL string (base64)
+ */
+export declare function blobToDataUrl(blob: Blob): Promise<string>;

package/lib/web/utils/formatConverter.js

@@ -0,0 +1,18 @@
+/**
+ * Converts a Blob to a Data URL string (base64)
+ */
+export function blobToDataUrl(blob) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => {
+            if (typeof reader.result === 'string') {
+                resolve(reader.result);
+            }
+            else {
+                reject(new Error('Failed to convert blob to data URL'));
+            }
+        };
+        reader.onerror = () => reject(reader.error);
+        reader.readAsDataURL(blob);
+    });
+}

package/lib/web/utils/uriHelper.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Helper to normalize React Native URIs for Web consumption.
+ * Handles file://, asset://, and data: URIs.
+ */
+export declare function normalizeUri(uri: string): Promise<string>;
+/**
+ * Loads an image from a URI into an HTMLImageElement for processing.
+ * Handles CORS cross-origin issues.
+ */
+export declare function loadImage(uri: string): Promise<HTMLImageElement>;

package/lib/web/utils/uriHelper.js

@@ -0,0 +1,46 @@
+/**
+ * Helper to normalize React Native URIs for Web consumption.
+ * Handles file://, asset://, and data: URIs.
+ */
+export async function normalizeUri(uri) {
+    if (!uri)
+        return '';
+    // Handle data URIs (return as is)
+    if (uri.startsWith('data:')) {
+        return uri;
+    }
+    // Handle http/https (return as is)
+    if (uri.startsWith('http')) {
+        return uri;
+    }
+    // Handle Expo asset:// URIs (convert to http relative path if needed, or pass through)
+    // In Expo Web, bundled assets are usually served from /assets/
+    if (uri.startsWith('asset://')) {
+        // NOTE: complex asset:// handling might require expo-asset, 
+        // but often on web the uri passed is already resolved or a relative path.
+        // For now, we return it. If it fails, we might need 'expo-asset' module.
+        return uri.replace('asset://', '/assets/');
+    }
+    // Handle file:// URIs
+    // On web, file:// is blocked for security unless it's a blob url created by the app
+    if (uri.startsWith('file://')) {
+        // If it's a local file picked by user, it might be a blob: reference in disguise or invalid.
+        // We strip the protocol for relative paths check.
+        return uri;
+    }
+    // Relative paths
+    return uri;
+}
+/**
+ * Loads an image from a URI into an HTMLImageElement for processing.
+ * Handles CORS cross-origin issues.
+ */
+export function loadImage(uri) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.crossOrigin = 'Anonymous'; // Enable CORS
+        img.onload = () => resolve(img);
+        img.onerror = (e) => reject(new Error(`Failed to load image at ${uri}: ${String(e)}`));
+        img.src = uri;
+    });
+}