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

package/dist/Infrastructure/ModelManager.js

@@ -4,21 +4,17 @@
  * Composes ModelRegistry (catalog) + ModelDownloader (downloads) and adds
  * model-loading orchestration (STT / TTS / LLM / VLM routing).
  *
- * The public API is unchanged — `ModelManager` is still a singleton that
- * exposes `registerModels()`, `downloadModel()`, `loadModel()`, `onChange()`, etc.
- * Internally it delegates catalog operations to the Registry and download
- * operations to the Downloader.
+ * Backend-specific logic (writing to sherpa-onnx FS, extracting archives,
+ * creating recognizer configs) is handled by the pluggable loader interfaces.
+ * This keeps ModelManager backend-agnostic — it only depends on core types.
  */
-import { WASMBridge } from '../Foundation/WASMBridge';
-import { SherpaONNXBridge } from '../Foundation/SherpaONNXBridge';
 import { EventBus } from '../Foundation/EventBus';
 import { SDKLogger } from '../Foundation/SDKLogger';
-import { STTModelType } from '../Public/Extensions/STTTypes';
 import { ModelCategory, LLMFramework, ModelStatus, DownloadStage, SDKEventType } from '../types/enums';
 import { OPFSStorage } from './OPFSStorage';
 import { ModelRegistry } from './ModelRegistry';
 import { ModelDownloader } from './ModelDownloader';
-import { extractTarGz } from './ArchiveUtility';
+import { inferModelFromFilename, sanitizeId } from './ModelFileInference';
 // Re-export types so existing imports from './Infrastructure/ModelManager' still work
 export { ModelCategory, LLMFramework, ModelStatus, DownloadStage };
 // ---------------------------------------------------------------------------
@@ -38,48 +34,38 @@ class ModelManagerImpl {
     metadata = {};
     /** Pluggable VLM loader (set by the app via setVLMLoader) */
     vlmLoader = null;
-    /** Pluggable model loaders — registered by the Public layer during init */
+    /** Pluggable model loaders — registered by backend providers */
     llmLoader = null;
     sttLoader = null;
     ttsLoader = null;
     vadLoader = null;
     constructor() {
         this.downloader = new ModelDownloader(this.registry, this.storage);
-        // Initialize OPFS storage (non-blocking)
         this.initStorage();
-        // Request persistent storage so browser won't evict our cached models
         this.requestPersistentStorage();
     }
     async initStorage() {
         await this.storage.initialize();
     }
-    // --- Registration API (called by the app) ---
-    /**
-     * Register a catalog of models. Resolves compact definitions into full
-     * ManagedModel entries and checks OPFS for previously downloaded files.
-     */
+    // --- Registration API ---
     registerModels(models) {
         this.registry.registerModels(models);
-        // Check OPFS for previously downloaded models (async, updates status when done)
         this.refreshDownloadStatus();
     }
-    /**
-     * Set the VLM loader implementation. Called by the app to plug in
-     * worker-based VLM loading (the SDK doesn't create Web Workers directly).
-     */
     setVLMLoader(loader) {
         this.vlmLoader = loader;
     }
-    /** Register the LLM model loader (text generation extension). */
     setLLMLoader(loader) { this.llmLoader = loader; }
-    /** Register the STT model loader (speech-to-text extension). */
     setSTTLoader(loader) { this.sttLoader = loader; }
-    /** Register the TTS model loader (text-to-speech extension). */
     setTTSLoader(loader) { this.ttsLoader = loader; }
-    /** Register the VAD model loader (voice activity detection extension). */
     setVADLoader(loader) { this.vadLoader = loader; }
+    /** Expose the downloader for backend packages that need file operations. */
+    getDownloader() { return this.downloader; }
+    /** Set the local file storage backend for persistent model storage. */
+    setLocalFileStorage(storage) {
+        this.downloader.setLocalFileStorage(storage);
+    }
     // --- Internal init ---
-    /** Request persistent storage to prevent browser from evicting cached models */
     async requestPersistentStorage() {
         try {
             if (navigator.storage?.persist) {
@@ -88,24 +74,18 @@ class ModelManagerImpl {
                     logger.info('Persistent storage: granted');
                 }
                 else {
-                    // Expected on first visit — browsers require engagement signals
-                    // (bookmark, PWA install, etc.) before granting persistence.
                     logger.debug('Persistent storage: denied (expected on first visit)');
                 }
             }
         }
         catch {
-            // Not supported or denied — non-critical
+            // Not supported or denied
         }
     }
-    /**
-     * Check OPFS for models that were downloaded in a previous session.
-     * Updates their status from 'registered' to 'downloaded'.
-     * Also loads persisted LRU metadata for each model.
-     * Only checks file existence + size — does NOT read file contents into memory.
-     */
     async refreshDownloadStatus() {
-        // Load persisted metadata (lastUsedAt timestamps)
+        // Ensure OPFS is initialized before checking for previously downloaded models.
+        // initStorage() is idempotent — returns immediately if already done.
+        await this.storage.initialize();
         this.metadata = await this.storage.loadMetadata();
         for (const model of this.registry.getModels()) {
             if (model.status !== ModelStatus.Registered)
@@ -114,7 +94,6 @@ class ModelManagerImpl {
                 const size = await this.downloader.getOPFSFileSize(model.id);
                 if (size !== null && size > 0) {
                     this.registry.updateModel(model.id, { status: ModelStatus.Downloaded, sizeBytes: size });
-                    // Ensure metadata entry exists — use persisted value or fall back to OPFS lastModified
                     if (!this.metadata[model.id]) {
                         const stored = await this.storage.listModels();
                         const entry = stored.find((s) => s.id === model.id);
@@ -129,34 +108,17 @@ class ModelManagerImpl {
                 // Not in OPFS, keep as registered
             }
         }
-        // Persist any newly created metadata entries
         await this.storage.saveMetadata(this.metadata);
     }
-    // --- Queries (delegated to registry) ---
-    getModels() {
-        return this.registry.getModels();
-    }
-    getModelsByCategory(category) {
-        return this.registry.getModelsByCategory(category);
-    }
-    getModelsByFramework(framework) {
-        return this.registry.getModelsByFramework(framework);
-    }
-    getLLMModels() {
-        return this.registry.getLLMModels();
-    }
-    getVLMModels() {
-        return this.registry.getVLMModels();
-    }
-    getSTTModels() {
-        return this.registry.getSTTModels();
-    }
-    getTTSModels() {
-        return this.registry.getTTSModels();
-    }
-    getVADModels() {
-        return this.registry.getVADModels();
-    }
+    // --- Queries ---
+    getModels() { return this.registry.getModels(); }
+    getModelsByCategory(category) { return this.registry.getModelsByCategory(category); }
+    getModelsByFramework(framework) { return this.registry.getModelsByFramework(framework); }
+    getLLMModels() { return this.registry.getLLMModels(); }
+    getVLMModels() { return this.registry.getVLMModels(); }
+    getSTTModels() { return this.registry.getSTTModels(); }
+    getTTSModels() { return this.registry.getTTSModels(); }
+    getVADModels() { return this.registry.getVADModels(); }
     getLoadedModel(category) {
         if (category) {
             const id = this.loadedByCategory.get(category);
@@ -168,69 +130,92 @@ class ModelManagerImpl {
         if (category) {
             return this.loadedByCategory.get(category) ?? null;
         }
-        // Legacy: return first loaded model id
         return this.registry.getModels().find((m) => m.status === ModelStatus.Loaded)?.id ?? null;
     }
-    /** Check if models for all given categories are loaded */
     areAllLoaded(categories) {
         return categories.every((c) => this.loadedByCategory.has(c));
     }
-    /**
-     * Ensure a model is loaded for the given category.
-     * If already loaded, returns the loaded model. If a downloaded model exists,
-     * loads it automatically. Returns null if no suitable model is available.
-     *
-     * @param options.coexist  Forwarded to `loadModel()`. When true, only swaps
-     *   models of the same category instead of unloading everything.
-     */
     async ensureLoaded(category, options) {
-        // Check if already loaded
         const loaded = this.getLoadedModel(category);
         if (loaded)
             return loaded;
-        // Find a downloaded model for this category
         const models = this.getModels();
         const downloaded = models.find(m => m.modality === category && m.status === ModelStatus.Downloaded);
         if (!downloaded)
             return null;
-        // Load it
         await this.loadModel(downloaded.id, options);
         return this.getLoadedModel(category);
     }
-    // --- Download (delegated to downloader) ---
-    /**
-     * Check whether downloading a model will fit in OPFS without eviction.
-     * Returns a result indicating whether it fits and which models could be
-     * evicted if not. Does NOT perform any mutations.
-     */
+    // --- Download ---
     async checkDownloadFit(modelId) {
         const model = this.registry.getModel(modelId);
         if (!model)
             return { fits: true, availableBytes: 0, neededBytes: 0, evictionCandidates: [] };
-        // Find the currently loaded model for the same category (excluded from eviction)
         const loadedId = this.loadedByCategory.get(model.modality ?? ModelCategory.Language);
         return this.downloader.checkStorageQuota(model, this.metadata, loadedId ?? undefined);
     }
     async downloadModel(modelId) {
         return this.downloader.downloadModel(modelId);
     }
-    // --- Model loading orchestration ---
+    // --- Model Import (file picker / drag-drop) ---
     /**
-     * Load a model by ID.
+     * Import a model from a user-provided File (via picker or drag-and-drop).
+     * Stores the file in the active storage backend and registers it as downloaded.
+     * If the model isn't already in the catalog, auto-registers it based on filename.
      *
-     * @param options.coexist  When `true`, only unload the model of the **same
-     *   category** (swap) rather than unloading ALL loaded models. Use this for
-     *   multi-model pipelines like Voice (STT + LLM + TTS).
-     *   Default is `false` — unloads everything to reclaim memory.
+     * @param file - The File object from file picker or drag-drop
+     * @param modelId - Optional: associate with an existing registered model
+     * @returns The model ID (existing or auto-generated)
      */
+    async importModel(file, modelId) {
+        let id = modelId ?? sanitizeId(file.name.replace(/\.[^.]+$/, ''));
+        // Auto-register if not in the catalog
+        if (!this.registry.getModel(id)) {
+            const meta = inferModelFromFilename(file.name);
+            this.registry.addModel({
+                id: meta.id,
+                name: meta.name,
+                url: '',
+                modality: meta.category,
+                framework: meta.framework,
+                status: ModelStatus.Registered,
+            });
+            // Use the inferred ID if different
+            id = meta.id;
+        }
+        logger.info(`Importing model from file: ${file.name} (${(file.size / 1024 / 1024).toFixed(1)} MB) -> ${id}`);
+        // Stream the file directly to storage to avoid loading the entire file into memory.
+        // file.stream() returns a ReadableStream<Uint8Array> in modern browsers.
+        if (typeof file.stream === 'function') {
+            await this.downloader.storeStreamInOPFS(id, file.stream());
+        }
+        else {
+            // Fallback for older browsers: buffer the entire file
+            const data = new Uint8Array(await file.arrayBuffer());
+            await this.downloader.storeInOPFS(id, data);
+        }
+        // Use file.size (already known) instead of data.length to avoid extra reference
+        const sizeBytes = file.size;
+        this.registry.updateModel(id, {
+            status: ModelStatus.Downloaded,
+            sizeBytes,
+        });
+        this.touchLastUsed(id, sizeBytes);
+        EventBus.shared.emit('model.imported', SDKEventType.Model, {
+            modelId: id,
+            filename: file.name,
+            sizeBytes,
+        });
+        logger.info(`Model imported: ${id} (${(sizeBytes / 1024 / 1024).toFixed(1)} MB)`);
+        return id;
+    }
+    // --- Model loading orchestration ---
     async loadModel(modelId, options) {
         const model = this.registry.getModel(modelId);
         if (!model || (model.status !== ModelStatus.Downloaded && model.status !== ModelStatus.Registered))
             return false;
         const category = model.modality ?? ModelCategory.Language;
         if (options?.coexist) {
-            // Pipeline mode: only unload models of the SAME category (swap).
-            // Other categories remain loaded for multi-model workflows.
             const currentId = this.loadedByCategory.get(category);
             if (currentId && currentId !== modelId) {
                 logger.info(`Swapping ${category} model: ${currentId} → ${modelId}`);
@@ -238,61 +223,41 @@ class ModelManagerImpl {
             }
         }
         else {
-            // Default: Unload ALL currently loaded models before loading the new one.
-            //
-            // In a browser environment, memory is limited (WASM linear memory +
-            // WebGPU buffers). The user interacts with one feature at a time
-            // (chat, vision, transcribe, etc.), so there's no need to keep models
-            // from other categories resident.
             await this.unloadAll(modelId);
         }
         this.registry.updateModel(modelId, { status: ModelStatus.Loading });
         EventBus.shared.emit('model.loadStarted', SDKEventType.Model, { modelId, category });
         try {
             if (model.modality === ModelCategory.Multimodal) {
-                // VLM: Worker reads from OPFS directly when possible.
-                // When OPFS quota is exceeded, models live only in the main-thread
-                // memory cache — we must read and transfer them to the Worker.
-                const exists = await this.downloader.existsInOPFS(modelId);
-                if (!exists) {
+                await this.loadVLMModel(model, modelId);
+            }
+            else if (model.modality === ModelCategory.SpeechRecognition) {
+                const data = await this.downloader.loadFromOPFS(modelId);
+                if (!data)
                     throw new Error('Model not downloaded — please download the model first.');
-                }
-                const inActualOPFS = await this.downloader.existsInActualOPFS(modelId);
-                if (inActualOPFS) {
-                    // Worker can read from OPFS directly (optimal: avoids main-thread copy)
-                    await this.loadLLMModel(model, modelId, new Uint8Array(0));
-                }
-                else {
-                    // Model is in memory cache only (OPFS quota exceeded) — read and transfer to Worker
-                    logger.debug(`VLM model ${modelId} not in OPFS, reading from memory cache to transfer to Worker`);
-                    const data = await this.downloader.loadFromOPFS(modelId);
-                    if (!data)
-                        throw new Error('Model not downloaded — please download the model first.');
-                    await this.loadLLMModel(model, modelId, data);
-                }
+                await this.loadSTTModel(model, data);
+            }
+            else if (model.modality === ModelCategory.SpeechSynthesis) {
+                const data = await this.downloader.loadFromOPFS(modelId);
+                if (!data)
+                    throw new Error('Model not downloaded — please download the model first.');
+                await this.loadTTSModel(model, data);
+            }
+            else if (model.modality === ModelCategory.Audio) {
+                const data = await this.downloader.loadFromOPFS(modelId);
+                if (!data)
+                    throw new Error('Model not downloaded — please download the model first.');
+                await this.loadVADModel(model, data);
             }
             else {
                 const data = await this.downloader.loadFromOPFS(modelId);
-                if (!data) {
+                if (!data)
                     throw new Error('Model not downloaded — please download the model first.');
-                }
-                if (model.modality === ModelCategory.SpeechRecognition) {
-                    await this.loadSTTModel(model, data);
-                }
-                else if (model.modality === ModelCategory.SpeechSynthesis) {
-                    await this.loadTTSModel(model, data);
-                }
-                else if (model.modality === ModelCategory.Audio) {
-                    await this.loadVADModel(model, data);
-                }
-                else {
-                    await this.loadLLMModel(model, modelId, data);
-                }
+                await this.loadLLMModel(model, modelId, data);
             }
             this.loadedByCategory.set(category, modelId);
             this.registry.updateModel(modelId, { status: ModelStatus.Loaded });
             EventBus.shared.emit('model.loadCompleted', SDKEventType.Model, { modelId, category });
-            // Update LRU metadata
             this.touchLastUsed(modelId, model.sizeBytes ?? 0);
             return true;
         }
@@ -313,17 +278,7 @@ class ModelManagerImpl {
         const category = model.modality ?? ModelCategory.Language;
         await this.unloadModelByCategory(category);
     }
-    /**
-     * Unload ALL currently loaded models.
-     *
-     * Called automatically before loading a new model, and can also be called
-     * explicitly by app code (e.g. on tab switch) to release all resources.
-     *
-     * @param exceptModelId - Optional model ID to skip (the model about to be loaded).
-     *                        Avoids redundant unload+reload of the same model.
-     */
     async unloadAll(exceptModelId) {
-        // Snapshot categories to avoid mutation during iteration
         const loaded = [...this.loadedByCategory.entries()];
         if (loaded.length === 0)
             return;
@@ -335,16 +290,13 @@ class ModelManagerImpl {
         }
     }
     async deleteModel(modelId) {
-        // Remove from loaded tracking if this model is loaded
         for (const [category, id] of this.loadedByCategory) {
             if (id === modelId) {
                 this.loadedByCategory.delete(category);
                 break;
             }
         }
-        // Delete primary file
         await this.downloader.deleteFromOPFS(modelId);
-        // Delete additional files
         const model = this.registry.getModel(modelId);
         if (model?.additionalFiles) {
             for (const file of model.additionalFiles) {
@@ -354,7 +306,6 @@ class ModelManagerImpl {
         this.registry.updateModel(modelId, { status: ModelStatus.Registered, downloadProgress: undefined, sizeBytes: undefined });
         this.removeMetadata(modelId);
     }
-    /** Clear all models from OPFS and reset registry statuses. */
     async clearAll() {
         await this.storage.clearAll();
         this.metadata = {};
@@ -376,10 +327,10 @@ class ModelManagerImpl {
             const root = await navigator.storage.getDirectory();
             const modelsDir = await root.getDirectoryHandle('models');
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            for await (const entry of modelsDir.values()) {
-                if (entry.kind === 'file') {
+            for await (const [name, handle] of modelsDir.entries()) {
+                if (handle.kind === 'file' && !name.startsWith('_')) {
                     modelCount++;
-                    const file = await entry.getFile();
+                    const file = await handle.getFile();
                     totalSize += file.size;
                 }
             }
@@ -398,22 +349,18 @@ class ModelManagerImpl {
         return { modelCount, totalSize, available };
     }
     // --- LRU Metadata ---
-    /** Get the last-used timestamp for a model (0 if never recorded). */
     getModelLastUsedAt(modelId) {
         return this.metadata[modelId]?.lastUsedAt ?? 0;
     }
-    /** Update lastUsedAt for a model and persist to OPFS (fire-and-forget). */
     touchLastUsed(modelId, sizeBytes) {
         this.metadata[modelId] = { lastUsedAt: Date.now(), sizeBytes };
-        // Persist asynchronously — don't block the caller
         this.storage.saveMetadata(this.metadata).catch(() => { });
     }
-    /** Remove metadata entry when a model is deleted. */
     removeMetadata(modelId) {
         delete this.metadata[modelId];
         this.storage.saveMetadata(this.metadata).catch(() => { });
     }
-    // --- Subscriptions (delegated to registry) ---
+    // --- Subscriptions ---
     onChange(callback) {
         return this.registry.onChange(callback);
     }
@@ -421,423 +368,130 @@ class ModelManagerImpl {
     // Private — model loading by modality
     // ---------------------------------------------------------------------------
     /**
-     * Load an LLM/VLM model into the RACommons Emscripten FS.
+     * Build a ModelLoadContext for passing to backend loaders.
      */
-    async loadLLMModel(model, modelId, data) {
-        const fsDir = `/models`;
-        const fsPath = `${fsDir}/${modelId}.gguf`;
-        if (model.modality === ModelCategory.Multimodal) {
-            // VLM models are loaded in a dedicated Web Worker that reads from OPFS.
-        }
-        else {
-            // Text-only LLM: write to main-thread Emscripten FS as before
-            const bridge = WASMBridge.shared;
-            if (!bridge.isLoaded) {
-                throw new Error('WASM module not loaded — SDK not initialized.');
-            }
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const m = bridge.module;
-            if (typeof m.FS_createPath !== 'function' || typeof m.FS_createDataFile !== 'function') {
-                throw new Error('Emscripten FS helper functions not available on WASM module.');
-            }
-            m.FS_createPath('/', 'models', true, true);
-            try {
-                m.FS_unlink(fsPath);
-            }
-            catch { /* File doesn't exist yet */ }
-            logger.debug(`Writing ${data.length} bytes to ${fsPath}`);
-            m.FS_createDataFile('/models', `${modelId}.gguf`, data, true, true, true);
-            logger.debug(`Model file written to ${fsPath}`);
-        }
-        if (model.modality === ModelCategory.Multimodal) {
-            const mmprojFile = model.additionalFiles?.find((f) => f.filename.includes('mmproj'));
-            if (!mmprojFile) {
-                logger.warning(`No mmproj found, loading as text-only LLM: ${modelId}`);
-                if (!this.llmLoader)
-                    throw new Error('No LLM loader registered. Call ModelManager.setLLMLoader() first.');
-                await this.llmLoader.loadModel(fsPath, modelId, model.name);
-            }
-            else {
-                // Ensure mmproj is in OPFS or memory cache (fallback download if missing)
-                const mmprojKey = this.downloader.additionalFileKey(modelId, mmprojFile.filename);
-                const mmprojExists = await this.downloader.existsInOPFS(mmprojKey);
-                if (!mmprojExists && mmprojFile.url) {
-                    logger.debug(`mmproj not in OPFS, downloading on-demand: ${mmprojFile.filename}`);
-                    const mmprojDownload = await this.downloader.downloadFile(mmprojFile.url);
-                    await this.downloader.storeInOPFS(mmprojKey, mmprojDownload);
-                }
-                if (!this.vlmLoader) {
-                    throw new Error('No VLM loader registered. Call ModelManager.setVLMLoader() first.');
-                }
-                // Initialize the Worker (loads its own WASM instance)
-                if (!this.vlmLoader.isInitialized) {
-                    logger.info('Initializing VLM loader...');
-                    await this.vlmLoader.init();
-                }
-                // When model/mmproj are only in memory cache (OPFS quota exceeded),
-                // we need to read and transfer the data to the Worker.
-                let modelDataBuf;
-                let mmprojDataBuf;
-                const modelInOPFS = await this.downloader.existsInActualOPFS(modelId);
-                if (!modelInOPFS && data.length > 0) {
-                    // data was already read from memory cache in the caller
-                    modelDataBuf = new ArrayBuffer(data.byteLength);
-                    new Uint8Array(modelDataBuf).set(data);
-                    logger.debug(`Transferring model data to VLM Worker (${(data.length / 1024 / 1024).toFixed(1)} MB)`);
-                }
-                const mmprojInOPFS = await this.downloader.existsInActualOPFS(mmprojKey);
-                if (!mmprojInOPFS) {
-                    const mmprojBytes = await this.downloader.loadFromOPFS(mmprojKey);
-                    if (mmprojBytes) {
-                        mmprojDataBuf = new ArrayBuffer(mmprojBytes.byteLength);
-                        new Uint8Array(mmprojDataBuf).set(mmprojBytes);
-                        logger.debug(`Transferring mmproj data to VLM Worker (${(mmprojBytes.length / 1024 / 1024).toFixed(1)} MB)`);
-                    }
-                }
-                // Load model via the pluggable VLM loader
-                logger.info(`Loading VLM model: ${modelId}`);
-                await this.vlmLoader.loadModel({
-                    modelOpfsKey: modelId,
-                    modelFilename: `${modelId}.gguf`,
-                    mmprojOpfsKey: mmprojKey,
-                    mmprojFilename: mmprojFile.filename,
-                    modelId,
-                    modelName: model.name,
-                    modelData: modelDataBuf,
-                    mmprojData: mmprojDataBuf,
-                });
-                logger.info(`VLM model loaded: ${modelId}`);
-            }
-        }
-        else if (model.modality === ModelCategory.Language) {
-            if (!this.llmLoader)
-                throw new Error('No LLM loader registered. Call ModelManager.setLLMLoader() first.');
-            await this.llmLoader.loadModel(fsPath, modelId, model.name);
-            logger.info(`LLM model loaded via TextGeneration: ${modelId}`);
-        }
+    buildLoadContext(model, data) {
+        return {
+            model,
+            data,
+            downloadFile: (url) => this.downloader.downloadFile(url),
+            loadFile: (fileKey) => this.downloader.loadFromOPFS(fileKey),
+            storeFile: (fileKey, fileData) => this.downloader.storeInOPFS(fileKey, fileData),
+            additionalFileKey: (modelId, filename) => this.downloader.additionalFileKey(modelId, filename),
+        };
     }
     /**
-     * Load an STT model into sherpa-onnx.
-     *
-     * Supports two modes:
-     *  1. **Archive** (isArchive=true): Download is a .tar.gz that bundles encoder,
-     *     decoder, tokens, etc. Matches the Swift SDK approach.
-     *  2. **Individual files**: Separate encoder/decoder/tokens downloads.
+     * Load an LLM model via the pluggable loader.
+     * The loader (in @runanywhere/web-llamacpp) handles writing to its own
+     * Emscripten FS and calling the C API.
      */
-    async loadSTTModel(model, primaryData) {
-        if (!this.sttLoader)
-            throw new Error('No STT loader registered. Call ModelManager.setSTTLoader() first.');
-        const sherpa = SherpaONNXBridge.shared;
-        await sherpa.ensureLoaded();
-        const modelDir = `/models/${model.id}`;
-        if (model.isArchive) {
-            await this.loadSTTFromArchive(model, primaryData, sherpa, modelDir);
-        }
-        else {
-            await this.loadSTTFromIndividualFiles(model, primaryData, sherpa, modelDir);
-        }
-        logger.info(`STT model loaded via sherpa-onnx: ${model.id}`);
+    async loadLLMModel(model, _modelId, data) {
+        if (!this.llmLoader)
+            throw new Error('No LLM loader registered. Register the @runanywhere/web-llamacpp package.');
+        const ctx = this.buildLoadContext(model, data);
+        await this.llmLoader.loadModelFromData(ctx);
+        logger.info(`LLM model loaded: ${model.id}`);
     }
     /**
-     * Load an STT model from a .tar.gz archive (matching Swift SDK approach).
-     * Extracts encoder, decoder, and tokens from the archive automatically.
+     * Load a VLM (vision-language) model via the pluggable VLM loader.
      */
-    async loadSTTFromArchive(model, archiveData, sherpa, modelDir) {
-        logger.debug(`Extracting STT archive for ${model.id} (${archiveData.length} bytes)...`);
-        const entries = await extractTarGz(archiveData);
-        logger.debug(`Extracted ${entries.length} files from STT archive`);
-        const prefix = this.findArchivePrefix(entries.map(e => e.path));
-        // Write all files and auto-discover key paths
-        let encoderPath = null;
-        let decoderPath = null;
-        let tokensPath = null;
-        let joinerPath = null;
-        let modelPath = null;
-        for (const entry of entries) {
-            const relativePath = prefix ? entry.path.slice(prefix.length) : entry.path;
-            const fsPath = `${modelDir}/${relativePath}`;
-            sherpa.writeFile(fsPath, entry.data);
-            // Auto-discover by filename pattern
-            if (relativePath.includes('encoder') && relativePath.endsWith('.onnx')) {
-                encoderPath = fsPath;
-            }
-            else if (relativePath.includes('decoder') && relativePath.endsWith('.onnx')) {
-                decoderPath = fsPath;
-            }
-            else if (relativePath.includes('joiner') && relativePath.endsWith('.onnx')) {
-                joinerPath = fsPath;
-            }
-            else if (relativePath.includes('tokens') && relativePath.endsWith('.txt')) {
-                tokensPath = fsPath;
-            }
-            else if (relativePath.endsWith('.onnx') && !relativePath.includes('encoder') && !relativePath.includes('decoder') && !relativePath.includes('joiner')) {
-                modelPath = fsPath;
-            }
-        }
-        // Route to the appropriate STT model type
-        if (model.id.includes('whisper')) {
-            if (!encoderPath || !decoderPath || !tokensPath) {
-                throw new Error(`Whisper archive for '${model.id}' missing encoder/decoder/tokens`);
-            }
-            await this.sttLoader.loadModel({
-                modelId: model.id,
-                type: STTModelType.Whisper,
-                modelFiles: { encoder: encoderPath, decoder: decoderPath, tokens: tokensPath },
-                sampleRate: 16000,
-                language: model.language ?? 'en',
-                task: model.sttTask ?? 'transcribe',
-            });
-        }
-        else if (model.id.includes('paraformer')) {
-            if (!modelPath || !tokensPath) {
-                throw new Error(`Paraformer archive for '${model.id}' missing model/tokens`);
-            }
-            await this.sttLoader.loadModel({
-                modelId: model.id,
-                type: STTModelType.Paraformer,
-                modelFiles: { model: modelPath, tokens: tokensPath },
-                sampleRate: 16000,
-            });
-        }
-        else if (model.id.includes('zipformer')) {
-            if (!encoderPath || !decoderPath || !joinerPath || !tokensPath) {
-                throw new Error(`Zipformer archive for '${model.id}' missing encoder/decoder/joiner/tokens`);
-            }
-            await this.sttLoader.loadModel({
-                modelId: model.id,
-                type: STTModelType.Zipformer,
-                modelFiles: { encoder: encoderPath, decoder: decoderPath, joiner: joinerPath, tokens: tokensPath },
-                sampleRate: 16000,
-            });
-        }
-        else {
-            throw new Error(`Unknown STT model type for model: ${model.id}`);
+    async loadVLMModel(model, modelId) {
+        const exists = await this.downloader.existsInOPFS(modelId);
+        if (!exists) {
+            throw new Error('Model not downloaded — please download the model first.');
+        }
+        const mmprojFile = model.additionalFiles?.find((f) => f.filename.includes('mmproj'));
+        if (!mmprojFile) {
+            // No mmproj — load as text-only LLM
+            logger.warning(`No mmproj found, loading as text-only LLM: ${modelId}`);
+            const data = await this.downloader.loadFromOPFS(modelId);
+            if (!data)
+                throw new Error('Model not downloaded.');
+            await this.loadLLMModel(model, modelId, data);
+            return;
         }
+        // Ensure mmproj is available
+        const mmprojKey = this.downloader.additionalFileKey(modelId, mmprojFile.filename);
+        const mmprojExists = await this.downloader.existsInOPFS(mmprojKey);
+        if (!mmprojExists && mmprojFile.url) {
+            logger.debug(`mmproj not in storage, downloading on-demand: ${mmprojFile.filename}`);
+            const mmprojDownload = await this.downloader.downloadFile(mmprojFile.url);
+            await this.downloader.storeInOPFS(mmprojKey, mmprojDownload);
+        }
+        if (!this.vlmLoader) {
+            throw new Error('No VLM loader registered. Call ModelManager.setVLMLoader() first.');
+        }
+        if (!this.vlmLoader.isInitialized) {
+            logger.info('Initializing VLM loader...');
+            await this.vlmLoader.init();
+        }
+        // Transfer data to Worker when model is only in memory cache
+        let modelDataBuf;
+        let mmprojDataBuf;
+        const modelInOPFS = await this.downloader.existsInActualOPFS(modelId);
+        if (!modelInOPFS) {
+            const data = await this.downloader.loadFromOPFS(modelId);
+            if (data && data.length > 0) {
+                modelDataBuf = new ArrayBuffer(data.byteLength);
+                new Uint8Array(modelDataBuf).set(data);
+                logger.debug(`Transferring model data to VLM Worker (${(data.length / 1024 / 1024).toFixed(1)} MB)`);
+            }
+        }
+        const mmprojInOPFS = await this.downloader.existsInActualOPFS(mmprojKey);
+        if (!mmprojInOPFS) {
+            const mmprojBytes = await this.downloader.loadFromOPFS(mmprojKey);
+            if (mmprojBytes) {
+                mmprojDataBuf = new ArrayBuffer(mmprojBytes.byteLength);
+                new Uint8Array(mmprojDataBuf).set(mmprojBytes);
+                logger.debug(`Transferring mmproj data to VLM Worker (${(mmprojBytes.length / 1024 / 1024).toFixed(1)} MB)`);
+            }
+        }
+        logger.info(`Loading VLM model: ${modelId}`);
+        await this.vlmLoader.loadModel({
+            modelOpfsKey: modelId,
+            modelFilename: `${modelId}.gguf`,
+            mmprojOpfsKey: mmprojKey,
+            mmprojFilename: mmprojFile.filename,
+            modelId,
+            modelName: model.name,
+            modelData: modelDataBuf,
+            mmprojData: mmprojDataBuf,
+        });
+        logger.info(`VLM model loaded: ${modelId}`);
     }
     /**
-     * Load an STT model from individual downloaded files (legacy path).
+     * Load an STT model via the pluggable loader.
+     * All sherpa-onnx FS operations are handled by the loader.
      */
-    async loadSTTFromIndividualFiles(model, primaryData, sherpa, modelDir) {
-        const primaryFilename = model.url.split('/').pop();
-        const primaryPath = `${modelDir}/${primaryFilename}`;
-        logger.debug(`Writing STT primary file to ${primaryPath} (${primaryData.length} bytes)`);
-        sherpa.writeFile(primaryPath, primaryData);
-        // Write additional files to sherpa FS (download on-demand if missing from OPFS)
-        const additionalPaths = {};
-        if (model.additionalFiles) {
-            for (const file of model.additionalFiles) {
-                const fileKey = this.downloader.additionalFileKey(model.id, file.filename);
-                let fileData = await this.downloader.loadFromOPFS(fileKey);
-                if (!fileData) {
-                    logger.debug(`Additional file ${file.filename} not in OPFS, downloading...`);
-                    fileData = await this.downloader.downloadFile(file.url);
-                    await this.downloader.storeInOPFS(fileKey, fileData);
-                }
-                const filePath = `${modelDir}/${file.filename}`;
-                logger.debug(`Writing STT file to ${filePath} (${fileData.length} bytes)`);
-                sherpa.writeFile(filePath, fileData);
-                additionalPaths[file.filename] = filePath;
-            }
-        }
-        // Determine model type and build config based on the model ID
-        if (model.id.includes('whisper')) {
-            const encoderPath = primaryPath;
-            const decoderFilename = model.additionalFiles?.find(f => f.filename.includes('decoder'))?.filename;
-            const tokensFilename = model.additionalFiles?.find(f => f.filename.includes('tokens'))?.filename;
-            if (!decoderFilename || !tokensFilename) {
-                throw new Error('Whisper model requires encoder, decoder, and tokens files');
-            }
-            await this.sttLoader.loadModel({
-                modelId: model.id,
-                type: STTModelType.Whisper,
-                modelFiles: {
-                    encoder: encoderPath,
-                    decoder: `${modelDir}/${decoderFilename}`,
-                    tokens: `${modelDir}/${tokensFilename}`,
-                },
-                sampleRate: 16000,
-                language: model.language ?? 'en',
-                task: model.sttTask ?? 'transcribe',
-            });
-        }
-        else if (model.id.includes('paraformer')) {
-            const tokensFilename = model.additionalFiles?.find(f => f.filename.includes('tokens'))?.filename;
-            if (!tokensFilename) {
-                throw new Error('Paraformer model requires model and tokens files');
-            }
-            await this.sttLoader.loadModel({
-                modelId: model.id,
-                type: STTModelType.Paraformer,
-                modelFiles: { model: primaryPath, tokens: `${modelDir}/${tokensFilename}` },
-                sampleRate: 16000,
-            });
-        }
-        else if (model.id.includes('zipformer')) {
-            const decoderFilename = model.additionalFiles?.find(f => f.filename.includes('decoder'))?.filename;
-            const joinerFilename = model.additionalFiles?.find(f => f.filename.includes('joiner'))?.filename;
-            const tokensFilename = model.additionalFiles?.find(f => f.filename.includes('tokens'))?.filename;
-            if (!decoderFilename || !joinerFilename || !tokensFilename) {
-                throw new Error('Zipformer model requires encoder, decoder, joiner, and tokens files');
-            }
-            await this.sttLoader.loadModel({
-                modelId: model.id,
-                type: STTModelType.Zipformer,
-                modelFiles: {
-                    encoder: primaryPath,
-                    decoder: `${modelDir}/${decoderFilename}`,
-                    joiner: `${modelDir}/${joinerFilename}`,
-                    tokens: `${modelDir}/${tokensFilename}`,
-                },
-                sampleRate: 16000,
-            });
-        }
-        else {
-            throw new Error(`Unknown STT model type for model: ${model.id}`);
-        }
+    async loadSTTModel(model, data) {
+        if (!this.sttLoader)
+            throw new Error('No STT loader registered. Register the @runanywhere/web-onnx package.');
+        const ctx = this.buildLoadContext(model, data);
+        await this.sttLoader.loadModelFromData(ctx);
+        logger.info(`STT model loaded: ${model.id}`);
     }
     /**
-     * Load a TTS model into the sherpa-onnx Emscripten FS and initialise the TTS engine.
-     *
-     * Supports two modes:
-     *  1. **Archive** (isArchive=true): Download is a .tar.gz that bundles model files +
-     *     espeak-ng-data. Matches the Swift SDK approach — extract and write all files.
-     *  2. **Individual files** (legacy): Separate model + companion file downloads.
+     * Load a TTS model via the pluggable loader.
+     * All sherpa-onnx FS operations are handled by the loader.
      */
-    async loadTTSModel(model, primaryData) {
+    async loadTTSModel(model, data) {
         if (!this.ttsLoader)
-            throw new Error('No TTS loader registered. Call ModelManager.setTTSLoader() first.');
-        const sherpa = SherpaONNXBridge.shared;
-        await sherpa.ensureLoaded();
-        const modelDir = `/models/${model.id}`;
-        if (model.isArchive) {
-            await this.loadTTSFromArchive(model, primaryData, sherpa, modelDir);
-        }
-        else {
-            await this.loadTTSFromIndividualFiles(model, primaryData, sherpa, modelDir);
-        }
-        logger.info(`TTS model loaded via sherpa-onnx: ${model.id}`);
+            throw new Error('No TTS loader registered. Register the @runanywhere/web-onnx package.');
+        const ctx = this.buildLoadContext(model, data);
+        await this.ttsLoader.loadModelFromData(ctx);
+        logger.info(`TTS model loaded: ${model.id}`);
     }
     /**
-     * Load a TTS model from a .tar.gz archive (matching Swift SDK approach).
-     *
-     * The archive contains all necessary files in a nested directory:
-     *   model.onnx, tokens.txt, espeak-ng-data/, etc.
-     * We extract everything and write it to the sherpa virtual FS.
-     */
-    async loadTTSFromArchive(model, archiveData, sherpa, modelDir) {
-        logger.debug(`Extracting TTS archive for ${model.id} (${archiveData.length} bytes)...`);
-        const entries = await extractTarGz(archiveData);
-        logger.debug(`Extracted ${entries.length} files from archive`);
-        // Find the common prefix (nested directory) — archives typically contain
-        // one top-level directory with all files inside it.
-        const prefix = this.findArchivePrefix(entries.map(e => e.path));
-        // Write all extracted files to the sherpa virtual FS
-        let modelPath = null;
-        let tokensPath = null;
-        let dataDirPath = null;
-        for (const entry of entries) {
-            // Strip the nested directory prefix to get relative path
-            const relativePath = prefix ? entry.path.slice(prefix.length) : entry.path;
-            const fsPath = `${modelDir}/${relativePath}`;
-            sherpa.writeFile(fsPath, entry.data);
-            // Auto-discover key files
-            if (relativePath.endsWith('.onnx') && !relativePath.includes('/')) {
-                modelPath = fsPath;
-            }
-            if (relativePath === 'tokens.txt') {
-                tokensPath = fsPath;
-            }
-            if (relativePath.startsWith('espeak-ng-data/') && !dataDirPath) {
-                dataDirPath = `${modelDir}/espeak-ng-data`;
-            }
-        }
-        if (!modelPath) {
-            throw new Error(`TTS archive for '${model.id}' does not contain an .onnx model file`);
-        }
-        if (!tokensPath) {
-            throw new Error(`TTS archive for '${model.id}' does not contain tokens.txt`);
-        }
-        logger.debug(`TTS archive extracted — model: ${modelPath}, tokens: ${tokensPath}, dataDir: ${dataDirPath ?? 'none'}`);
-        await this.ttsLoader.loadVoice({
-            voiceId: model.id,
-            modelPath,
-            tokensPath,
-            dataDir: dataDirPath ?? '',
-            numThreads: 1,
-        });
-    }
-    /**
-     * Load a TTS model from individual downloaded files.
-     * Used when models are registered with individual file URLs (e.g. HuggingFace)
-     * rather than tar.gz archives. Downloads espeak-ng-data on-demand for Piper models.
-     */
-    async loadTTSFromIndividualFiles(model, primaryData, sherpa, modelDir) {
-        const primaryFilename = model.url.split('/').pop();
-        const primaryPath = `${modelDir}/${primaryFilename}`;
-        logger.debug(`Writing TTS primary file to ${primaryPath} (${primaryData.length} bytes)`);
-        sherpa.writeFile(primaryPath, primaryData);
-        // Write additional files (tokens.txt, *.json, etc.)
-        const additionalPaths = {};
-        if (model.additionalFiles) {
-            for (const file of model.additionalFiles) {
-                const fileKey = this.downloader.additionalFileKey(model.id, file.filename);
-                let fileData = await this.downloader.loadFromOPFS(fileKey);
-                if (!fileData) {
-                    logger.debug(`Additional file ${file.filename} not in OPFS, downloading...`);
-                    fileData = await this.downloader.downloadFile(file.url);
-                    await this.downloader.storeInOPFS(fileKey, fileData);
-                }
-                const filePath = `${modelDir}/${file.filename}`;
-                logger.debug(`Writing TTS file to ${filePath} (${fileData.length} bytes)`);
-                sherpa.writeFile(filePath, fileData);
-                additionalPaths[file.filename] = filePath;
-            }
-        }
-        const tokensPath = additionalPaths['tokens.txt'];
-        if (!tokensPath) {
-            throw new Error('TTS model requires tokens.txt file');
-        }
-        await this.ttsLoader.loadVoice({
-            voiceId: model.id,
-            modelPath: primaryPath,
-            tokensPath,
-            dataDir: '', // espeak-ng-data is bundled in archives; individual-file path doesn't include it
-            numThreads: 1,
-        });
-    }
-    /**
-     * Load a VAD model (Silero) into the sherpa-onnx Emscripten FS.
-     * The Silero VAD is a single ONNX file — write it to FS and initialise.
+     * Load a VAD model via the pluggable loader.
+     * All sherpa-onnx FS operations are handled by the loader.
      */
     async loadVADModel(model, data) {
-        const sherpa = SherpaONNXBridge.shared;
-        await sherpa.ensureLoaded();
-        const modelDir = `/models/${model.id}`;
-        const filename = model.url?.split('/').pop() ?? 'silero_vad.onnx';
-        const fsPath = `${modelDir}/${filename}`;
-        logger.debug(`Writing VAD model to ${fsPath} (${data.length} bytes)`);
-        sherpa.writeFile(fsPath, data);
         if (!this.vadLoader)
-            throw new Error('No VAD loader registered. Call ModelManager.setVADLoader() first.');
-        await this.vadLoader.loadModel({ modelPath: fsPath });
+            throw new Error('No VAD loader registered. Register the @runanywhere/web-onnx package.');
+        const ctx = this.buildLoadContext(model, data);
+        await this.vadLoader.loadModelFromData(ctx);
         logger.info(`VAD model loaded: ${model.id}`);
     }
-    /**
-     * Find the common directory prefix in archive entry paths.
-     * Archives typically contain a single top-level directory (nested structure).
-     * Returns the prefix including trailing '/', or empty string if no common prefix.
-     */
-    findArchivePrefix(paths) {
-        if (paths.length === 0)
-            return '';
-        // Check if all paths share a common first directory component
-        const firstSlash = paths[0].indexOf('/');
-        if (firstSlash === -1)
-            return '';
-        const candidate = paths[0].slice(0, firstSlash + 1);
-        const allMatch = paths.every(p => p.startsWith(candidate));
-        return allMatch ? candidate : '';
-    }
     /** Unload the currently loaded model for a specific category */
     async unloadModelByCategory(category) {
         const modelId = this.loadedByCategory.get(category);
@@ -858,27 +512,12 @@ class ModelManagerImpl {
                 await this.vlmLoader?.unloadModel();
             }
             else {
-                await this.llmLoader?.unloadModel();
-            }
-            // Clean up Emscripten FS model files to release WASM linear memory.
-            // LLM models (Language) write .gguf files into the main-thread
-            // Emscripten FS. VLM (Multimodal) models are handled by the Worker's
-            // own WASM FS and don't need cleanup here.
-            if (category === ModelCategory.Language) {
-                try {
-                    const bridge = WASMBridge.shared;
-                    if (bridge.isLoaded) {
-                        const m = bridge.module;
-                        const fsPath = `/models/${modelId}.gguf`;
-                        try {
-                            m.FS_unlink(fsPath);
-                        }
-                        catch { /* file may not exist */ }
-                        logger.debug(`Cleaned up Emscripten FS: ${fsPath}`);
-                    }
+                // LLM: delegate unload + FS cleanup to the backend loader
+                if (this.llmLoader?.unloadAndCleanup) {
+                    await this.llmLoader.unloadAndCleanup(modelId);
                 }
-                catch {
-                    // Non-critical — FS cleanup is best-effort
+                else {
+                    await this.llmLoader?.unloadModel();
                 }
             }
         }