react-native-sherpa-onnx 0.2.0 → 0.3.0

package/lib/module/download/ModelDownloadManager.js

@@ -0,0 +1,918 @@
+"use strict";
+
+import { Alert, Platform } from 'react-native';
+import { DocumentDirectoryPath, exists, readFile, mkdir, writeFile, readDir, stat, unlink, downloadFile, stopDownload } from '@dr.pogodin/react-native-fs';
+import { extractTarBz2 } from "./extractTarBz2.js";
+import { parseChecksumFile, validateChecksum, validateExtractedFiles, checkDiskSpace } from "./validation.js";
+const RELEASE_API_BASE = 'https://api.github.com/repos/k2-fsa/sherpa-onnx/releases/tags';
+const CACHE_TTL_MINUTES = 24 * 60;
+const MODEL_ARCHIVE_EXT = '.tar.bz2';
+const MODEL_ONNX_EXT = '.onnx';
+export let ModelCategory = /*#__PURE__*/function (ModelCategory) {
+  ModelCategory["Tts"] = "tts";
+  ModelCategory["Stt"] = "stt";
+  ModelCategory["Vad"] = "vad";
+  ModelCategory["Diarization"] = "diarization";
+  ModelCategory["Enhancement"] = "enhancement";
+  ModelCategory["Separation"] = "separation";
+  return ModelCategory;
+}({});
+
+/** TTS model type for meta; 'unknown' when id could not be classified. */
+
+const promptChecksumFallback = issue => new Promise(resolve => {
+  const reasonText = issue.reason === 'CHECKSUM_FAILED' ? 'Failed to compute checksum.' : 'Computed checksum does not match the expected value.';
+  const body = `${reasonText}\n\n${issue.message}\n\nDo you want to keep the file and continue?`;
+  Alert.alert('Checksum Problem', body, [{
+    text: 'Delete and cancel',
+    style: 'destructive',
+    onPress: () => resolve(false)
+  }, {
+    text: 'Keep file',
+    style: 'default',
+    onPress: () => resolve(true)
+  }]);
+});
+const memoryCacheByCategory = {};
+const checksumCacheByCategory = {};
+const downloadProgressListeners = new Set();
+const modelsListUpdatedListeners = new Set();
+export const subscribeDownloadProgress = listener => {
+  downloadProgressListeners.add(listener);
+  return () => {
+    downloadProgressListeners.delete(listener);
+  };
+};
+const emitDownloadProgress = (category, modelId, progress) => {
+  for (const listener of downloadProgressListeners) {
+    try {
+      listener(category, modelId, progress);
+    } catch (error) {
+      console.warn('Download progress listener error:', error);
+    }
+  }
+};
+export const subscribeModelsListUpdated = listener => {
+  modelsListUpdatedListeners.add(listener);
+  return () => {
+    modelsListUpdatedListeners.delete(listener);
+  };
+};
+const emitModelsListUpdated = (category, models) => {
+  for (const listener of modelsListUpdatedListeners) {
+    try {
+      listener(category, models);
+    } catch (error) {
+      console.warn('Models list listener error:', error);
+    }
+  }
+};
+const CATEGORY_CONFIG = {
+  [ModelCategory.Tts]: {
+    tag: 'tts-models',
+    cacheFile: 'tts-models.json',
+    baseDir: `${DocumentDirectoryPath}/sherpa-onnx/models/tts`
+  },
+  [ModelCategory.Stt]: {
+    tag: 'asr-models',
+    cacheFile: 'asr-models.json',
+    baseDir: `${DocumentDirectoryPath}/sherpa-onnx/models/stt`
+  },
+  [ModelCategory.Vad]: {
+    tag: 'asr-models',
+    cacheFile: 'vad-models.json',
+    baseDir: `${DocumentDirectoryPath}/sherpa-onnx/models/vad`
+  },
+  [ModelCategory.Diarization]: {
+    tag: 'speaker-segmentation-models',
+    cacheFile: 'diarization-models.json',
+    baseDir: `${DocumentDirectoryPath}/sherpa-onnx/models/diarization`
+  },
+  [ModelCategory.Enhancement]: {
+    tag: 'speech-enhancement-models',
+    cacheFile: 'enhancement-models.json',
+    baseDir: `${DocumentDirectoryPath}/sherpa-onnx/models/enhancement`
+  },
+  [ModelCategory.Separation]: {
+    tag: 'source-separation-models',
+    cacheFile: 'separation-models.json',
+    baseDir: `${DocumentDirectoryPath}/sherpa-onnx/models/separation`
+  }
+};
+function getCacheDir() {
+  return `${DocumentDirectoryPath}/sherpa-onnx/cache`;
+}
+function getCachePath(category) {
+  return `${getCacheDir()}/${CATEGORY_CONFIG[category].cacheFile}`;
+}
+function getModelsBaseDir(category) {
+  return CATEGORY_CONFIG[category].baseDir;
+}
+function getModelDir(category, modelId) {
+  return `${getModelsBaseDir(category)}/${modelId}`;
+}
+function getArchiveFilename(modelId, archiveExt) {
+  return `${modelId}.${archiveExt}`;
+}
+function getArchivePath(category, modelId, archiveExt) {
+  const filename = getArchiveFilename(modelId, archiveExt);
+  if (archiveExt === 'onnx') {
+    return `${getModelDir(category, modelId)}/${filename}`;
+  }
+  return `${getModelsBaseDir(category)}/${filename}`;
+}
+function getTarArchivePath(category, modelId) {
+  return getArchivePath(category, modelId, 'tar.bz2');
+}
+function getOnnxPath(category, modelId) {
+  return getArchivePath(category, modelId, 'onnx');
+}
+function getReadyMarkerPath(category, modelId) {
+  return `${getModelDir(category, modelId)}/.ready`;
+}
+function getManifestPath(category, modelId) {
+  return `${getModelDir(category, modelId)}/manifest.json`;
+}
+function getReleaseUrl(category) {
+  return `${RELEASE_API_BASE}/${CATEGORY_CONFIG[category].tag}`;
+}
+
+/**
+ * Retry helper with exponential backoff
+ * @param fn - The async function to retry
+ * @param options - Retry configuration
+ * @returns The result of the function
+ * @throws The last error if all retries fail or AbortError if aborted
+ */
+async function retryWithBackoff(fn, options = {}) {
+  const maxRetries = options.maxRetries ?? 3;
+  const initialDelayMs = options.initialDelayMs ?? 1000;
+  const maxDelayMs = options.maxDelayMs ?? 10000;
+  const backoffFactor = options.backoffFactor ?? 2;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (options.signal?.aborted) {
+      const abortError = new Error('Operation aborted');
+      abortError.name = 'AbortError';
+      throw abortError;
+    }
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Don't retry on abort
+      if (lastError.name === 'AbortError' || options.signal?.aborted) {
+        throw lastError;
+      }
+
+      // If this was the last attempt, throw the error
+      if (attempt === maxRetries) {
+        throw lastError;
+      }
+
+      // Calculate delay with exponential backoff
+      const delayMs = Math.min(initialDelayMs * Math.pow(backoffFactor, attempt), maxDelayMs);
+      console.warn(`Retry attempt ${attempt + 1}/${maxRetries} after ${delayMs}ms due to:`, lastError.message);
+
+      // Wait before retrying
+      await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+  }
+  throw lastError ?? new Error('Retry failed with no error');
+}
+async function fetchChecksumsFromRelease(category) {
+  // Return cached if available
+  if (checksumCacheByCategory[category]) {
+    return checksumCacheByCategory[category];
+  }
+  try {
+    const checksums = await retryWithBackoff(async () => {
+      const response = await fetch(`https://github.com/k2-fsa/sherpa-onnx/releases/download/${CATEGORY_CONFIG[category].tag}/checksum.txt`);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch checksum.txt for ${category}: ${response.status}`);
+      }
+      const content = await response.text();
+      return parseChecksumFile(content);
+    }, {
+      maxRetries: 3,
+      initialDelayMs: 1000
+    });
+    checksumCacheByCategory[category] = checksums;
+    return checksums;
+  } catch (error) {
+    console.warn(`SherpaOnnxChecksum: Error fetching checksums for ${category}:`, error);
+    return new Map();
+  }
+}
+function toTitleCase(value) {
+  return value.split(/[-_\s]+/g).filter(Boolean).map(token => token[0].toUpperCase() + token.slice(1)).join(' ');
+}
+function deriveDisplayName(id) {
+  const cleaned = id.replace(/^sherpa-onnx-/, '');
+  return toTitleCase(cleaned);
+}
+function deriveType(id) {
+  const lower = id.toLowerCase();
+  if (lower.includes('vits')) return 'vits';
+  if (lower.includes('kokoro')) return 'kokoro';
+  if (lower.includes('matcha')) return 'matcha';
+  if (lower.includes('kitten')) return 'kitten';
+  if (lower.includes('pocket')) return 'pocket';
+  if (lower.includes('zipvoice')) return 'zipvoice';
+  return 'unknown';
+}
+function deriveQuantization(id) {
+  const lower = id.toLowerCase();
+  if (lower.includes('int8') && lower.includes('quant')) {
+    return 'int8-quantized';
+  }
+  if (lower.includes('int8')) return 'int8';
+  if (lower.includes('fp16')) return 'fp16';
+  return 'unknown';
+}
+function deriveSizeTier(id) {
+  const lower = id.toLowerCase();
+  if (lower.includes('tiny')) return 'tiny';
+  if (lower.includes('small')) return 'small';
+  if (lower.includes('medium')) return 'medium';
+  if (lower.includes('large')) return 'large';
+  if (lower.includes('low')) return 'small';
+  return 'unknown';
+}
+function deriveLanguages(id) {
+  const tokens = id.split(/[-_]+/g);
+  const languages = new Set();
+  for (const token of tokens) {
+    if (/^[a-z]{2}$/.test(token)) {
+      languages.add(token);
+      continue;
+    }
+    if (/^[a-z]{2}[A-Z]{2}$/.test(token)) {
+      languages.add(token.slice(0, 2).toLowerCase());
+      continue;
+    }
+    if (/^[a-z]{2}-[A-Z]{2}$/.test(token)) {
+      languages.add(token.slice(0, 2).toLowerCase());
+    }
+  }
+  return Array.from(languages);
+}
+function getAssetExtension(name) {
+  if (name.endsWith(MODEL_ARCHIVE_EXT)) return 'tar.bz2';
+  if (name.endsWith(MODEL_ONNX_EXT)) return 'onnx';
+  return null;
+}
+function stripAssetExtension(name, ext) {
+  const suffix = `.${ext}`;
+  return name.endsWith(suffix) ? name.slice(0, -suffix.length) : name;
+}
+function isAssetSupportedForCategory(category, name, ext) {
+  const lower = name.toLowerCase();
+  switch (category) {
+    case ModelCategory.Tts:
+      return ext === 'tar.bz2';
+    case ModelCategory.Stt:
+      return ext === 'tar.bz2' && !lower.includes('vad');
+    case ModelCategory.Vad:
+      return ext === 'onnx' && lower.includes('vad');
+    case ModelCategory.Diarization:
+      return ext === 'tar.bz2';
+    case ModelCategory.Enhancement:
+      return ext === 'onnx';
+    case ModelCategory.Separation:
+      return ext === 'tar.bz2' || ext === 'onnx';
+    default:
+      return false;
+  }
+}
+function parseDigestSha256(value) {
+  if (!value) return undefined;
+  const match = value.match(/^sha256:([a-f0-9]{64})$/i);
+  return match?.[1]?.toLowerCase();
+}
+function toTtsModelMeta(asset, archiveExt) {
+  if (archiveExt !== 'tar.bz2') {
+    return null;
+  }
+  const id = stripAssetExtension(asset.name, archiveExt);
+  const type = deriveType(id);
+  if (type === 'unknown') {
+    console.warn('SherpaOnnxModelList: Unsupported model', id);
+  }
+  return {
+    id,
+    displayName: deriveDisplayName(id),
+    type,
+    languages: deriveLanguages(id),
+    quantization: deriveQuantization(id),
+    sizeTier: deriveSizeTier(id),
+    downloadUrl: asset.browser_download_url,
+    archiveExt,
+    bytes: asset.size,
+    sha256: parseDigestSha256(asset.digest),
+    category: ModelCategory.Tts
+  };
+}
+function toGenericModelMeta(category, asset, archiveExt) {
+  const id = stripAssetExtension(asset.name, archiveExt);
+  return {
+    id,
+    displayName: deriveDisplayName(id),
+    downloadUrl: asset.browser_download_url,
+    archiveExt,
+    bytes: asset.size,
+    sha256: parseDigestSha256(asset.digest),
+    category
+  };
+}
+function toModelMeta(category, asset) {
+  const archiveExt = getAssetExtension(asset.name);
+  if (!archiveExt) return null;
+  if (!isAssetSupportedForCategory(category, asset.name, archiveExt)) {
+    return null;
+  }
+  if (category === ModelCategory.Tts) {
+    return toTtsModelMeta(asset, archiveExt);
+  }
+  return toGenericModelMeta(category, asset, archiveExt);
+}
+async function loadCacheFromDisk(category) {
+  const memoryCache = memoryCacheByCategory[category];
+  if (memoryCache) return memoryCache;
+  const cachePath = getCachePath(category);
+  const existsResult = await exists(cachePath);
+  if (!existsResult) return null;
+  const raw = await readFile(cachePath, 'utf8');
+  const parsed = JSON.parse(raw);
+  memoryCacheByCategory[category] = parsed;
+  return parsed;
+}
+async function saveCache(category, payload) {
+  const cacheDir = getCacheDir();
+  await mkdir(cacheDir);
+  await writeFile(getCachePath(category), JSON.stringify(payload), 'utf8');
+  memoryCacheByCategory[category] = payload;
+}
+function isCacheFresh(payload, ttlMinutes) {
+  const updated = new Date(payload.lastUpdated).getTime();
+  if (!updated) return false;
+  const ageMs = Date.now() - updated;
+  return ageMs < ttlMinutes * 60 * 1000;
+}
+export async function listModelsByCategory(category) {
+  const cache = await loadCacheFromDisk(category);
+  return cache?.models ?? [];
+}
+export async function refreshModelsByCategory(category, options) {
+  const ttl = options?.cacheTtlMinutes ?? CACHE_TTL_MINUTES;
+  const cached = await loadCacheFromDisk(category);
+  if (!options?.forceRefresh && cached && isCacheFresh(cached, ttl)) {
+    return cached.models;
+  }
+  try {
+    const body = await retryWithBackoff(async () => {
+      const response = await fetch(getReleaseUrl(category));
+      if (!response.ok) {
+        throw new Error(`Failed to fetch models: ${response.status}`);
+      }
+      return response.json();
+    }, {
+      maxRetries: options?.maxRetries ?? 3,
+      initialDelayMs: 1000,
+      signal: options?.signal
+    });
+    const assets = Array.isArray(body?.assets) ? body.assets : [];
+    const models = assets.map(asset => toModelMeta(category, {
+      name: asset.name,
+      size: asset.size,
+      browser_download_url: asset.browser_download_url,
+      digest: asset.digest
+    })).filter(model => Boolean(model));
+
+    // Load and attach SHA256 checksums from checksum.txt
+    const checksums = await fetchChecksumsFromRelease(category);
+    for (const model of models) {
+      const archiveFilename = getArchiveFilename(model.id, model.archiveExt);
+      const sha256 = checksums.get(archiveFilename);
+      if (sha256) {
+        model.sha256 = sha256;
+      } else if (model.sha256) {
+        model.sha256 = model.sha256.toLowerCase();
+      }
+    }
+    const payload = {
+      lastUpdated: new Date().toISOString(),
+      models
+    };
+    await saveCache(category, payload);
+    emitModelsListUpdated(category, models);
+    return models;
+  } catch (error) {
+    // If retry failed and we have cached data, return it as fallback
+    if (cached) {
+      console.warn(`Failed to refresh models for ${category}, using cached data:`, error);
+      return cached.models;
+    }
+    throw error;
+  }
+}
+export async function getModelsCacheStatusByCategory(category) {
+  const cached = await loadCacheFromDisk(category);
+  if (!cached) {
+    return {
+      lastUpdated: null,
+      source: 'cache'
+    };
+  }
+  return {
+    lastUpdated: cached.lastUpdated,
+    source: 'cache'
+  };
+}
+export async function getModelByIdByCategory(category, id) {
+  const models = await listModelsByCategory(category);
+  return models.find(model => model.id === id) ?? null;
+}
+export async function listDownloadedModelsByCategory(category) {
+  const baseDir = getModelsBaseDir(category);
+  const existsResult = await exists(baseDir);
+  if (!existsResult) return [];
+  const entries = await readDir(baseDir);
+  const models = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const manifestPath = getManifestPath(category, entry.name);
+    const manifestExists = await exists(manifestPath);
+    // Only list models that have a manifest (download + extraction fully complete).
+    // Directories without manifest are still being extracted and must not appear in the list.
+    if (!manifestExists) continue;
+    try {
+      const raw = await readFile(manifestPath, 'utf8');
+      const manifest = JSON.parse(raw);
+      if (manifest.model) {
+        models.push(manifest.model);
+      }
+    } catch {
+      // ignore invalid manifest
+    }
+  }
+  return models;
+}
+export async function isModelDownloadedByCategory(category, id) {
+  const readyPath = getReadyMarkerPath(category, id);
+  return exists(readyPath);
+}
+export async function getLocalModelPathByCategory(category, id) {
+  const ready = await isModelDownloadedByCategory(category, id);
+  if (!ready) return null;
+
+  // Update lastUsed timestamp when model is accessed
+  await updateModelLastUsed(category, id);
+  return getModelDir(category, id);
+}
+export async function downloadModelByCategory(category, id, opts) {
+  const isAborted = () => Boolean(opts?.signal?.aborted);
+  if (opts?.signal?.aborted) {
+    const abortError = new Error('Download aborted');
+    abortError.name = 'AbortError';
+    throw abortError;
+  }
+  const model = await getModelByIdByCategory(category, id);
+  if (!model) {
+    throw new Error(`Unknown model id: ${id}`);
+  }
+  const baseDir = getModelsBaseDir(category);
+  await mkdir(baseDir);
+  const downloadPath = getArchivePath(category, id, model.archiveExt);
+  const isArchive = model.archiveExt === 'tar.bz2';
+  const modelDir = getModelDir(category, id);
+  const sleep = ms => new Promise(resolve => {
+    setTimeout(resolve, ms);
+  });
+  const cleanupPartial = async () => {
+    if (!isArchive) {
+      return;
+    }
+
+    // Only clean up extracted model dir, preserve archive for download resume
+    if (await exists(modelDir)) {
+      await unlink(modelDir);
+    }
+  };
+  const cleanupPartialWithRetry = async () => {
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      await cleanupPartial();
+      if (!(await exists(modelDir))) {
+        return;
+      }
+      await sleep(400);
+    }
+    if (await exists(modelDir)) {
+      console.warn(`Model cleanup after abort did not fully complete for ${category}:${id}`);
+    }
+  };
+
+  // Step 1: Check available disk space
+  const diskSpaceCheck = await checkDiskSpace(model.bytes);
+  if (!diskSpaceCheck.success) {
+    throw new Error(`Insufficient disk space: ${diskSpaceCheck.message}`);
+  }
+  if (opts?.overwrite) {
+    if (await exists(modelDir)) {
+      await unlink(modelDir);
+    }
+    if (await exists(downloadPath)) {
+      await unlink(downloadPath);
+    }
+  } else {
+    // Clean up incomplete extractions but preserve partial downloads for resume
+    const readyMarkerExists = await exists(getReadyMarkerPath(category, id));
+    if (!readyMarkerExists) {
+      if (isArchive) {
+        // No ready marker found; only clean up extracted model dir
+        // Keep archive file to support download resume
+        if (await exists(modelDir)) {
+          // Removing partial model dir
+          await unlink(modelDir);
+        }
+      }
+    }
+  }
+  try {
+    // Step 2: Download archive or onnx file (with resume support)
+    if (!isArchive) {
+      await mkdir(modelDir);
+    }
+    const archiveExists = await exists(downloadPath);
+    let partialDownload = false;
+    if (archiveExists) {
+      // Check if this is a complete download or partial
+      const statResult = await stat(downloadPath);
+      const currentSize = statResult.size;
+      if (currentSize < model.bytes) {
+        partialDownload = true;
+        console.log(`[Download] Resuming partial download for ${category}:${id} (${currentSize}/${model.bytes} bytes)`);
+      }
+    }
+    if (!archiveExists || partialDownload) {
+      const maxRetries = opts?.maxRetries ?? 2;
+      await retryWithBackoff(async () => {
+        const downloadStartTime = Date.now();
+        const download = downloadFile({
+          fromUrl: model.downloadUrl,
+          toFile: downloadPath,
+          progressDivider: 1,
+          resumable: () => {
+            // iOS only: Called when download is resumed
+            console.log(`[Download] Resuming download for ${category}:${id}`);
+          },
+          progress: data => {
+            if (isAborted()) {
+              return;
+            }
+            const total = data.contentLength || model.bytes || 0;
+            const percent = total > 0 ? data.bytesWritten / total * 100 : 0;
+
+            // Calculate speed and ETA
+            const now = Date.now();
+            const elapsedSeconds = (now - downloadStartTime) / 1000;
+            let speed;
+            let eta;
+            if (elapsedSeconds > 0.5) {
+              // Calculate overall speed (bytes per second)
+              speed = data.bytesWritten / elapsedSeconds;
+
+              // Calculate ETA based on current speed
+              const remainingBytes = total - data.bytesWritten;
+              if (speed > 0) {
+                eta = remainingBytes / speed;
+              }
+            }
+            const progress = {
+              bytesDownloaded: data.bytesWritten,
+              totalBytes: total,
+              percent,
+              phase: 'downloading',
+              speed,
+              eta
+            };
+            opts?.onProgress?.(progress);
+            emitDownloadProgress(category, id, progress);
+          }
+        });
+        let downloadFinished = false;
+        let aborted = false;
+        const onAbort = () => {
+          aborted = true;
+          if (downloadFinished) return;
+          try {
+            stopDownload(download.jobId);
+          } catch {
+            // Swallow stop errors to avoid crashing the app on cancel.
+          }
+        };
+        if (opts?.signal) {
+          opts.signal.addEventListener('abort', onAbort);
+        }
+        let result;
+        try {
+          result = await download.promise;
+        } finally {
+          downloadFinished = true;
+          if (opts?.signal) {
+            opts.signal.removeEventListener('abort', onAbort);
+          }
+        }
+        if (aborted || opts?.signal?.aborted) {
+          const abortError = new Error('Download aborted');
+          abortError.name = 'AbortError';
+          throw abortError;
+        }
+        if (result.statusCode && result.statusCode >= 400) {
+          // For certain errors, delete partial download as resume won't help
+          const isNonResumableError = result.statusCode === 404 ||
+          // Not found
+          result.statusCode === 410 ||
+          // Gone
+          result.statusCode === 451 ||
+          // Unavailable for legal reasons
+          result.statusCode === 416; // Range not satisfiable
+          if (isNonResumableError && (await exists(downloadPath))) {
+            console.warn(`[Download] Non-resumable error ${result.statusCode}, removing partial download`);
+            await unlink(downloadPath);
+          }
+          throw new Error(`Download failed: ${result.statusCode}`);
+        }
+      }, {
+        maxRetries,
+        initialDelayMs: 2000,
+        signal: opts?.signal
+      });
+    }
+    if (opts?.signal?.aborted) {
+      const abortError = new Error('Download aborted');
+      abortError.name = 'AbortError';
+      throw abortError;
+    }
+    let extractResult = null;
+    /** Total uncompressed bytes from libarchive progress; used for manifest.sizeOnDisk. */
+    let extractedTotalBytes = 0;
+    if (isArchive) {
+      await mkdir(modelDir);
+      const extractStartTime = Date.now();
+      extractResult = await extractTarBz2(downloadPath, modelDir, true, evt => {
+        if (isAborted()) {
+          return;
+        }
+        if (evt.totalBytes > 0) extractedTotalBytes = evt.totalBytes;
+        if (model.bytes > 0) {
+          // Calculate extraction speed and ETA
+          const now = Date.now();
+          const elapsedSeconds = (now - extractStartTime) / 1000;
+          let speed;
+          let eta;
+          if (elapsedSeconds > 0.5) {
+            speed = evt.bytes / elapsedSeconds;
+            const remainingBytes = evt.totalBytes - evt.bytes;
+            if (speed > 0) {
+              eta = remainingBytes / speed;
+            }
+          }
+          const progress = {
+            bytesDownloaded: evt.bytes,
+            totalBytes: evt.totalBytes,
+            percent: evt.percent,
+            phase: 'extracting',
+            speed,
+            eta
+          };
+          opts?.onProgress?.(progress);
+          emitDownloadProgress(category, id, progress);
+        }
+      }, opts?.signal);
+    }
+
+    // Step 3: Validate checksum if available
+    if (model.sha256) {
+      const expectedSha = model.sha256.toLowerCase();
+      let issue = null;
+      if (isArchive) {
+        const nativeSha = extractResult?.sha256?.toLowerCase();
+        if (!nativeSha) {
+          issue = {
+            category,
+            id,
+            archivePath: downloadPath,
+            expected: model.sha256,
+            message: 'Native SHA-256 not available after extraction.',
+            reason: 'CHECKSUM_FAILED'
+          };
+        } else if (nativeSha !== expectedSha) {
+          issue = {
+            category,
+            id,
+            archivePath: downloadPath,
+            expected: model.sha256,
+            message: `Checksum mismatch: expected ${model.sha256}, got ${extractResult?.sha256}`,
+            reason: 'CHECKSUM_MISMATCH'
+          };
+        }
+      } else {
+        const checksumResult = await validateChecksum(downloadPath, expectedSha);
+        if (!checksumResult.success) {
+          issue = {
+            category,
+            id,
+            archivePath: downloadPath,
+            expected: model.sha256,
+            message: checksumResult.message ?? 'Checksum validation failed.',
+            reason: checksumResult.error === 'CHECKSUM_MISMATCH' ? 'CHECKSUM_MISMATCH' : 'CHECKSUM_FAILED'
+          };
+        }
+      }
+      if (issue) {
+        const keepFile = opts?.onChecksumIssue ? await opts.onChecksumIssue(issue) : await promptChecksumFallback(issue);
+        if (!keepFile) {
+          if (await exists(modelDir)) {
+            await unlink(modelDir);
+          }
+          if (await exists(downloadPath)) {
+            await unlink(downloadPath);
+          }
+          throw new Error(`Checksum validation failed: ${issue.message}`);
+        }
+      }
+    }
+    if (opts?.signal?.aborted) {
+      const abortError = new Error('Download aborted');
+      abortError.name = 'AbortError';
+      throw abortError;
+    }
+
+    // Step 4: Validate extracted files exist
+    const filesValidation = await validateExtractedFiles(modelDir, category);
+    if (!filesValidation.success) {
+      // Clean up failed extraction
+      await unlink(modelDir);
+      throw new Error(`Extracted files validation failed: ${filesValidation.message}`);
+    }
+    await writeFile(getReadyMarkerPath(category, id), 'ready', 'utf8');
+    const now = new Date().toISOString();
+    let sizeOnDisk;
+    if (isArchive && extractedTotalBytes > 0) {
+      sizeOnDisk = extractedTotalBytes;
+    } else if (!isArchive) {
+      try {
+        const statResult = await stat(downloadPath);
+        sizeOnDisk = statResult.size;
+      } catch {
+        // ignore
+      }
+    }
+    await writeFile(getManifestPath(category, id), JSON.stringify({
+      downloadedAt: now,
+      lastUsed: now,
+      model,
+      sizeOnDisk
+    }), 'utf8');
+
+    // Notify subscribers (e.g. STT/TTS screens) so the model list updates without leaving the screen.
+    const list = await listDownloadedModelsByCategory(category);
+    emitModelsListUpdated(category, list);
+    return {
+      modelId: id,
+      localPath: modelDir
+    };
+  } catch (err) {
+    if (err instanceof Error && err.name === 'AbortError' || isAborted()) {
+      await cleanupPartialWithRetry();
+    }
+    throw err;
+  }
+}
+
+/**
+ * Update the lastUsed timestamp for a downloaded model
+ */
+export async function updateModelLastUsed(category, id) {
+  const manifestPath = getManifestPath(category, id);
+  const existsResult = await exists(manifestPath);
+  if (!existsResult) return;
+  try {
+    const raw = await readFile(manifestPath, 'utf8');
+    const manifest = JSON.parse(raw);
+    manifest.lastUsed = new Date().toISOString();
+    await writeFile(manifestPath, JSON.stringify(manifest), 'utf8');
+  } catch (error) {
+    console.warn(`Failed to update lastUsed for ${category}:${id}:`, error);
+  }
+}
+
+/**
+ * Get all downloaded models with LRU metadata
+ */
+export async function listDownloadedModelsWithMetadata(category) {
+  const baseDir = getModelsBaseDir(category);
+  const existsResult = await exists(baseDir);
+  if (!existsResult) return [];
+  const entries = await readDir(baseDir);
+  const modelsWithMetadata = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const manifestPath = getManifestPath(category, entry.name);
+    const manifestExists = await exists(manifestPath);
+    if (manifestExists) {
+      try {
+        const raw = await readFile(manifestPath, 'utf8');
+        const manifest = JSON.parse(raw);
+        if (manifest.model) {
+          modelsWithMetadata.push({
+            model: manifest.model,
+            downloadedAt: manifest.downloadedAt,
+            lastUsed: manifest.lastUsed ?? null,
+            sizeOnDisk: manifest.sizeOnDisk ?? entry.size
+          });
+        }
+      } catch (error) {
+        console.warn(`Failed to read manifest for ${category}:${entry.name}:`, error);
+      }
+    }
+  }
+  return modelsWithMetadata;
+}
+
+/**
+ * Remove least recently used models to free up disk space
+ * @param category - Model category
+ * @param targetBytes - Target amount of bytes to free (optional)
+ * @param maxModelsToDelete - Maximum number of models to delete (default: no limit)
+ * @returns Array of deleted model IDs
+ */
+export async function cleanupLeastRecentlyUsed(category, options) {
+  const modelsWithMetadata = await listDownloadedModelsWithMetadata(category);
+  if (modelsWithMetadata.length === 0) {
+    return [];
+  }
+
+  // Keep at least this many models
+  const keepCount = options?.keepCount ?? 1;
+  if (modelsWithMetadata.length <= keepCount) {
+    return [];
+  }
+
+  // Sort by lastUsed (oldest first), then by downloadedAt if no lastUsed
+  const sorted = modelsWithMetadata.sort((a, b) => {
+    const aTime = a.lastUsed ?? a.downloadedAt;
+    const bTime = b.lastUsed ?? b.downloadedAt;
+    return new Date(aTime).getTime() - new Date(bTime).getTime();
+  });
+  const deletedIds = [];
+  let bytesFreed = 0;
+  const targetBytes = options?.targetBytes ?? 0;
+  const maxToDelete = options?.maxModelsToDelete ?? sorted.length - keepCount;
+  for (let i = 0; i < sorted.length - keepCount && i < maxToDelete; i++) {
+    const item = sorted[i];
+    if (!item) continue;
+    try {
+      await deleteModelByCategory(category, item.model.id);
+      deletedIds.push(item.model.id);
+      bytesFreed += item.sizeOnDisk ?? 0;
+      console.log(`[LRU Cleanup] Deleted ${category}:${item.model.id} (freed ${(item.sizeOnDisk ?? 0) / 1024 / 1024} MB)`);
+      if (targetBytes > 0 && bytesFreed >= targetBytes) {
+        break;
+      }
+    } catch (error) {
+      console.warn(`[LRU Cleanup] Failed to delete ${category}:${item.model.id}:`, error);
+    }
+  }
+  return deletedIds;
+}
+export async function deleteModelByCategory(category, id) {
+  const modelDir = getModelDir(category, id);
+  const tarPath = getTarArchivePath(category, id);
+  const onnxPath = getOnnxPath(category, id);
+  if (await exists(modelDir)) {
+    await unlink(modelDir);
+  }
+  if (await exists(tarPath)) {
+    await unlink(tarPath);
+  }
+  if (await exists(onnxPath)) {
+    await unlink(onnxPath);
+  }
+}
+export async function clearModelCacheByCategory(category) {
+  const cachePath = getCachePath(category);
+  if (await exists(cachePath)) {
+    await unlink(cachePath);
+  }
+  delete memoryCacheByCategory[category];
+}
+export async function getDownloadStorageBase() {
+  if (Platform.OS === 'ios') {
+    return DocumentDirectoryPath;
+  }
+  return DocumentDirectoryPath;
+}
+//# sourceMappingURL=ModelDownloadManager.js.map