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

package/dist/Infrastructure/ModelManager.js

@@ -4,18 +4,21 @@
  * Composes ModelRegistry (catalog) + ModelDownloader (downloads) and adds
  * model-loading orchestration (STT / TTS / LLM / VLM routing).
  *
- * 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.
+ * 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.
  */
 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 { inferModelFromFilename, sanitizeId } from './ModelFileInference';
+import { extractTarGz } from './ArchiveUtility';
 // Re-export types so existing imports from './Infrastructure/ModelManager' still work
 export { ModelCategory, LLMFramework, ModelStatus, DownloadStage };
 // ---------------------------------------------------------------------------
@@ -35,38 +38,48 @@ class ModelManagerImpl {
     metadata = {};
     /** Pluggable VLM loader (set by the app via setVLMLoader) */
     vlmLoader = null;
-    /** Pluggable model loaders — registered by backend providers */
+    /** Pluggable model loaders — registered by the Public layer during init */
     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 ---
+    // --- 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.
+     */
     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) {
@@ -75,18 +88,24 @@ 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
+            // Not supported or denied — non-critical
         }
     }
+    /**
+     * 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() {
-        // Ensure OPFS is initialized before checking for previously downloaded models.
-        // initStorage() is idempotent — returns immediately if already done.
-        await this.storage.initialize();
+        // Load persisted metadata (lastUsedAt timestamps)
         this.metadata = await this.storage.loadMetadata();
         for (const model of this.registry.getModels()) {
             if (model.status !== ModelStatus.Registered)
@@ -95,6 +114,7 @@ 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);
@@ -109,17 +129,34 @@ class ModelManagerImpl {
                 // Not in OPFS, keep as registered
             }
         }
+        // Persist any newly created metadata entries
         await this.storage.saveMetadata(this.metadata);
     }
-    // --- 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(); }
+    // --- 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();
+    }
     getLoadedModel(category) {
         if (category) {
             const id = this.loadedByCategory.get(category);
@@ -131,84 +168,69 @@ 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 ---
+    // --- 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.
+     */
     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 Import (file picker / drag-drop) ---
+    // --- Model loading orchestration ---
     /**
-     * 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.
+     * Load a model by ID.
      *
-     * @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)
+     * @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.
      */
-    async importModel(file, modelId) {
-        const 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
-            if (meta.id !== id) {
-                return this.importModel(file, meta.id);
-            }
-        }
-        logger.info(`Importing model from file: ${file.name} (${(file.size / 1024 / 1024).toFixed(1)} MB) -> ${id}`);
-        const data = new Uint8Array(await file.arrayBuffer());
-        await this.downloader.storeInOPFS(id, data);
-        this.registry.updateModel(id, {
-            status: ModelStatus.Downloaded,
-            sizeBytes: data.length,
-        });
-        this.touchLastUsed(id, data.length);
-        EventBus.shared.emit('model.imported', SDKEventType.Model, {
-            modelId: id,
-            filename: file.name,
-            sizeBytes: data.length,
-        });
-        logger.info(`Model imported: ${id} (${(data.length / 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}`);
@@ -216,41 +238,61 @@ 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) {
-                await this.loadVLMModel(model, modelId);
-            }
-            else if (model.modality === ModelCategory.SpeechRecognition) {
-                const data = await this.downloader.loadFromOPFS(modelId);
-                if (!data)
+                // 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) {
                     throw new Error('Model not downloaded — please download the model first.');
-                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);
+                }
+                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);
+                }
             }
             else {
                 const data = await this.downloader.loadFromOPFS(modelId);
-                if (!data)
+                if (!data) {
                     throw new Error('Model not downloaded — please download the model first.');
-                await this.loadLLMModel(model, modelId, data);
+                }
+                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);
+                }
             }
             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;
         }
@@ -271,7 +313,17 @@ 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;
@@ -283,13 +335,16 @@ 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) {
@@ -299,6 +354,7 @@ 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 = {};
@@ -342,18 +398,22 @@ 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 ---
+    // --- Subscriptions (delegated to registry) ---
     onChange(callback) {
         return this.registry.onChange(callback);
     }
@@ -361,148 +421,423 @@ class ModelManagerImpl {
     // Private — model loading by modality
     // ---------------------------------------------------------------------------
     /**
-     * Build a ModelLoadContext for passing to backend loaders.
-     */
-    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 LLM model into the RACommons Emscripten FS.
-     * This logic stays in core because WASMBridge is in core.
+     * Load an LLM/VLM model into the RACommons Emscripten FS.
      */
     async loadLLMModel(model, modelId, data) {
         const fsDir = `/models`;
         const fsPath = `${fsDir}/${modelId}.gguf`;
-        // Write to Emscripten FS
-        const bridge = WASMBridge.shared;
-        if (!bridge.isLoaded) {
-            throw new Error('WASM module not loaded — SDK not initialized.');
+        if (model.modality === ModelCategory.Multimodal) {
+            // VLM models are loaded in a dedicated Web Worker that reads from OPFS.
         }
-        // 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.');
+        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}`);
         }
-        m.FS_createPath('/', 'models', true, true);
-        try {
-            m.FS_unlink(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}`);
         }
-        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 (!this.llmLoader)
-            throw new Error('No LLM loader registered. Register the @runanywhere/web-llamacpp package.');
-        await this.llmLoader.loadModel(fsPath, modelId, model.name);
-        logger.info(`LLM model loaded: ${modelId}`);
     }
     /**
-     * Load a VLM (vision-language) model via the pluggable VLM loader.
+     * 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.
      */
-    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;
+    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);
         }
-        // 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}`);
+        else {
+            await this.loadSTTFromIndividualFiles(model, primaryData, sherpa, modelDir);
+        }
+        logger.info(`STT model loaded via sherpa-onnx: ${model.id}`);
     }
     /**
-     * Load an STT model via the pluggable loader.
-     * All sherpa-onnx FS operations are handled by the loader.
+     * Load an STT model from a .tar.gz archive (matching Swift SDK approach).
+     * Extracts encoder, decoder, and tokens from the archive automatically.
      */
-    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}`);
+    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}`);
+        }
+    }
+    /**
+     * Load an STT model from individual downloaded files (legacy path).
+     */
+    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}`);
+        }
     }
     /**
-     * Load a TTS model via the pluggable loader.
-     * All sherpa-onnx FS operations are handled by the loader.
+     * 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.
      */
-    async loadTTSModel(model, data) {
+    async loadTTSModel(model, primaryData) {
         if (!this.ttsLoader)
-            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}`);
+            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}`);
     }
     /**
-     * Load a VAD model via the pluggable loader.
-     * All sherpa-onnx FS operations are handled by the loader.
+     * 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.
      */
     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. Register the @runanywhere/web-onnx package.');
-        const ctx = this.buildLoadContext(model, data);
-        await this.vadLoader.loadModelFromData(ctx);
+            throw new Error('No VAD loader registered. Call ModelManager.setVADLoader() first.');
+        await this.vadLoader.loadModel({ modelPath: fsPath });
         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);
@@ -525,12 +860,14 @@ class ModelManagerImpl {
             else {
                 await this.llmLoader?.unloadModel();
             }
-            // Clean up Emscripten FS model files for LLM models
+            // 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) {
-                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
                         const m = bridge.module;
                         const fsPath = `/models/${modelId}.gguf`;
                         try {
@@ -541,7 +878,7 @@ class ModelManagerImpl {
                     }
                 }
                 catch {
-                    // Non-critical
+                    // Non-critical — FS cleanup is best-effort
                 }
             }
         }