@runanywhere/web 0.1.0-beta.6 → 0.1.0-beta.7

package/dist/Infrastructure/LocalFileStorage.js

@@ -0,0 +1,428 @@
+/**
+ * LocalFileStorage - Persistent model storage using the File System Access API
+ *
+ * Allows users to choose a real folder on their local filesystem for model
+ * storage. Models are saved as actual files (e.g. ~/ai-models/smollm2.gguf)
+ * that persist permanently — no browser eviction, no re-downloads.
+ *
+ * The directory handle is stored in IndexedDB (not cookies — handles are
+ * structured-cloneable objects that can't be serialized to strings).
+ *
+ * Browser support:
+ *   - Chrome 122+: Full support with persistent permissions ("Allow on every visit")
+ *   - Chrome 86-121: Supported but re-prompts for permission each session
+ *   - Edge: Same as Chrome (Chromium-based)
+ *   - Firefox/Safari: NOT supported — falls back to OPFS storage
+ *
+ * Usage:
+ *   const storage = new LocalFileStorage();
+ *   await storage.chooseDirectory();        // User picks a folder
+ *   await storage.saveModel('model-id', data);
+ *
+ *   // On return visit:
+ *   const restored = await storage.restoreDirectory();
+ *   if (restored) {
+ *     const data = await storage.loadModel('model-id');
+ *   }
+ */
+import { SDKLogger } from '../Foundation/SDKLogger';
+const logger = new SDKLogger('LocalFileStorage');
+/* eslint-enable @typescript-eslint/no-explicit-any */
+// ---------------------------------------------------------------------------
+// IndexedDB Constants
+// ---------------------------------------------------------------------------
+const DB_NAME = 'runanywhere-storage';
+const DB_VERSION = 1;
+const STORE_NAME = 'handles';
+const HANDLE_KEY = 'modelDirectory';
+const LS_DIR_NAME_KEY = 'runanywhere_storage_dir_name';
+// ---------------------------------------------------------------------------
+// LocalFileStorage
+// ---------------------------------------------------------------------------
+export class LocalFileStorage {
+    dirHandle = null;
+    _isReady = false;
+    _hasStoredHandle = false;
+    /** Per-key write lock to prevent concurrent writes to the same file. */
+    writeLocks = new Map();
+    // -------------------------------------------------------------------------
+    // Static
+    // -------------------------------------------------------------------------
+    /** Whether the File System Access API is available in this browser. */
+    static get isSupported() {
+        return typeof window !== 'undefined' && 'showDirectoryPicker' in window;
+    }
+    /**
+     * Get the stored directory name from localStorage (fast, synchronous).
+     * Available immediately on page load before IndexedDB restores the handle.
+     * Returns the folder name only (e.g. "ai-models"), not the full path.
+     */
+    static get storedDirectoryName() {
+        try {
+            return localStorage.getItem(LS_DIR_NAME_KEY);
+        }
+        catch {
+            return null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // State
+    // -------------------------------------------------------------------------
+    /** Whether the storage is ready for use (directory selected + permission granted). */
+    get isReady() {
+        return this._isReady && this.dirHandle !== null;
+    }
+    /** Whether a handle was found in IndexedDB (even if permission isn't granted yet). */
+    get hasStoredHandle() {
+        return this._hasStoredHandle;
+    }
+    /** The name of the chosen directory (for display in UI). */
+    get directoryName() {
+        return this.dirHandle?.name ?? null;
+    }
+    // -------------------------------------------------------------------------
+    // Directory Selection
+    // -------------------------------------------------------------------------
+    /**
+     * Prompt the user to choose a directory for model storage.
+     * Opens the OS folder picker dialog.
+     * Stores the directory handle in IndexedDB for future sessions.
+     *
+     * @returns true if a directory was selected, false if cancelled
+     */
+    async chooseDirectory() {
+        if (!LocalFileStorage.isSupported) {
+            logger.warning('File System Access API not supported in this browser');
+            return false;
+        }
+        try {
+            // showDirectoryPicker requires user gesture (button click)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            this.dirHandle = await window.showDirectoryPicker({
+                mode: 'readwrite',
+            });
+            await this.storeHandle(this.dirHandle);
+            this._isReady = true;
+            this._hasStoredHandle = true;
+            // Persist directory name in localStorage for fast UI display on next visit
+            try {
+                localStorage.setItem(LS_DIR_NAME_KEY, this.dirHandle.name);
+            }
+            catch { /* non-critical */ }
+            logger.info(`Local storage directory selected: ${this.dirHandle.name}`);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                logger.debug('User cancelled directory picker');
+                return false;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error(`Failed to choose directory: ${message}`);
+            return false;
+        }
+    }
+    /**
+     * Attempt to restore a previously chosen directory from IndexedDB.
+     *
+     * On Chrome 122+, if the user selected "Allow on every visit",
+     * permission is automatically granted without any prompt.
+     *
+     * @returns true if directory was restored and permission is granted.
+     *          false if no handle stored or permission not granted (UI
+     *          should show a "Re-authorize" button).
+     */
+    async restoreDirectory() {
+        if (!LocalFileStorage.isSupported)
+            return false;
+        try {
+            const handle = await this.retrieveHandle();
+            if (!handle) {
+                logger.debug('No stored directory handle found');
+                return false;
+            }
+            this._hasStoredHandle = true;
+            this.dirHandle = handle;
+            // queryPermission does NOT require user gesture
+            const permission = await handle.queryPermission({ mode: 'readwrite' });
+            if (permission === 'granted') {
+                this._isReady = true;
+                logger.info(`Local storage restored: ${handle.name}`);
+                return true;
+            }
+            // Permission not granted yet — user needs to click a button
+            // to trigger requestPermission() via requestAccess()
+            logger.debug(`Local storage handle found but permission is '${permission}' — needs re-authorization`);
+            this._isReady = false;
+            return false;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warning(`Failed to restore directory: ${message}`);
+            return false;
+        }
+    }
+    /**
+     * Request readwrite permission on a previously stored handle.
+     * MUST be called from a user gesture (button click handler).
+     *
+     * @returns true if permission was granted
+     */
+    async requestAccess() {
+        if (!this.dirHandle) {
+            logger.warning('No directory handle to request access for');
+            return false;
+        }
+        try {
+            const permission = await this.dirHandle.requestPermission({ mode: 'readwrite' });
+            if (permission === 'granted') {
+                this._isReady = true;
+                logger.info(`Local storage re-authorized: ${this.dirHandle.name}`);
+                return true;
+            }
+            logger.debug(`Permission request result: ${permission}`);
+            return false;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warning(`Permission request failed: ${message}`);
+            return false;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Model Operations
+    // -------------------------------------------------------------------------
+    /**
+     * Save model data to the local filesystem.
+     * Uses a per-key lock to prevent concurrent writes from corrupting files.
+     * @param key - Model identifier (used as filename)
+     * @param data - Model file data
+     */
+    async saveModel(key, data) {
+        return this.withWriteLock(key, () => this._saveModelImpl(key, data));
+    }
+    /**
+     * Save model data from a ReadableStream to the local filesystem.
+     * Streams data directly to disk without buffering the entire file in memory.
+     * Uses a per-key lock to prevent concurrent writes from corrupting files.
+     * @param key - Model identifier (used as filename)
+     * @param stream - Readable stream of model data
+     */
+    async saveModelFromStream(key, stream) {
+        return this.withWriteLock(key, () => this._saveStreamImpl(key, stream));
+    }
+    async _saveModelImpl(key, data) {
+        if (!this.dirHandle || !this._isReady) {
+            throw new Error('LocalFileStorage not ready — call chooseDirectory() or restoreDirectory() first.');
+        }
+        const filename = this.sanitizeFilename(key);
+        const fileHandle = await this.dirHandle.getFileHandle(filename, { create: true });
+        const writable = await fileHandle.createWritable();
+        try {
+            await writable.write(data);
+            await writable.close();
+            logger.info(`Saved model to local storage: ${filename} (${(data.byteLength / 1024 / 1024).toFixed(1)} MB)`);
+        }
+        catch (err) {
+            try {
+                await writable.abort();
+            }
+            catch { /* ignore */ }
+            throw err;
+        }
+    }
+    async _saveStreamImpl(key, stream) {
+        if (!this.dirHandle || !this._isReady) {
+            throw new Error('LocalFileStorage not ready — call chooseDirectory() or restoreDirectory() first.');
+        }
+        const filename = this.sanitizeFilename(key);
+        const fileHandle = await this.dirHandle.getFileHandle(filename, { create: true });
+        const writable = await fileHandle.createWritable();
+        try {
+            const reader = stream.getReader();
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                await writable.write(value);
+            }
+            await writable.close();
+            logger.info(`Streamed model to local storage: ${filename}`);
+        }
+        catch (err) {
+            try {
+                await writable.abort();
+            }
+            catch { /* ignore */ }
+            throw err;
+        }
+    }
+    /**
+     * Per-key write lock: ensures only one write operation per key at a time.
+     * Concurrent calls for the same key will be serialized.
+     */
+    async withWriteLock(key, fn) {
+        const prev = this.writeLocks.get(key) ?? Promise.resolve();
+        const next = prev.then(fn, fn); // chain even if previous rejected
+        this.writeLocks.set(key, next);
+        try {
+            await next;
+        }
+        finally {
+            // Clean up lock if this was the last write in the chain
+            if (this.writeLocks.get(key) === next) {
+                this.writeLocks.delete(key);
+            }
+        }
+    }
+    /**
+     * Load model data from the local filesystem.
+     * @param key - Model identifier
+     * @returns Model data, or null if not found
+     */
+    async loadModel(key) {
+        if (!this.dirHandle || !this._isReady)
+            return null;
+        try {
+            const filename = this.sanitizeFilename(key);
+            const fileHandle = await this.dirHandle.getFileHandle(filename);
+            const file = await fileHandle.getFile();
+            logger.info(`Loaded model from local storage: ${filename} (${(file.size / 1024 / 1024).toFixed(1)} MB)`);
+            return await file.arrayBuffer();
+        }
+        catch {
+            return null; // File not found
+        }
+    }
+    /**
+     * Check if a model file exists in local storage.
+     * @param key - Model identifier
+     */
+    async hasModel(key) {
+        if (!this.dirHandle || !this._isReady)
+            return false;
+        try {
+            const filename = this.sanitizeFilename(key);
+            await this.dirHandle.getFileHandle(filename);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Delete a model file from local storage.
+     * @param key - Model identifier
+     */
+    async deleteModel(key) {
+        if (!this.dirHandle || !this._isReady)
+            return;
+        try {
+            const filename = this.sanitizeFilename(key);
+            await this.dirHandle.removeEntry(filename);
+            logger.info(`Deleted model from local storage: ${filename}`);
+        }
+        catch {
+            // File doesn't exist
+        }
+    }
+    /**
+     * Get file size without reading into memory.
+     * @param key - Model identifier
+     */
+    async getFileSize(key) {
+        if (!this.dirHandle || !this._isReady)
+            return null;
+        try {
+            const filename = this.sanitizeFilename(key);
+            const fileHandle = await this.dirHandle.getFileHandle(filename);
+            const file = await fileHandle.getFile();
+            return file.size;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * List all model files in the directory.
+     */
+    async listModels() {
+        if (!this.dirHandle || !this._isReady)
+            return [];
+        const models = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        for await (const [name, handle] of this.dirHandle.entries()) {
+            if (handle.kind === 'file') {
+                const file = await handle.getFile();
+                models.push({
+                    id: name,
+                    sizeBytes: file.size,
+                    lastModified: file.lastModified,
+                });
+            }
+        }
+        return models;
+    }
+    // -------------------------------------------------------------------------
+    // IndexedDB Handle Persistence
+    // -------------------------------------------------------------------------
+    async openDB() {
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open(DB_NAME, DB_VERSION);
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains(STORE_NAME)) {
+                    db.createObjectStore(STORE_NAME);
+                }
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async storeHandle(handle) {
+        try {
+            const db = await this.openDB();
+            const tx = db.transaction(STORE_NAME, 'readwrite');
+            tx.objectStore(STORE_NAME).put(handle, HANDLE_KEY);
+            await new Promise((resolve, reject) => {
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => reject(tx.error);
+            });
+            db.close();
+            logger.debug('Directory handle stored in IndexedDB');
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warning(`Failed to store handle in IndexedDB: ${message}`);
+        }
+    }
+    async retrieveHandle() {
+        try {
+            const db = await this.openDB();
+            const tx = db.transaction(STORE_NAME, 'readonly');
+            const handle = await new Promise((resolve, reject) => {
+                const req = tx.objectStore(STORE_NAME).get(HANDLE_KEY);
+                req.onsuccess = () => resolve(req.result ?? null);
+                req.onerror = () => reject(req.error);
+            });
+            db.close();
+            return handle;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warning(`Failed to retrieve handle from IndexedDB: ${message}`);
+            return null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Sanitize a key for use as a filename.
+     * Keeps alphanumeric, dots, dashes, underscores. Replaces everything else.
+     */
+    sanitizeFilename(key) {
+        return key.replace(/[<>:"/\\|?*\x00-\x1F]/g, '_');
+    }
+}
+//# sourceMappingURL=LocalFileStorage.js.map

package/dist/Infrastructure/LocalFileStorage.js.map

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

package/dist/Infrastructure/ModelDownloader.d.ts

@@ -7,6 +7,7 @@
  */
 import { OPFSStorage } from './OPFSStorage';
 import type { MetadataMap } from './OPFSStorage';
+import type { LocalFileStorage } from './LocalFileStorage';
 import type { ManagedModel } from './ModelRegistry';
 import type { ModelRegistry } from './ModelRegistry';
 /** Candidate model that could be evicted to free space. */
@@ -33,6 +34,11 @@ export interface QuotaCheckResult {
 export declare class ModelDownloader {
     private readonly storage;
     private readonly registry;
+    /**
+     * Optional local filesystem storage. When configured, models are saved
+     * to the user's chosen directory instead of OPFS. Set via setLocalFileStorage().
+     */
+    private localFileStorage;
     /**
      * In-memory fallback cache for models that were downloaded successfully
      * but failed to persist to OPFS (e.g. storage quota exceeded).
@@ -40,6 +46,11 @@ export declare class ModelDownloader {
      */
     private readonly memoryCache;
     constructor(registry: ModelRegistry, storage: OPFSStorage);
+    /**
+     * Set the local file storage backend.
+     * When configured and ready, models are saved/loaded from the local filesystem first.
+     */
+    setLocalFileStorage(storage: LocalFileStorage): void;
     /**
      * Check whether a model will fit in OPFS without eviction.
      *
@@ -64,7 +75,7 @@ export declare class ModelDownloader {
      * URLs are validated before fetching to prevent SSRF and enforce HTTPS.
      */
     downloadFile(url: string, onProgress?: (progress: number, bytesDownloaded: number, totalBytes: number) => void): Promise<Uint8Array>;
-    /** Store data in OPFS via OPFSStorage. Auto-evicts old models if quota is exceeded, falls back to in-memory cache. */
+    /** Store data, preferring local filesystem when available, then OPFS, then memory cache. */
     storeInOPFS(key: string, data: Uint8Array): Promise<void>;
     /**
      * Evict old models from OPFS to free space for a new model.
@@ -76,15 +87,20 @@ export declare class ModelDownloader {
      * the other, separated by "__" (e.g. "modelA" and "modelA__mmproj-...").
      */
     private evictOPFSModels;
-    /** Load data from OPFS via OPFSStorage, falling back to in-memory cache. */
+    /**
+     * Store a file from a ReadableStream, avoiding loading the entire file into memory.
+     * Priority: local filesystem > OPFS. Falls back to buffered write if streaming not supported.
+     */
+    storeStreamInOPFS(key: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    /** Load data from storage. Priority: local filesystem > OPFS > memory cache. */
     loadFromOPFS(key: string): Promise<Uint8Array | null>;
-    /** Check existence in OPFS or in-memory cache. */
+    /** Check existence in local storage, OPFS, or in-memory cache. */
     existsInOPFS(key: string): Promise<boolean>;
     /** Check if data exists in actual OPFS storage (NOT memory cache). */
     existsInActualOPFS(key: string): Promise<boolean>;
-    /** Delete from OPFS and memory cache. */
+    /** Delete from all storage backends (local filesystem, OPFS, memory cache). */
     deleteFromOPFS(key: string): Promise<void>;
-    /** Get file size from OPFS without reading into memory. */
+    /** Get file size from storage without reading into memory. */
     getOPFSFileSize(key: string): Promise<number | null>;
     /**
      * Build an OPFS key for additional files (e.g., mmproj).

package/dist/Infrastructure/ModelDownloader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModelDownloader.d.ts","sourceRoot":"","sources":["../../src/Infrastructure/ModelDownloader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAMrD,2DAA2D;AAC3D,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,IAAI,EAAE,OAAO,CAAC;IACd,4CAA4C;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,kBAAkB,EAAE,qBAAqB,EAAE,CAAC;CAC7C;AAkED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;gBAEjD,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW;IASzD;;;;;;;;;;OAUG;IACG,iBAAiB,CACrB,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,WAAW,EACrB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,gBAAgB,CAAC;IAmD5B;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyGnD;;;;;OAKG;IACG,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,GACnF,OAAO,CAAC,UAAU,CAAC;IA+BtB,sHAAsH;IAChH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC/D;;;;;;;;OAQG;YACW,eAAe;IAmD7B,4EAA4E;IACtE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA6B3D,kDAAkD;IAC5C,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKjD,sEAAsE;IAChE,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIvD,yCAAyC;IACnC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhD,2DAA2D;IACrD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQ1D;;;;OAIG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAI5D,6DAA6D;IAC7D,OAAO,CAAC,oBAAoB;CAS7B"}
+{"version":3,"file":"ModelDownloader.d.ts","sourceRoot":"","sources":["../../src/Infrastructure/ModelDownloader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAMrD,2DAA2D;AAC3D,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,IAAI,EAAE,OAAO,CAAC;IACd,4CAA4C;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,kBAAkB,EAAE,qBAAqB,EAAE,CAAC;CAC7C;AAkED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAiC;IAEzD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;gBAEjD,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW;IAKzD;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAQpD;;;;;;;;;;OAUG;IACG,iBAAiB,CACrB,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,WAAW,EACrB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,gBAAgB,CAAC;IAmD5B;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyGnD;;;;;OAKG;IACG,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,GACnF,OAAO,CAAC,UAAU,CAAC;IA+BtB,4FAA4F;IACtF,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAoD/D;;;;;;;;OAQG;YACW,eAAe;IAmD7B;;;OAGG;IACG,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBvF,gFAAgF;IAC1E,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAuC3D,kEAAkE;IAC5D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASjD,sEAAsE;IAChE,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIvD,+EAA+E;IACzE,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD,8DAA8D;IACxD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAY1D;;;;OAIG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAI5D,6DAA6D;IAC7D,OAAO,CAAC,oBAAoB;CAS7B"}

package/dist/Infrastructure/ModelDownloader.js

@@ -65,6 +65,11 @@ const logger = new SDKLogger('ModelDownloader');
 export class ModelDownloader {
     storage;
     registry;
+    /**
+     * Optional local filesystem storage. When configured, models are saved
+     * to the user's chosen directory instead of OPFS. Set via setLocalFileStorage().
+     */
+    localFileStorage = null;
     /**
      * In-memory fallback cache for models that were downloaded successfully
      * but failed to persist to OPFS (e.g. storage quota exceeded).
@@ -75,6 +80,13 @@ export class ModelDownloader {
         this.registry = registry;
         this.storage = storage;
     }
+    /**
+     * Set the local file storage backend.
+     * When configured and ready, models are saved/loaded from the local filesystem first.
+     */
+    setLocalFileStorage(storage) {
+        this.localFileStorage = storage;
+    }
     // ---------------------------------------------------------------------------
     // Public API
     // ---------------------------------------------------------------------------
@@ -270,11 +282,24 @@ export class ModelDownloader {
         }
         return data;
     }
-    /** Store data in OPFS via OPFSStorage. Auto-evicts old models if quota is exceeded, falls back to in-memory cache. */
+    /** Store data, preferring local filesystem when available, then OPFS, then memory cache. */
     async storeInOPFS(key, data) {
         const sizeMB = (data.length / 1024 / 1024).toFixed(1);
+        // Try local filesystem first (permanent, no quota issues)
+        if (this.localFileStorage?.isReady) {
+            try {
+                await this.localFileStorage.saveModel(key, data.buffer);
+                logger.info(`Stored ${key} in local storage (${sizeMB} MB)`);
+                this.memoryCache.delete(key);
+                return;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger.warning(`Local storage write failed for "${key}": ${msg}, falling back to OPFS`);
+            }
+        }
         try {
-            // First attempt
+            // First attempt — OPFS
             await this.storage.saveModel(key, data.buffer);
             logger.info(`Stored ${key} in OPFS (${sizeMB} MB)`);
             this.memoryCache.delete(key);
@@ -361,9 +386,43 @@ export class ModelDownloader {
             }
         }
     }
-    /** Load data from OPFS via OPFSStorage, falling back to in-memory cache. */
+    /**
+     * Store a file from a ReadableStream, avoiding loading the entire file into memory.
+     * Priority: local filesystem > OPFS. Falls back to buffered write if streaming not supported.
+     */
+    async storeStreamInOPFS(key, stream) {
+        // Try local filesystem first (permanent, no quota issues)
+        if (this.localFileStorage?.isReady) {
+            try {
+                await this.localFileStorage.saveModelFromStream(key, stream);
+                return;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger.warning(`Local storage stream write failed for "${key}": ${msg}, falling back to OPFS`);
+            }
+        }
+        try {
+            await this.storage.saveModelFromStream(key, stream);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warning(`OPFS stream store failed for "${key}": ${msg}`);
+            throw err;
+        }
+    }
+    /** Load data from storage. Priority: local filesystem > OPFS > memory cache. */
     async loadFromOPFS(key) {
-        // Try OPFS first (persistent storage)
+        // Try local filesystem first (permanent storage)
+        if (this.localFileStorage?.isReady) {
+            const localBuffer = await this.localFileStorage.loadModel(key);
+            if (localBuffer && localBuffer.byteLength > 0) {
+                const sizeMB = localBuffer.byteLength / 1024 / 1024;
+                logger.debug(`Loading ${key} from local storage (${sizeMB.toFixed(1)} MB)`);
+                return new Uint8Array(localBuffer);
+            }
+        }
+        // Try OPFS (persistent browser storage)
         const buffer = await this.storage.loadModel(key);
         if (buffer && buffer.byteLength > 0) {
             const sizeMB = buffer.byteLength / 1024 / 1024;
@@ -387,8 +446,13 @@ export class ModelDownloader {
         }
         return null;
     }
-    /** Check existence in OPFS or in-memory cache. */
+    /** Check existence in local storage, OPFS, or in-memory cache. */
     async existsInOPFS(key) {
+        if (this.localFileStorage?.isReady) {
+            const localExists = await this.localFileStorage.hasModel(key);
+            if (localExists)
+                return true;
+        }
         if (this.memoryCache.has(key))
             return true;
         return this.storage.hasModel(key);
@@ -397,13 +461,21 @@ export class ModelDownloader {
     async existsInActualOPFS(key) {
         return this.storage.hasModel(key);
     }
-    /** Delete from OPFS and memory cache. */
+    /** Delete from all storage backends (local filesystem, OPFS, memory cache). */
     async deleteFromOPFS(key) {
         this.memoryCache.delete(key);
+        if (this.localFileStorage?.isReady) {
+            await this.localFileStorage.deleteModel(key);
+        }
         await this.storage.deleteModel(key);
     }
-    /** Get file size from OPFS without reading into memory. */
+    /** Get file size from storage without reading into memory. */
     async getOPFSFileSize(key) {
+        if (this.localFileStorage?.isReady) {
+            const localSize = await this.localFileStorage.getFileSize(key);
+            if (localSize !== null)
+                return localSize;
+        }
         return this.storage.getFileSize(key);
     }
     // ---------------------------------------------------------------------------