Skip to content

armgit / Handy

Public Imported from GitHub
0

A free, open source, and extensible speech-to-text application that works completely offline.

133 KB
Raw Blame
use super::model_capabilities::{
    CapabilityProbe, CapabilityProber, Compatibility, GgufHeaderProber,
};
use crate::settings::{get_settings, write_settings};
use anyhow::Result;
use hf_hub::api::tokio::{ApiBuilder, CancellationToken, Progress};
use hf_hub::{Cache, Repo, RepoType};
use log::{debug, error, info, warn};
use serde::{Deserialize, Serialize};
use specta::Type;
use std::collections::{HashMap, HashSet};
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use tauri::{AppHandle, Emitter, Manager};

mod download;

use download::{
    HttpDownloadOutcome, RateMeter, DOWNLOAD_STALL_TIMEOUT, PROGRESS_THROTTLE, PROGRESS_TICK,
};

/// Where a model comes from and how Handy obtains it — the routing discriminant
/// for downloading and on-disk resolution.
#[derive(Debug, Clone, Serialize, Deserialize, Type)]
pub enum ModelSource {
    /// Direct HTTP download from a URL (current blob.handy.computer hosting).
    Url {
        url: String,
        /// Expected SHA-256 for integrity verification; `None` skips it.
        sha256: Option<String>,
    },
    /// A file inside a Hugging Face Hub repo, fetched via hf-hub into the shared
    /// HF cache (so other tools reuse it). The file within the repo is
    /// [`ModelInfo::filename`].
    HuggingFace { repo_id: String, revision: String },
    /// Already present on disk — a user-provided custom model, or one discovered
    /// in a shared cache. Nothing to download.
    Local,
}

#[derive(Debug, Clone, Serialize, Deserialize, Type)]
pub struct ModelInfo {
    pub id: String,
    pub name: String,
    pub description: String,
    pub filename: String,
    pub source: ModelSource,
    pub size_mb: u64,
    pub is_downloaded: bool,
    pub is_downloading: bool,
    pub partial_size: u64,
    pub accuracy_score: f32,        // 0.0 to 1.0, higher is more accurate
    pub speed_score: f32,           // 0.0 to 1.0, higher is faster
    pub supports_translation: bool, // Whether the model supports translating to English
    pub is_recommended: bool,       // Whether this is the recommended model for new users
    pub supported_languages: Vec<String>, // Languages this model can transcribe
    pub supports_language_selection: bool, // Whether the user can explicitly pick a language
    pub is_custom: bool,            // Whether this is a user-provided custom model
    pub supports_streaming: bool, // Whether this model supports live streaming preview (transcribe-cpp)
    pub supports_language_detection: bool, // Whether the model can auto-detect language (gates the "Auto" option)
}

const CHINESE_LANGUAGE_CODE: &str = "zh";

fn recognition_language(language: &str) -> &str {
    match language {
        "zh-Hans" | "zh-Hant" => CHINESE_LANGUAGE_CODE,
        other => other,
    }
}

/// A tag's primary language subtag, with any BCP-47 region/script suffix
/// dropped (`en-US` → `en`, `zh-Hant` → `zh`).
fn base_language(language: &str) -> &str {
    language.split(&['-', '_'][..]).next().unwrap_or(language)
}

/// The package's `languageIdentity` for a code (`no`→`nb`, `tl`→`fil`, `iw`→`he`,
/// `jw`→`jv`). For matching only: pass on the model's own code.
pub(crate) fn canonical_language_code(language: &str) -> &str {
    match base_language(language) {
        "no" => "nb",
        "tl" => "fil",
        "iw" => "he",
        "jw" => "jv",
        base => base,
    }
}

fn canonicalize_supported_languages(languages: Vec<String>) -> Vec<String> {
    let mut seen = HashSet::new();
    let mut canonical = Vec::with_capacity(languages.len());

    for language in languages {
        let language = recognition_language(&language).to_string();
        if seen.insert(language.clone()) {
            canonical.push(language);
        }
    }

    canonical
}

/// One downloadable quantization of a catalog model. (Its sha256, the trust
/// anchor for mirror downloads, stays in the catalog: see
/// `catalog::mirror_fallbacks`.)
#[derive(Debug, Clone)]
pub struct QuantFile {
    pub filename: String,
    pub quant: String,
    pub size_bytes: u64,
}

/// Pick the default quant among `files`: the one whose `quant` matches
/// `default_quant`, else the first file. The single source of the "which file do
/// we surface" rule — shared by [`ModelDescriptor::default_file`] and the
/// catalog's id construction so the two can never drift.
pub(crate) fn default_quant_file<'a>(
    files: &'a [QuantFile],
    default_quant: Option<&str>,
) -> Option<&'a QuantFile> {
    files
        .iter()
        .find(|f| Some(f.quant.as_str()) == default_quant)
        .or_else(|| files.first())
}

/// Live, on-disk status — the half of [`ModelInfo`] that isn't part of the
/// static spec. Kept separate so a descriptor stays purely descriptive and
/// status can be recomputed without rebuilding it.
#[derive(Debug, Clone, Default)]
pub struct DiskStatus {
    pub is_downloaded: bool,
    pub is_downloading: bool,
    pub partial_size: u64,
}

/// The spec of a bundled catalog model: everything in `catalog.json` normalised
/// into one shape, rendered into the frontend-facing [`ModelInfo`] via
/// [`ModelDescriptor::to_model_info`] by combining it with a [`DiskStatus`].
/// (The catalog is the only producer that routes through this; the legacy table
/// and on-disk scans build `ModelInfo` directly.)
#[derive(Debug, Clone)]
pub struct ModelDescriptor {
    pub id: String,
    pub source: ModelSource,
    pub name: String,
    pub description: String,
    pub caps: CapabilityProbe,
    pub files: Vec<QuantFile>,
    pub default_quant: Option<String>,
    pub speed_score: f32,
    pub accuracy_score: f32,
    /// Editorial sort priority across the whole catalog (lower = higher). Drives
    /// list ordering; independent of `recommended`.
    pub recommended_rank: Option<u32>,
    /// Whether this is part of the small curated set shown to new users in
    /// onboarding (and badged "Recommended"). A model can be ranked for ordering
    /// without being in this set.
    pub recommended: bool,
}

impl ModelDescriptor {
    /// The quant we surface for download/size: the declared default, else the
    /// first file.
    pub(crate) fn default_file(&self) -> Option<&QuantFile> {
        default_quant_file(&self.files, self.default_quant.as_deref())
    }

    /// Render the frontend-facing [`ModelInfo`] by combining this spec with live
    /// disk `status`.
    pub fn to_model_info(&self, status: &DiskStatus) -> ModelInfo {
        self.render_model_info(self.default_file(), status)
    }

    /// [`ModelInfo`] for one specific quant `file` of this catalog model — how
    /// alternate-quant files found on disk surface with full catalog metadata
    /// instead of as anonymous customs. The default quant keeps the plain
    /// catalog name; any other quant appends it ("Name (Q4_K_M)") so two
    /// quants of one model stay tellable apart, and only the default carries
    /// the Recommended badge. Identity stays `"{repo_id}/{filename}"`, so the
    /// default quant renders identically to the seeded entry.
    pub fn to_model_info_for_file(&self, file: &QuantFile, status: &DiskStatus) -> ModelInfo {
        self.render_model_info(Some(file), status)
    }

    fn render_model_info(&self, file: Option<&QuantFile>, status: &DiskStatus) -> ModelInfo {
        let is_default = match (file, self.default_file()) {
            (Some(f), Some(d)) => f.filename == d.filename,
            _ => true,
        };
        let id = match (&self.source, file) {
            (ModelSource::HuggingFace { repo_id, .. }, Some(f)) => {
                format!("{}/{}", repo_id, f.filename)
            }
            _ => self.id.clone(),
        };
        let name = if is_default {
            self.name.clone()
        } else {
            format!(
                "{} ({})",
                self.name,
                file.map(|f| f.quant.as_str()).unwrap_or("")
            )
        };
        let languages =
            canonicalize_supported_languages(self.caps.languages.clone().unwrap_or_default());
        ModelInfo {
            id,
            name,
            description: self.description.clone(),
            filename: file.map(|f| f.filename.clone()).unwrap_or_default(),
            source: self.source.clone(),
            size_mb: file.map(|f| f.size_bytes / (1024 * 1024)).unwrap_or(0),
            is_downloaded: status.is_downloaded,
            is_downloading: status.is_downloading,
            partial_size: status.partial_size,
            accuracy_score: self.accuracy_score,
            speed_score: self.speed_score,
            supports_translation: self.caps.supports_translation.unwrap_or(false),
            is_recommended: self.recommended && is_default,
            supports_language_selection: languages.len() > 1,
            supported_languages: languages,
            // Catalog models are always HF-sourced downloads, never user-dropped
            // custom files (those bypass the descriptor and set this directly).
            is_custom: false,
            supports_streaming: self.caps.supports_streaming.unwrap_or(false),
            supports_language_detection: self.caps.supports_language_detect.unwrap_or(false),
        }
    }
}

/// Resolve the user's persisted language *intent* (`"auto"` or a language code)
/// into the language a given model will actually use.
///
/// The canonical coercion used on every transcription path: computed at the
/// point of use and **never written back** to settings, so the user's last
/// explicit intent survives switching to an incompatible model and back.
///
/// Matching is base-aware ([`base_language`]) and returns the model's own
/// *concrete* code, so a bare intent (`en`) resolves to the exact string the
/// engine's prompt table expects (`en-US`) for models that advertise full
/// BCP-47 locales.
///
/// `preferred_languages` (`spoken_languages`) only matters when the model can't
/// detect and the intent isn't usable: a single spoken language beats English.
pub fn effective_language(
    intent: &str,
    preferred_languages: &[String],
    supported_languages: &[String],
    supports_language_detection: bool,
) -> String {
    if supported_languages.is_empty() {
        return intent.to_string();
    }

    if intent != "auto" {
        if let Some(code) = supported_code(intent, supported_languages) {
            return code.clone();
        }
    }

    if supports_language_detection {
        return "auto".to_string();
    }

    // Model can't auto-detect and the intent isn't usable: fall back to a
    // concrete language so we never hand the engine "auto". The one language
    // they speak, if the model hears it; else English; else the model's first.
    if let [only] = preferred_languages {
        if let Some(code) = supported_code(only, supported_languages) {
            return code.clone();
        }
    }
    if let Some(en) = supported_languages
        .iter()
        .find(|language| base_language(language) == "en")
    {
        return en.clone();
    }
    recognition_language(&supported_languages[0]).to_string()
}

/// The model's own code for `language`, if it hears it.
pub(crate) fn supported_code<'a>(
    language: &str,
    supported_languages: &'a [String],
) -> Option<&'a String> {
    // Exact base first, then aliases: with both `no` and `nb` listed, `nb` must pick `nb`.
    supported_languages
        .iter()
        .find(|code| base_language(code) == base_language(language))
        .or_else(|| {
            supported_languages
                .iter()
                .find(|code| canonical_language_code(code) == canonical_language_code(language))
        })
}

#[derive(Debug, Clone, Serialize, Deserialize, Type)]
pub struct DownloadProgress {
    pub model_id: String,
    pub downloaded: u64,
    pub total: u64,
    pub percentage: f64,
    /// Measured over a trailing window of this transfer only (bytes resumed
    /// from disk excluded); `None` until there is enough to measure.
    pub bytes_per_sec: Option<f64>,
}

/// Return the active HF cache followed by the pre-v0.9.6 cache for portable
/// upgrades. Downloads still use `Cache::from_env()` and therefore only write
/// to the active portable cache.
fn hf_caches() -> Vec<Cache> {
    let current = Cache::from_env();
    let mut caches = vec![current.clone()];

    if crate::portable::is_portable() {
        let legacy = crate::portable::previous_hf_home()
            .map(|home| Cache::new(home.join("hub")))
            .unwrap_or_default();
        if legacy.path() != current.path() {
            caches.push(legacy);
        }
    }

    caches
}

fn hf_cached_path(repo_id: &str, revision: &str, filename: &str) -> Option<PathBuf> {
    hf_cached_path_in(&hf_caches(), repo_id, revision, filename)
}

/// Reuse an existing file regardless of which revision originally downloaded it.
/// Prefer the requested pin, then main, then other snapshots.
fn hf_cached_path_in(
    caches: &[Cache],
    repo_id: &str,
    revision: &str,
    filename: &str,
) -> Option<PathBuf> {
    hf_cached_paths_in(caches, repo_id, revision, filename)
        .into_iter()
        .find(|path| path.is_file())
}

/// Snapshot directories in lookup order, with the active cache winning ties.
/// Shared by lookup, discovery and deletion; no catalog revision history needed.
fn hf_snapshot_paths(caches: &[Cache], repo_id: &str, revision: &str) -> Vec<PathBuf> {
    let mut snapshots = Vec::new();
    for (cache_index, cache) in caches.iter().enumerate() {
        let repo_dir = cache
            .path()
            .join(Repo::new(repo_id.to_string(), RepoType::Model).folder_name());
        let root = repo_dir.join("snapshots");
        let refs = repo_dir.join("refs");
        let read_ref = |name: &str| {
            fs::read_to_string(refs.join(name))
                .ok()
                .map(|s| s.trim().to_string())
        };
        let pin = read_ref(revision).unwrap_or_else(|| revision.to_string());
        let main = read_ref("main");
        // Known refs still work when directory listing is unavailable.
        let mut paths = vec![root.join(&pin), root.join(revision)];
        if let Some(main) = &main {
            paths.push(root.join(main));
        }
        match fs::read_dir(&root) {
            Ok(entries) => paths.extend(entries.flatten().map(|e| e.path())),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
            Err(e) => warn!("Couldn't list HF snapshots at {:?}: {}", root, e),
        }
        for path in paths.into_iter().filter(|path| path.is_dir()) {
            let Some(commit) = path.file_name().and_then(|name| name.to_str()) else {
                continue;
            };
            let rank = if commit == revision || commit == pin {
                0
            } else if main.as_deref() == Some(commit) {
                1
            } else {
                2
            };
            snapshots.push((rank, cache_index, path));
        }
    }
    snapshots.sort();
    snapshots.dedup();
    snapshots.into_iter().map(|(_, _, path)| path).collect()
}

/// Include dangling pointers so deleting a model cleans up all of its copies.
fn hf_cached_paths_in(
    caches: &[Cache],
    repo_id: &str,
    revision: &str,
    filename: &str,
) -> Vec<PathBuf> {
    hf_snapshot_paths(caches, repo_id, revision)
        .into_iter()
        .map(|snapshot| snapshot.join(filename))
        .filter(|path| path.is_file() || path.is_symlink())
        .collect()
}

/// The `models--org--name` dir a cached file lives in.
fn hf_repo_dir(cached_file: &Path) -> Option<PathBuf> {
    cached_file
        .ancestors()
        .find(|dir| {
            dir.file_name()
                .and_then(|n| n.to_str())
                .is_some_and(|n| n.starts_with("models--"))
        })
        .map(Path::to_path_buf)
}

/// The blob a snapshot pointer owns, if it may be deleted along with it:
/// `None` for plain files (on Windows hf-hub's symlink fallback renames the
/// blob into the snapshot), dangling pointers (copies at other pins can share
/// a blob that's already gone), targets outside the repo's `blobs/`, and blobs
/// another filename still references.
fn unshared_blob(pointer: &Path, deleting: &HashSet<PathBuf>) -> std::io::Result<Option<PathBuf>> {
    let is_symlink = fs::symlink_metadata(pointer)
        .map(|m| m.file_type().is_symlink())
        .unwrap_or(false);
    let Some(repo_dir) = hf_repo_dir(pointer).filter(|_| is_symlink) else {
        return Ok(None);
    };
    let blob = match fs::canonicalize(pointer) {
        Ok(blob) => blob,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(e),
    };
    // Only delete actual HF blobs, not arbitrary symlink targets.
    let blobs = fs::canonicalize(repo_dir.join("blobs"))?;
    if blob.parent() != Some(blobs.as_path())
        || blob_is_shared(&repo_dir.join("snapshots"), &blob, deleting)?
    {
        return Ok(None);
    }
    Ok(Some(blob))
}

/// Preserve blobs referenced by another filename, including files in subfolders.
/// Listing errors are returned rather than guessing that a blob is unshared.
fn blob_is_shared(dir: &Path, blob: &Path, deleting: &HashSet<PathBuf>) -> std::io::Result<bool> {
    for entry in fs::read_dir(dir)? {
        let entry = entry?;
        let path = entry.path();
        if deleting.contains(&path) {
            continue;
        }
        let kind = entry.file_type()?;
        if kind.is_dir() {
            if blob_is_shared(&path, blob, deleting)? {
                return Ok(true);
            }
        } else if kind.is_symlink() {
            match fs::canonicalize(&path) {
                Ok(target) if target == blob => return Ok(true),
                Ok(_) => {}
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
                Err(e) => return Err(e),
            }
        }
    }
    Ok(false)
}

/// `fs::remove_file`, where a file that's already gone counts as nothing
/// removed rather than an error, so deleting stays idempotent.
fn remove_file_if_present(path: &Path) -> std::io::Result<bool> {
    match fs::remove_file(path) {
        Ok(()) => Ok(true),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(false),
        // Name the file: a delete can stop partway through several copies.
        Err(e) => Err(std::io::Error::new(
            e.kind(),
            format!("couldn't remove {}: {}", path.display(), e),
        )),
    }
}

/// Friendly name advertised by GGUF metadata, if present. Empty strings are not
/// useful display names, so callers can keep their filename/repo fallback.
fn probed_display_name(probe: &CapabilityProbe) -> Option<String> {
    probe
        .display_name
        .as_deref()
        .map(str::trim)
        .filter(|name| !name.is_empty())
        .map(str::to_string)
}

/// Capability fields for a locally-discovered on-disk model, derived from its
/// GGUF header probe. Anything without readable GGUF metadata — a legacy `.bin`
/// file, or a header that simply omits a key — collapses to "no advertised
/// capability"; transcribe-cpp still reconciles the real values at load time.
/// Shared by both local discovery paths (custom models dir + HF cache) so they
/// surface capabilities identically.
struct LocalCaps {
    supports_streaming: bool,
    supports_translation: bool,
    supports_language_selection: bool,
    supports_language_detection: bool,
    supported_languages: Vec<String>,
}

fn local_caps(probe: &CapabilityProbe) -> LocalCaps {
    let languages = canonicalize_supported_languages(probe.languages.clone().unwrap_or_default());
    LocalCaps {
        supports_streaming: probe.supports_streaming.unwrap_or(false),
        supports_translation: probe.supports_translation.unwrap_or(false),
        // Only offer a language picker when there's more than one to choose.
        supports_language_selection: languages.len() > 1,
        supports_language_detection: probe.supports_language_detect.unwrap_or(false),
        supported_languages: languages,
    }
}

/// Download id under which a standalone language detector download reports
/// progress, completion and cancellation, like a model's.
pub const LANGUAGE_DETECTOR_ID: &str = "language-detector";

/// Where one file's download progress is reported: under `model_id`, its bytes
/// counted from `offset`, out of `total` (default: `offset` + the file's own
/// size). Lets two files (the language detector, then a model) fill one bar.
#[derive(Clone)]
pub(super) struct ProgressTarget {
    pub model_id: String,
    pub offset: u64,
    pub total: Option<u64>,
}

impl ProgressTarget {
    /// A file reporting on its own.
    fn own(model_id: &str) -> Self {
        Self {
            model_id: model_id.to_string(),
            offset: 0,
            total: None,
        }
    }

    /// The event for `downloaded` of this file's `total` bytes.
    pub(super) fn progress(
        &self,
        downloaded: u64,
        total: u64,
        bytes_per_sec: Option<f64>,
    ) -> DownloadProgress {
        let downloaded = self.offset + downloaded;
        let total = self.total.unwrap_or(self.offset + total).max(downloaded);
        DownloadProgress {
            model_id: self.model_id.clone(),
            downloaded,
            total,
            percentage: if total > 0 {
                downloaded as f64 / total as f64 * 100.0
            } else {
                0.0
            },
            bytes_per_sec,
        }
    }
}

/// One file to fetch from Hugging Face, with mirror fallback.
struct FileTransfer<'a> {
    /// What the logs call it.
    label: &'a str,
    repo_id: &'a str,
    revision: &'a str,
    filename: &'a str,
    mirrors: Vec<crate::catalog::MirrorFile>,
    progress: ProgressTarget,
}

/// Bridges hf-hub's async download progress to Handy's `model-download-progress`
/// event. hf-hub clones the reporter, so shared state lives behind an `Arc`.
#[derive(Clone)]
struct HfDownloadProgress {
    app_handle: AppHandle,
    target: ProgressTarget,
    state: Arc<Mutex<HfProgressState>>,
}

/// `(downloaded, total, bytes_per_sec)` to emit.
type HfProgressSnapshot = (u64, u64, Option<f64>);

struct HfProgressState {
    total: u64,
    downloaded: u64,
    /// `None` until hf-hub reports the resume offset; see [`Self::on_update`].
    rate: Option<RateMeter>,
    last_emit: Instant,
    /// Every callback (even throttled-out ones) bumps this; the stall watchdog
    /// reads it. Starts at construction so a hang before the first byte —
    /// e.g. a wedged metadata/resolve request — also counts as a stall.
    last_activity: Instant,
}

impl HfProgressState {
    fn new(now: Instant) -> Self {
        Self {
            total: 0,
            downloaded: 0,
            rate: None,
            last_emit: now,
            last_activity: now,
        }
    }

    fn on_init(&mut self, size: u64, now: Instant) {
        self.total = size;
        self.downloaded = 0;
        self.rate = None;
        self.last_activity = now;
    }

    fn on_update(&mut self, size: u64, now: Instant) -> Option<HfProgressSnapshot> {
        self.last_activity = now;
        let Some(rate) = self.rate.as_mut() else {
            // hf-hub's first `update(start)` after `init` is the resume offset already
            // on disk, not transfer: use it as the rate baseline and emit it at once
            // so the bar doesn't flash 0%.
            self.downloaded = size;
            self.rate = Some(RateMeter::new(size));
            self.last_emit = now;
            return Some((self.downloaded, self.total, None));
        };
        self.downloaded = self.downloaded.saturating_add(size);
        // Throttle, but always emit the final byte.
        let done = self.total > 0 && self.downloaded >= self.total;
        if !done && now.duration_since(self.last_emit) < PROGRESS_THROTTLE {
            return None;
        }
        self.last_emit = now;
        Some((
            self.downloaded,
            self.total,
            rate.sample(self.downloaded, now),
        ))
    }

    /// Re-emit during a lull so the rate decays instead of freezing.
    fn on_tick(&mut self, now: Instant) -> Option<HfProgressSnapshot> {
        let rate = self.rate.as_mut()?;
        if now.duration_since(self.last_emit) < PROGRESS_TICK {
            return None;
        }
        self.last_emit = now;
        Some((
            self.downloaded,
            self.total,
            rate.sample(self.downloaded, now),
        ))
    }
}

impl HfDownloadProgress {
    fn new(app_handle: AppHandle, target: ProgressTarget) -> Self {
        Self {
            app_handle,
            target,
            state: Arc::new(Mutex::new(HfProgressState::new(Instant::now()))),
        }
    }

    /// Instant of the most recent sign of life from the transfer.
    fn last_activity(&self) -> Instant {
        self.state.lock().unwrap().last_activity
    }

    /// Called periodically by the stall watchdog.
    fn tick(&self) {
        let snapshot = self.state.lock().unwrap().on_tick(Instant::now());
        if let Some(snapshot) = snapshot {
            self.emit(snapshot);
        }
    }

    fn emit(&self, (downloaded, total, bytes_per_sec): HfProgressSnapshot) {
        let _ = self.app_handle.emit(
            "model-download-progress",
            &self.target.progress(downloaded, total, bytes_per_sec),
        );
    }
}

impl Progress for HfDownloadProgress {
    async fn init(&mut self, size: usize, _filename: &str) {
        // No emit: the resume offset follows immediately (see `on_update`).
        self.state
            .lock()
            .unwrap()
            .on_init(size as u64, Instant::now());
    }

    async fn update(&mut self, size: usize) {
        let snapshot = self
            .state
            .lock()
            .unwrap()
            .on_update(size as u64, Instant::now());
        if let Some(snapshot) = snapshot {
            self.emit(snapshot);
        }
    }

    async fn finish(&mut self) {
        let total = {
            let st = self.state.lock().unwrap();
            st.total.max(st.downloaded)
        };
        self.emit((total, total, None));
    }
}

/// RAII guard that clears the `is_rescanning` single-flight flag on drop, so the
/// slot is released on every exit path (including early returns and `?`).
struct RescanGuard {
    flag: Arc<AtomicBool>,
}

impl Drop for RescanGuard {
    fn drop(&mut self) {
        self.flag.store(false, Ordering::SeqCst);
    }
}

/// RAII guard that cleans up download state (`is_downloading` flag and cancel flag)
/// when dropped, unless explicitly disarmed. This ensures consistent cleanup on
/// every error path without requiring manual cleanup at each `?` or `return Err`.
struct DownloadCleanup<'a> {
    available_models: &'a Mutex<HashMap<String, ModelInfo>>,
    cancel_flags: &'a Arc<Mutex<HashMap<String, CancellationToken>>>,
    model_id: String,
    disarmed: bool,
}

impl<'a> Drop for DownloadCleanup<'a> {
    fn drop(&mut self) {
        if self.disarmed {
            return;
        }
        {
            let mut models = self.available_models.lock().unwrap();
            if let Some(model) = models.get_mut(self.model_id.as_str()) {
                model.is_downloading = false;
            }
        }
        self.cancel_flags.lock().unwrap().remove(&self.model_id);
    }
}

/// A retired ONNX model: nothing can load it anymore, but it may still be on
/// disk. The update screen offers its GGUF replacement and then deletes it.
/// This table is the single source of truth for retired models; the frontend
/// only renders what `get_retired_models` reports.
struct RetiredOnnxModel {
    id: &'static str,
    name: &'static str,
    /// Every name the model was stored under in the models dir: a directory,
    /// or for GigaAM before #1088, a single `.onnx` file.
    disk_names: &'static [&'static str],
    size_mb: u64,
    /// Hugging Face repo of the catalog model that replaces it.
    replacement_repo: &'static str,
}

const RETIRED_ONNX_MODELS: &[RetiredOnnxModel] = &[
    RetiredOnnxModel {
        id: "parakeet-tdt-0.6b-v2",
        name: "Parakeet V2",
        disk_names: &["parakeet-tdt-0.6b-v2-int8"],
        size_mb: 451,
        replacement_repo: "handy-computer/parakeet-tdt-0.6b-v2-gguf",
    },
    RetiredOnnxModel {
        id: "parakeet-tdt-0.6b-v3",
        name: "Parakeet V3",
        disk_names: &["parakeet-tdt-0.6b-v3-int8"],
        size_mb: 456,
        replacement_repo: "handy-computer/parakeet-tdt-0.6b-v3-gguf",
    },
    RetiredOnnxModel {
        id: "moonshine-base",
        name: "Moonshine Base",
        disk_names: &["moonshine-base"],
        size_mb: 55,
        replacement_repo: "handy-computer/moonshine-base-gguf",
    },
    RetiredOnnxModel {
        id: "moonshine-tiny-streaming-en",
        name: "Moonshine V2 Tiny",
        disk_names: &["moonshine-tiny-streaming-en"],
        size_mb: 31,
        replacement_repo: "handy-computer/moonshine-streaming-tiny-gguf",
    },
    RetiredOnnxModel {
        id: "moonshine-small-streaming-en",
        name: "Moonshine V2 Small",
        disk_names: &["moonshine-small-streaming-en"],
        size_mb: 99,
        replacement_repo: "handy-computer/moonshine-streaming-small-gguf",
    },
    RetiredOnnxModel {
        id: "moonshine-medium-streaming-en",
        name: "Moonshine V2 Medium",
        disk_names: &["moonshine-medium-streaming-en"],
        size_mb: 192,
        replacement_repo: "handy-computer/moonshine-streaming-medium-gguf",
    },
    RetiredOnnxModel {
        id: "sense-voice-int8",
        name: "SenseVoice",
        disk_names: &["sense-voice-int8"],
        size_mb: 152,
        replacement_repo: "handy-computer/SenseVoiceSmall-gguf",
    },
    RetiredOnnxModel {
        id: "gigaam-v3-e2e-ctc",
        name: "GigaAM v3",
        disk_names: &["giga-am-v3-int8", "giga-am-v3.int8.onnx"],
        size_mb: 151,
        replacement_repo: "handy-computer/gigaam-v3-e2e-ctc-gguf",
    },
    RetiredOnnxModel {
        id: "canary-180m-flash",
        name: "Canary 180M Flash",
        disk_names: &["canary-180m-flash"],
        size_mb: 146,
        replacement_repo: "handy-computer/canary-180m-flash-gguf",
    },
    RetiredOnnxModel {
        id: "canary-1b-v2",
        name: "Canary 1B v2",
        disk_names: &["canary-1b-v2"],
        size_mb: 691,
        replacement_repo: "handy-computer/canary-1b-v2-gguf",
    },
    RetiredOnnxModel {
        id: "cohere-int8",
        name: "Cohere",
        disk_names: &["cohere-int8"],
        size_mb: 1708,
        replacement_repo: "handy-computer/cohere-transcribe-03-2026-gguf",
    },
];

/// A retired ONNX model found on disk.
#[derive(Serialize, Clone, Debug, Type)]
pub struct RetiredModel {
    pub id: String,
    pub name: String,
    pub size_mb: u64,
    pub replacement_repo: String,
}

pub struct ModelManager {
    app_handle: AppHandle,
    models_dir: PathBuf,
    available_models: Mutex<HashMap<String, ModelInfo>>,
    cancel_flags: Arc<Mutex<HashMap<String, CancellationToken>>>,
    /// Single-flight guard for [`Self::rescan_local_models`] so concurrent
    /// refresh requests coalesce instead of scanning the disk in parallel.
    is_rescanning: Arc<AtomicBool>,
    /// One language detector transfer at a time, however many downloads
    /// want it.
    detector_download: tokio::sync::Mutex<()>,
}

impl ModelManager {
    pub fn new(app_handle: &AppHandle) -> Result<Self> {
        // Create models directory in app data
        let models_dir = crate::portable::app_data_dir(app_handle)
            .map_err(|e| anyhow::anyhow!("Failed to get app data dir: {}", e))?
            .join("models");

        if !models_dir.exists() {
            fs::create_dir_all(&models_dir)?;
        }

        let mut available_models = HashMap::new();

        // Whisper supported languages (99 languages from tokenizer)
        let whisper_languages: Vec<String> = vec![
            "en", "zh", "de", "es", "ru", "ko", "fr", "ja", "pt", "tr", "pl", "ca", "nl", "ar",
            "sv", "it", "id", "hi", "fi", "vi", "he", "uk", "el", "ms", "cs", "ro", "da", "hu",
            "ta", "no", "th", "ur", "hr", "bg", "lt", "la", "mi", "ml", "cy", "sk", "te", "fa",
            "lv", "bn", "sr", "az", "sl", "kn", "et", "mk", "br", "eu", "is", "hy", "ne", "mn",
            "bs", "kk", "sq", "sw", "gl", "mr", "pa", "si", "km", "sn", "yo", "so", "af", "oc",
            "ka", "be", "tg", "sd", "gu", "am", "yi", "lo", "uz", "fo", "ht", "ps", "tk", "nn",
            "mt", "sa", "lb", "my", "bo", "tl", "mg", "as", "tt", "haw", "ln", "ha", "ba", "jw",
            "su", "yue",
        ]
        .into_iter()
        .map(String::from)
        .collect();

        available_models.insert(
            "small".to_string(),
            ModelInfo {
                id: "small".to_string(),
                name: "Whisper Small".to_string(),
                description: "Fast and fairly accurate.".to_string(),
                filename: "ggml-small.bin".to_string(),
                source: ModelSource::Url {
                    url: "https://blob.handy.computer/ggml-small.bin".to_string(),
                    sha256: Some(
                        "1be3a9b2063867b937e64e2ec7483364a79917e157fa98c5d94b5c1fffea987b"
                            .to_string(),
                    ),
                },
                size_mb: 465,
                is_downloaded: false,
                is_downloading: false,
                partial_size: 0,
                accuracy_score: 0.60,
                speed_score: 0.85,
                supports_translation: true,
                is_recommended: false,
                supported_languages: whisper_languages.clone(),
                supports_language_selection: true,
                is_custom: false,
                supports_streaming: false,
                supports_language_detection: true,
            },
        );

        // Add downloadable models
        available_models.insert(
            "medium".to_string(),
            ModelInfo {
                id: "medium".to_string(),
                name: "Whisper Medium".to_string(),
                description: "Good accuracy, medium speed".to_string(),
                filename: "whisper-medium-q4_1.bin".to_string(),
                source: ModelSource::Url {
                    url: "https://blob.handy.computer/whisper-medium-q4_1.bin".to_string(),
                    sha256: Some(
                        "79283fc1f9fe12ca3248543fbd54b73292164d8df5a16e095e2bceeaaabddf57"
                            .to_string(),
                    ),
                },
                size_mb: 469,
                is_downloaded: false,
                is_downloading: false,
                partial_size: 0,
                accuracy_score: 0.75,
                speed_score: 0.60,
                supports_translation: true,
                is_recommended: false,
                supported_languages: whisper_languages.clone(),
                supports_language_selection: true,
                is_custom: false,
                supports_streaming: false,
                supports_language_detection: true,
            },
        );

        available_models.insert(
            "turbo".to_string(),
            ModelInfo {
                id: "turbo".to_string(),
                name: "Whisper Turbo".to_string(),
                description: "Balanced accuracy and speed.".to_string(),
                filename: "ggml-large-v3-turbo.bin".to_string(),
                source: ModelSource::Url {
                    url: "https://blob.handy.computer/ggml-large-v3-turbo.bin".to_string(),
                    sha256: Some(
                        "1fc70f774d38eb169993ac391eea357ef47c88757ef72ee5943879b7e8e2bc69"
                            .to_string(),
                    ),
                },
                size_mb: 1549,
                is_downloaded: false,
                is_downloading: false,
                partial_size: 0,
                accuracy_score: 0.80,
                speed_score: 0.40,
                supports_translation: false, // Turbo doesn't support translation
                is_recommended: false,
                supported_languages: whisper_languages.clone(),
                supports_language_selection: true,
                is_custom: false,
                supports_streaming: false,
                supports_language_detection: true,
            },
        );

        available_models.insert(
            "large".to_string(),
            ModelInfo {
                id: "large".to_string(),
                name: "Whisper Large".to_string(),
                description: "Good accuracy, but slow.".to_string(),
                filename: "ggml-large-v3-q5_0.bin".to_string(),
                source: ModelSource::Url {
                    url: "https://blob.handy.computer/ggml-large-v3-q5_0.bin".to_string(),
                    sha256: Some(
                        "d75795ecff3f83b5faa89d1900604ad8c780abd5739fae406de19f23ecd98ad1"
                            .to_string(),
                    ),
                },
                size_mb: 1031,
                is_downloaded: false,
                is_downloading: false,
                partial_size: 0,
                accuracy_score: 0.85,
                speed_score: 0.30,
                supports_translation: true,
                is_recommended: false,
                supported_languages: whisper_languages.clone(),
                supports_language_selection: true,
                is_custom: false,
                supports_streaming: false,
                supports_language_detection: true,
            },
        );

        available_models.insert(
            "breeze-asr".to_string(),
            ModelInfo {
                id: "breeze-asr".to_string(),
                name: "Breeze ASR".to_string(),
                description: "Optimized for Taiwanese Mandarin. Code-switching support."
                    .to_string(),
                filename: "breeze-asr-q5_k.bin".to_string(),
                source: ModelSource::Url {
                    url: "https://blob.handy.computer/breeze-asr-q5_k.bin".to_string(),
                    sha256: Some(
                        "8efbf0ce8a3f50fe332b7617da787fb81354b358c288b008d3bdef8359df64c6"
                            .to_string(),
                    ),
                },
                size_mb: 1030,
                is_downloaded: false,
                is_downloading: false,
                partial_size: 0,
                accuracy_score: 0.85,
                speed_score: 0.35,
                supports_translation: false,
                is_recommended: false,
                supported_languages: whisper_languages,
                supports_language_selection: true,
                is_custom: false,
                supports_streaming: false,
                supports_language_detection: true,
            },
        );

        // Seed the bundled offline catalog before the on-disk scans, so a model
        // already in the HF cache dedups onto its richer catalog entry (the scans
        // only insert ids not already present) instead of showing as a bare cache
        // find. Additive — see `seed_catalog_models`.
        Self::seed_catalog_models(&mut available_models);

        // Auto-discover custom transcribe-cpp models (.bin / .gguf) in the models directory
        if let Err(e) = Self::discover_custom_transcribe_models(&models_dir, &mut available_models)
        {
            warn!("Failed to discover custom models: {}", e);
        }

        // Auto-discover transcribe-cpp GGUF models already in the shared HF cache.
        Self::discover_hf_cache_models(&mut available_models);

        let manager = Self {
            app_handle: app_handle.clone(),
            models_dir,
            available_models: Mutex::new(available_models),
            cancel_flags: Arc::new(Mutex::new(HashMap::new())),
            is_rescanning: Arc::new(AtomicBool::new(false)),
            detector_download: tokio::sync::Mutex::new(()),
        };

        // Migrate any bundled models to user directory
        manager.migrate_bundled_models()?;

        // Check which models are already downloaded
        manager.update_download_status()?;

        // Auto-select a model if none is currently selected
        manager.auto_select_model_if_needed()?;

        Ok(manager)
    }

    pub fn get_available_models(&self) -> Vec<ModelInfo> {
        let mut list: Vec<ModelInfo> = {
            let models = self.available_models.lock().unwrap();
            models.values().cloned().collect()
        };
        // Stable, reasonable order: catalog editorial rank first (lower = higher
        // priority), then any other recommended model, then by accuracy, speed,
        // and name. `ModelInfo` doesn't carry rank, so resolve it by id from the
        // catalog here.
        list.sort_by(|a, b| {
            crate::catalog::rank_of(&a.id)
                .cmp(&crate::catalog::rank_of(&b.id))
                .then((!a.is_recommended).cmp(&(!b.is_recommended)))
                .then(b.accuracy_score.total_cmp(&a.accuracy_score))
                .then(b.speed_score.total_cmp(&a.speed_score))
                .then_with(|| a.name.cmp(&b.name))
        });
        list
    }

    /// Seed every bundled catalog default into the registry (additive).
    /// Alternate quants are discovered from disk instead.
    ///
    /// Catalog (`.gguf`, `HuggingFace`) and legacy (`.bin`/ONNX, `Url`) entries
    /// stay SEPARATE — different files, ids, and runtimes. Nothing is merged or
    /// removed; the UI just hides not-on-disk `Url` entries to deprecate legacy
    /// downloads, while already-downloaded ones stay runnable. Runs before the
    /// on-disk scans so a cached model dedups onto its catalog entry.
    fn seed_catalog_models(available_models: &mut HashMap<String, ModelInfo>) {
        use std::collections::hash_map::Entry;
        let mut added = 0usize;
        for desc in crate::catalog::CATALOG.iter() {
            if let Entry::Vacant(slot) = available_models.entry(desc.id.clone()) {
                slot.insert(desc.to_model_info(&DiskStatus::default()));
                added += 1;
            }
        }
        info!("Seeded {} catalog model(s) into the registry", added);
    }

    /// Claim the single rescan slot. Returns a guard that releases it on drop,
    /// or `None` if a rescan is already running (callers should just skip).
    fn try_start_rescan(&self) -> Option<RescanGuard> {
        if self.is_rescanning.swap(true, Ordering::SeqCst) {
            None
        } else {
            Some(RescanGuard {
                flag: self.is_rescanning.clone(),
            })
        }
    }

    /// Re-run the local discovery scans (custom models dir + shared HF cache) so
    /// models dropped in or downloaded outside Handy show up without a restart.
    /// The merge is additive: only new ids are inserted, so existing entries keep
    /// their values — including runtime-probed capabilities from
    /// [`Self::set_runtime_capabilities`]. It then runs [`Self::update_download_status`],
    /// which recomputes disk-derived flags for *every* entry; a rescan racing an
    /// in-flight download can briefly clear its `is_downloading`, but the download
    /// continues and the event-driven UI self-corrects.
    ///
    /// The disk walk and 64 KiB header probes run against a cloned snapshot
    /// *off-lock* so readers never block on I/O; only the brief merge takes the
    /// registry lock. Concurrent calls coalesce via [`Self::try_start_rescan`].
    pub fn rescan_local_models(&self) -> Result<()> {
        let _guard = match self.try_start_rescan() {
            Some(g) => g,
            None => {
                debug!("Model rescan already in progress; skipping");
                return Ok(());
            }
        };

        // Snapshot the current registry and discover against the copy off-lock.
        // The discover_* helpers are purely additive (they skip ids already in
        // the map), so the snapshot ends up as {current} ∪ {newly-found}.
        let mut snapshot = self.available_models.lock().unwrap().clone();
        if let Err(e) = Self::discover_custom_transcribe_models(&self.models_dir, &mut snapshot) {
            warn!("Rescan: failed to discover custom models: {}", e);
        }
        Self::discover_hf_cache_models(&mut snapshot);

        // Merge only the genuinely-new ids back into the live registry. `or_insert`
        // leaves every existing entry exactly as it was.
        let mut added = 0usize;
        {
            let mut live = self.available_models.lock().unwrap();
            for (id, info) in snapshot {
                if let std::collections::hash_map::Entry::Vacant(entry) = live.entry(id) {
                    entry.insert(info);
                    added += 1;
                }
            }
        }

        self.update_download_status()?;
        self.auto_select_model_if_needed()?;
        if added > 0 {
            info!("Model rescan discovered {} new model(s)", added);
        }
        let _ = self.app_handle.emit("models-updated", ());
        Ok(())
    }

    pub fn get_model_info(&self, model_id: &str) -> Option<ModelInfo> {
        let models = self.available_models.lock().unwrap();
        models.get(model_id).cloned()
    }

    /// Reconcile a model's advertised capabilities with the ground truth from the
    /// loaded model (transcribe-cpp's GGUF-derived capabilities), overwriting the
    /// pre-download view (catalog metadata or a header probe — see
    /// [`super::model_capabilities`]).
    ///
    /// This corrects the header probe's gaps. It matters most for **streaming**
    /// (transcribe-cpp infers it at load for parakeet/streaming families, where
    /// the flat GGUF key can be absent, and it gates whether streaming is even
    /// attempted — see `actions.rs`) and for **language detection** / the
    /// **supported-language set**, which feed [`effective_language`]; a mislabeled
    /// header would otherwise coerce an "auto" intent to a forced language for good.
    /// Translate is reconciled too for badge accuracy, though run paths re-read it
    /// live regardless.
    pub fn set_runtime_capabilities(
        &self,
        model_id: &str,
        supports_streaming: bool,
        supports_translation: bool,
        supports_language_detection: bool,
        supported_languages: Vec<String>,
    ) {
        let supported_languages = canonicalize_supported_languages(supported_languages);
        let mut models = self.available_models.lock().unwrap();
        if let Some(model) = models.get_mut(model_id) {
            model.supports_streaming = supports_streaming;
            model.supports_translation = supports_translation;
            model.supports_language_detection = supports_language_detection;
            // An empty set means the model is language-agnostic — but it is also
            // what a failed capability read leaves behind, so keep the probed /
            // catalog list rather than blanking a known one to nothing.
            if !supported_languages.is_empty() {
                model.supports_language_selection = supported_languages.len() > 1;
                model.supported_languages = supported_languages;
            }
        }
    }

    fn migrate_bundled_models(&self) -> Result<()> {
        // Check for bundled models and copy them to user directory
        let bundled_models = ["ggml-small.bin"]; // Add other bundled models here if any

        for filename in &bundled_models {
            let bundled_path = self.app_handle.path().resolve(
                format!("resources/models/{}", filename),
                tauri::path::BaseDirectory::Resource,
            );

            if let Ok(bundled_path) = bundled_path {
                if bundled_path.exists() {
                    let user_path = self.models_dir.join(filename);

                    // Only copy if user doesn't already have the model
                    if !user_path.exists() {
                        info!("Migrating bundled model {} to user directory", filename);
                        fs::copy(&bundled_path, &user_path)?;
                        info!("Successfully migrated {}", filename);
                    }
                }
            }
        }

        Ok(())
    }

    fn is_retired_on_disk(&self, model: &RetiredOnnxModel) -> bool {
        model
            .disk_names
            .iter()
            .any(|name| self.models_dir.join(name).exists())
    }

    /// Retired ONNX models still on disk, in any layout they were stored in.
    pub fn get_retired_models(&self) -> Vec<RetiredModel> {
        RETIRED_ONNX_MODELS
            .iter()
            .filter(|model| self.is_retired_on_disk(model))
            .map(|model| RetiredModel {
                id: model.id.to_string(),
                name: model.name.to_string(),
                size_mb: model.size_mb,
                replacement_repo: model.replacement_repo.to_string(),
            })
            .collect()
    }

    /// Delete everything a retired ONNX model left on disk, in any layout,
    /// including interrupted downloads (`.partial`) and extractions
    /// (`.extracting`).
    pub fn delete_retired_model(&self, model_id: &str) -> Result<()> {
        let model = RETIRED_ONNX_MODELS
            .iter()
            .find(|model| model.id == model_id)
            .ok_or_else(|| anyhow::anyhow!("Not a retired model: {}", model_id))?;
        for name in model.disk_names {
            for suffix in ["", ".partial", ".extracting"] {
                let path = self.models_dir.join(format!("{name}{suffix}"));
                if path.is_dir() {
                    fs::remove_dir_all(&path)?;
                } else if path.exists() {
                    fs::remove_file(&path)?;
                } else {
                    continue;
                }
                info!("Deleted retired model files at {:?}", path);
            }
        }
        Ok(())
    }

    fn update_download_status(&self) -> Result<()> {
        // Snapshot in-flight download ids before taking the registry lock (the
        // two locks are never nested) so a mid-download entry is never dropped.
        let downloading_ids: HashSet<String> =
            self.cancel_flags.lock().unwrap().keys().cloned().collect();
        let mut models = self.available_models.lock().unwrap();
        let mut vanished_models: Vec<String> = Vec::new();

        for model in models.values_mut() {
            if let ModelSource::HuggingFace { repo_id, revision } = &model.source {
                // A models-dir copy counts too: mirror-fallback downloads land
                // there, and it makes manual drop-ins of catalog files work.
                let local_path = self.models_dir.join(&model.filename);
                let partial_path = self.models_dir.join(format!("{}.partial", &model.filename));
                model.is_downloaded = hf_cached_path(repo_id, revision, &model.filename).is_some()
                    || local_path.exists();
                model.is_downloading = false;
                model.partial_size = partial_path.metadata().map(|m| m.len()).unwrap_or(0);
                // Alternate-quant entries exist only because their file was
                // discovered on disk — the catalog offers just the default
                // quant, so they are never presented for download. When the
                // file is gone, the entry goes with it.
                if !model.is_downloaded
                    && !downloading_ids.contains(&model.id)
                    && Self::disappears_when_missing(model)
                {
                    vanished_models.push(model.id.clone());
                }
                continue;
            }
            let model_path = self.models_dir.join(&model.filename);
            let partial_path = self.models_dir.join(format!("{}.partial", &model.filename));

            model.is_downloaded = model_path.exists();
            model.is_downloading = false;

            // Get partial file size if it exists
            if partial_path.exists() {
                model.partial_size = partial_path.metadata().map(|m| m.len()).unwrap_or(0);
            } else {
                model.partial_size = 0;
            }

            // Custom entries are discovered from files and have no download
            // source. Once their file is gone, keeping the entry would offer a
            // Download action that can never succeed.
            if !model.is_downloaded
                && !downloading_ids.contains(&model.id)
                && Self::disappears_when_missing(model)
            {
                vanished_models.push(model.id.clone());
            }
        }

        for id in vanished_models {
            models.remove(&id);
        }

        Ok(())
    }

    /// Whether `filename` is a catalog-listed quant of `repo_id` other than
    /// the default — the only quant the catalog seeds and offers for download.
    fn is_catalog_alternate_quant(repo_id: &str, filename: &str) -> bool {
        crate::catalog::file_in_catalog(filename, Some(repo_id)).is_some_and(|(desc, file)| {
            desc.default_file()
                .is_some_and(|d| d.filename != file.filename)
        })
    }

    /// Entries discovered exclusively from disk should disappear with their
    /// files. Catalog defaults remain so the UI can offer them for download.
    fn disappears_when_missing(model: &ModelInfo) -> bool {
        model.is_custom
            || match &model.source {
                ModelSource::HuggingFace { repo_id, .. } => {
                    Self::is_catalog_alternate_quant(repo_id, &model.filename)
                }
                _ => false,
            }
    }

    fn selected_model_is_available(models: &HashMap<String, ModelInfo>, model_id: &str) -> bool {
        models
            .get(model_id)
            .is_some_and(|model| model.is_downloaded)
    }

    /// Remove a filename's snapshot pointers and unshared blobs from the HF
    /// cache. Everything else in the repo (other quants, refs) is left
    /// untouched. Returns whether anything was removed, or the error that kept
    /// the model's file on disk.
    fn delete_hf_cache_file(
        repo_id: &str,
        revision: &str,
        filename: &str,
    ) -> std::io::Result<bool> {
        Self::delete_hf_cache_file_in(&hf_caches(), repo_id, revision, filename)
    }

    /// Remove every cached copy of this filename and its unshared blobs.
    /// Leave the repo's other files and empty directories alone.
    fn delete_hf_cache_file_in(
        caches: &[Cache],
        repo_id: &str,
        revision: &str,
        filename: &str,
    ) -> std::io::Result<bool> {
        let pointers = hf_cached_paths_in(caches, repo_id, revision, filename);
        let deleting: HashSet<PathBuf> = pointers.iter().cloned().collect();

        let mut deleted = false;
        for pointer in pointers {
            // The blob goes first: if it can't be removed, the pointer still
            // marks the model as downloaded, which stays true.
            match unshared_blob(&pointer, &deleting) {
                Ok(Some(blob)) => {
                    info!("Deleting HF cache blob at: {:?}", blob);
                    deleted |= remove_file_if_present(&blob)?;
                }
                Ok(None) => {}
                // Can't tell which blob it is or whether it's shared (e.g.
                // canonicalize is unsupported on some Windows volumes): keep
                // the blob rather than fail the delete or guess. At worst
                // its space stays used.
                Err(e) => warn!("Keeping HF cache blob for {:?}: {}", pointer, e),
            }
            info!("Deleting HF cache file at: {:?}", pointer);
            deleted |= remove_file_if_present(&pointer)?;
        }

        Ok(deleted)
    }

    fn auto_select_model_if_needed(&self) -> Result<()> {
        let mut settings = get_settings(&self.app_handle);

        // A model cannot remain selected after its files disappear. Catalog
        // entries stay in the registry so they can be downloaded again, so
        // checking only whether the id exists is not sufficient.
        if !settings.selected_model.is_empty() {
            let is_available = {
                let models = self.available_models.lock().unwrap();
                Self::selected_model_is_available(&models, &settings.selected_model)
            };

            // A retired model on disk stays selected so the frontend can
            // offer its replacement. It can't load: it isn't in the registry.
            let is_retired = RETIRED_ONNX_MODELS
                .iter()
                .any(|model| model.id == settings.selected_model && self.is_retired_on_disk(model));

            if !is_available && !is_retired {
                info!(
                    "Selected model '{}' is not available on disk; clearing selection",
                    settings.selected_model
                );
                settings.selected_model = String::new();
                write_settings(&self.app_handle, settings.clone());
            }
        }

        // If onboarding is still pending, do not auto-select just because a
        // compatible model exists on disk or in the shared HF cache. The
        // onboarding model step should present that choice explicitly.
        if !settings.onboarding_completed {
            debug!("Skipping model auto-selection until onboarding is complete");
            return Ok(());
        }

        // If no model is selected, pick the first downloaded one using the same
        // ranked order the UI receives.
        if settings.selected_model.is_empty() {
            if let Some(available_model) = self
                .get_available_models()
                .into_iter()
                .find(|model| model.is_downloaded)
            {
                info!(
                    "Auto-selecting model: {} ({})",
                    available_model.id, available_model.name
                );

                // Update settings with the selected model
                let mut updated_settings = settings;
                updated_settings.selected_model = available_model.id.clone();
                write_settings(&self.app_handle, updated_settings);

                info!("Successfully auto-selected model: {}", available_model.id);
            }
        }

        Ok(())
    }

    /// Discover custom Whisper-family models in the models directory: legacy
    /// GGML `.bin` files and `.gguf` files (both load through transcribe-cpp).
    /// Skips files that match predefined model filenames.
    fn discover_custom_transcribe_models(
        models_dir: &Path,
        available_models: &mut HashMap<String, ModelInfo>,
    ) -> Result<()> {
        if !models_dir.exists() {
            return Ok(());
        }

        // Collect filenames of predefined models to skip
        let predefined_filenames: HashSet<String> = available_models
            .values()
            .map(|m| m.filename.clone())
            .collect();

        // Scan models directory for .bin / .gguf files
        for entry in fs::read_dir(models_dir)? {
            let entry = match entry {
                Ok(e) => e,
                Err(e) => {
                    warn!("Failed to read directory entry: {}", e);
                    continue;
                }
            };

            let path = entry.path();

            // Skip directories; the .bin / .gguf extension filter is below.
            if !path.is_file() {
                continue;
            }

            let filename = match path.file_name().and_then(|s| s.to_str()) {
                Some(name) => name.to_string(),
                None => continue,
            };

            // Skip hidden files
            if filename.starts_with('.') {
                continue;
            }

            // Only process Whisper-family model files: legacy GGML `.bin` or
            // GGUF `.gguf` (both load through transcribe-cpp). Anything else —
            // including `.partial` downloads like "model.bin.partial" — is
            // skipped, since it ends in neither extension. The model ID is the
            // filename with its extension removed.
            let (model_id, is_gguf) = if let Some(stem) = filename.strip_suffix(".bin") {
                (stem.to_string(), false)
            } else if let Some(stem) = filename.strip_suffix(".gguf") {
                (stem.to_string(), true)
            } else {
                continue;
            };

            // Skip predefined model files, and the language detector (a mirror
            // download lands here), which isn't a transcription model.
            if predefined_filenames.contains(&filename)
                || crate::catalog::LANGUAGE_DETECTOR
                    .as_ref()
                    .is_some_and(|detector| detector.filename == filename)
            {
                continue;
            }

            // A file matching ANY catalog-listed quant surfaces as that catalog
            // model — full name/description/scores, quant-suffixed name for
            // non-defaults — instead of as an anonymous custom entry. (Default
            // quants never reach here: they're in `predefined_filenames`.)
            if let Some((desc, quant_file)) = crate::catalog::file_in_catalog(&filename, None) {
                let info = desc.to_model_info_for_file(
                    quant_file,
                    &DiskStatus {
                        is_downloaded: true,
                        ..Default::default()
                    },
                );
                if !available_models.contains_key(&info.id) {
                    info!(
                        "Discovered catalog quant in models dir: {} ({})",
                        info.id, filename
                    );
                    available_models.insert(info.id.clone(), info);
                }
                continue;
            }

            // Skip if model ID already exists (shouldn't happen, but be safe)
            if available_models.contains_key(&model_id) {
                continue;
            }

            // Generate display name: replace - and _ with space, capitalize words
            let fallback_display_name = model_id
                .replace(['-', '_'], " ")
                .split_whitespace()
                .map(|word| {
                    let mut chars = word.chars();
                    match chars.next() {
                        None => String::new(),
                        Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
                    }
                })
                .collect::<Vec<_>>()
                .join(" ");

            // Get file size in MB
            let size_mb = match path.metadata() {
                Ok(meta) => meta.len() / (1024 * 1024),
                Err(e) => {
                    warn!("Failed to get metadata for {}: {}", filename, e);
                    0
                }
            };

            // Probe GGUF headers for advertised capabilities so a dropped-in
            // model surfaces streaming / translation / languages just like a
            // Handy-downloaded one. Legacy `.bin` files have no GGUF header, so
            // they stay "unknown" until transcribe-cpp reconciles them at load.
            let probe = if is_gguf {
                GgufHeaderProber.probe_file(&path)
            } else {
                CapabilityProbe::default()
            };
            let caps = local_caps(&probe);
            let display_name = probed_display_name(&probe).unwrap_or(fallback_display_name);

            info!(
                "Discovered custom transcribe-cpp model: {} ({}, {} MB, streaming={})",
                model_id, filename, size_mb, caps.supports_streaming
            );

            available_models.insert(
                model_id.clone(),
                ModelInfo {
                    id: model_id,
                    name: display_name,
                    description: "Not officially supported".to_string(),
                    filename,
                    source: ModelSource::Local, // already on disk; nothing to download
                    size_mb,
                    is_downloaded: true, // Already present on disk
                    is_downloading: false,
                    partial_size: 0,
                    accuracy_score: 0.0, // Sentinel: UI hides score bars when both are 0
                    speed_score: 0.0,
                    supports_translation: caps.supports_translation,
                    is_recommended: false,
                    supported_languages: caps.supported_languages,
                    supports_language_selection: caps.supports_language_selection,
                    is_custom: true,
                    supports_streaming: caps.supports_streaming,
                    supports_language_detection: caps.supports_language_detection,
                },
            );
        }

        Ok(())
    }

    /// Discover transcribe-cpp-compatible GGUF models already present in the
    /// shared Hugging Face cache, so models downloaded by Handy (or any other
    /// tool) appear in "Your Models" without re-downloading. Only architectures
    /// transcribe-cpp recognises are surfaced; arbitrary (e.g. LLM) GGUFs that
    /// share the cache are ignored.
    fn discover_hf_cache_models(available_models: &mut HashMap<String, ModelInfo>) {
        for cache in hf_caches() {
            Self::discover_hf_cache_models_in(cache.path(), available_models);
        }
    }

    /// Scan a Hugging Face cache root (`<cache>/models--*`) for GGUF snapshots.
    /// Split from [`Self::discover_hf_cache_models`] so it can be tested against
    /// a synthetic cache directory.
    fn discover_hf_cache_models_in(
        cache_root: &Path,
        available_models: &mut HashMap<String, ModelInfo>,
    ) {
        if !cache_root.is_dir() {
            return;
        }

        // Repo+file pairs already represented (e.g. recommended/added models) so
        // the same file is not listed twice.
        let known_hf: HashSet<(String, String)> = available_models
            .values()
            .filter_map(|m| match &m.source {
                ModelSource::HuggingFace { repo_id, .. } => {
                    Some((repo_id.clone(), m.filename.clone()))
                }
                _ => None,
            })
            .collect();

        let prober = GgufHeaderProber;

        let entries = match fs::read_dir(cache_root) {
            Ok(entries) => entries,
            Err(_) => return,
        };

        for entry in entries.flatten() {
            let folder = entry.file_name();
            let folder = folder.to_string_lossy();
            let Some(rest) = folder.strip_prefix("models--") else {
                continue;
            };
            // Reverse hf-hub's `org/name` -> `models--org--name` folder naming.
            let repo_id = rest.replace("--", "/");

            let caches = [Cache::new(cache_root.to_path_buf())];
            for snapshot in hf_snapshot_paths(&caches, &repo_id, "main") {
                let Some(revision) = snapshot.file_name().and_then(|name| name.to_str()) else {
                    continue;
                };
                let Ok(files) = fs::read_dir(&snapshot) else {
                    continue;
                };

                for file in files.flatten() {
                    let fname = file.file_name().to_string_lossy().to_string();
                    if !fname.ends_with(".gguf") || !file.path().is_file() {
                        continue;
                    }
                    if known_hf.contains(&(repo_id.clone(), fname.clone())) {
                        continue;
                    }
                    let model_id = format!("{}/{}", repo_id, fname);
                    if available_models.contains_key(&model_id) {
                        continue;
                    }

                    // Catalog-listed quants (same repo) surface with full catalog
                    // metadata — quant-suffixed name for non-defaults — and skip
                    // the header probe (the catalog is authoritative for its own
                    // models). Everything else keeps the generic probed path.
                    if let Some((desc, quant_file)) =
                        crate::catalog::file_in_catalog(&fname, Some(&repo_id))
                    {
                        let info = desc.to_model_info_for_file(
                            quant_file,
                            &DiskStatus {
                                is_downloaded: true,
                                ..Default::default()
                            },
                        );
                        info!(
                            "Discovered catalog quant in HF cache: {} ({})",
                            info.id, repo_id
                        );
                        available_models.insert(info.id.clone(), info);
                        continue;
                    }

                    let path = snapshot.join(&fname);
                    let probe = prober.probe_file(&path);
                    // Only surface models transcribe-cpp recognises.
                    if probe.verdict != Compatibility::Compatible {
                        continue;
                    }
                    let caps = local_caps(&probe);

                    let size_mb = path
                        .metadata()
                        .map(|m| m.len() / (1024 * 1024))
                        .unwrap_or(0);
                    let display = probed_display_name(&probe)
                        .unwrap_or_else(|| fname.trim_end_matches(".gguf").to_string());

                    info!("Discovered HF cache model: {} ({})", model_id, repo_id);
                    available_models.insert(
                        model_id.clone(),
                        ModelInfo {
                            id: model_id,
                            name: display,
                            description: format!("From Hugging Face cache: {}", repo_id),
                            filename: fname,
                            source: ModelSource::HuggingFace {
                                repo_id: repo_id.clone(),
                                revision: revision.to_string(),
                            },
                            size_mb,
                            is_downloaded: true,
                            is_downloading: false,
                            partial_size: 0,
                            accuracy_score: 0.0,
                            speed_score: 0.0,
                            supports_translation: caps.supports_translation,
                            is_recommended: false,
                            supported_languages: caps.supported_languages,
                            supports_language_selection: caps.supports_language_selection,
                            is_custom: false,
                            supports_streaming: caps.supports_streaming,
                            supports_language_detection: caps.supports_language_detection,
                        },
                    );
                }
            }
        }
    }

    /// Download a Hugging Face-sourced model into the shared HF cache via
    /// hf-hub, reporting progress through the same `model-download-progress`
    /// event the URL path uses. Uses hf-hub's stock cache, but deliberately
    /// disables authentication because every catalog repository is public.
    /// A model that needs the language detector gets it first, in one bar.
    async fn download_hf_model(
        &self,
        model_info: &ModelInfo,
        repo_id: String,
        revision: String,
    ) -> Result<()> {
        let model_id = model_info.id.clone();
        let filename = model_info.filename.clone();

        // Already in the shared cache (possibly from another tool), or dropped
        // into the models dir (mirror fallback / manual install)?
        let model_present = hf_cached_path(&repo_id, &revision, &filename).is_some()
            || self.models_dir.join(&filename).exists();
        let detector = self.missing_detector_for(model_info);
        if model_present && detector.is_none() {
            self.update_download_status()?;
            let _ = self.app_handle.emit("model-download-complete", &model_id);
            return Ok(());
        }

        // Mark downloading; the guard resets the flag on any error path.
        {
            let mut models = self.available_models.lock().unwrap();
            if let Some(model) = models.get_mut(&model_id) {
                model.is_downloading = true;
            }
        }

        // Register a cancellation token so `cancel_download` can abort this
        // transfer promptly. The guard removes it on every exit path.
        let cancel_token = CancellationToken::new();
        {
            let mut flags = self.cancel_flags.lock().unwrap();
            flags.insert(model_id.clone(), cancel_token.clone());
        }

        let mut cleanup = DownloadCleanup {
            available_models: &self.available_models,
            cancel_flags: &self.cancel_flags,
            model_id: model_id.clone(),
            disarmed: false,
        };

        // The detector, then the model, as one bar: the detector's bytes come
        // first, out of both files' total.
        let mut offset = 0;
        if let Some(detector) = detector {
            let model_bytes = if model_present {
                0
            } else {
                crate::catalog::file_in_catalog(&filename, Some(&repo_id))
                    .map(|(_, file)| file.size_bytes)
                    .unwrap_or(model_info.size_mb * 1024 * 1024)
            };
            let progress = ProgressTarget {
                model_id: model_id.clone(),
                offset: 0,
                total: Some(detector.size_bytes + model_bytes),
            };
            match self.fetch_language_detector(progress, &cancel_token).await {
                Ok(true) => offset = detector.size_bytes,
                Ok(false) => {
                    info!("HF download cancelled for: {}", model_id);
                    return Ok(());
                }
                // The model works without it: Auto falls back to the first
                // preferred language and the language picker offers the
                // download, so it doesn't cost them the model.
                Err(e) => warn!(
                    "Language detector download failed; continuing with {}: {:#}",
                    model_id, e
                ),
            }
        }

        if !model_present {
            let transfer = FileTransfer {
                label: &model_id,
                repo_id: &repo_id,
                revision: &revision,
                filename: &filename,
                mirrors: crate::catalog::mirror_fallbacks(&model_id),
                progress: ProgressTarget {
                    model_id: model_id.clone(),
                    offset,
                    total: None,
                },
            };
            if !self.fetch_hf_file(&transfer, &cancel_token).await? {
                return Ok(());
            }
        }

        cleanup.disarmed = true;
        self.update_download_status()?;
        self.cancel_flags.lock().unwrap().remove(&model_id);
        let _ = self.app_handle.emit("model-download-complete", &model_id);
        info!("HF model {} downloaded", model_id);
        Ok(())
    }

    /// The language detector, when `model` needs it for Auto and it isn't on
    /// disk.
    fn missing_detector_for(
        &self,
        model: &ModelInfo,
    ) -> Option<&'static crate::catalog::LanguageDetectorFile> {
        let languages = crate::language_detection::policy::ModelLanguages {
            languages: &model.supported_languages,
            detects: model.supports_language_detection,
            streaming: model.supports_streaming,
        };
        if !crate::language_detection::policy::requires_language_detector(&languages)
            || self.language_detector_path().is_some()
        {
            return None;
        }
        crate::catalog::LANGUAGE_DETECTOR.as_ref()
    }

    /// Download the language detector on its own, tracked and cancelled under
    /// [`LANGUAGE_DETECTOR_ID`] like a model.
    pub async fn download_language_detector(&self) -> Result<()> {
        let cancel_token = CancellationToken::new();
        self.cancel_flags
            .lock()
            .unwrap()
            .insert(LANGUAGE_DETECTOR_ID.to_string(), cancel_token.clone());
        let fetched = self
            .fetch_language_detector(ProgressTarget::own(LANGUAGE_DETECTOR_ID), &cancel_token)
            .await;
        self.cancel_flags
            .lock()
            .unwrap()
            .remove(LANGUAGE_DETECTOR_ID);
        if fetched? {
            let _ = self
                .app_handle
                .emit("model-download-complete", LANGUAGE_DETECTOR_ID);
        }
        Ok(())
    }

    /// Fetch the language detector unless it's on disk. One transfer at a
    /// time: a second caller waits, then finds the file there. `Ok(false)` if
    /// cancelled.
    async fn fetch_language_detector(
        &self,
        progress: ProgressTarget,
        cancel_token: &CancellationToken,
    ) -> Result<bool> {
        let detector = crate::catalog::LANGUAGE_DETECTOR
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("The catalog names no language detector"))?;
        let _single = tokio::select! {
            guard = self.detector_download.lock() => guard,
            _ = cancel_token.cancelled() => return Ok(false),
        };
        if self.language_detector_path().is_some() {
            return Ok(true);
        }
        let transfer = FileTransfer {
            label: "the language detector",
            repo_id: &detector.repo_id,
            revision: &detector.revision,
            filename: &detector.filename,
            mirrors: crate::catalog::language_detector_mirrors(),
            progress,
        };
        self.fetch_hf_file(&transfer, cancel_token).await
    }

    /// Fetch one file from Hugging Face into the shared cache, retrying, then
    /// falling back to the mirrors into the models dir. `Ok(false)` if
    /// cancelled (partial kept for resume).
    async fn fetch_hf_file(
        &self,
        transfer: &FileTransfer<'_>,
        cancel_token: &CancellationToken,
    ) -> Result<bool> {
        let model_id = transfer.label;
        let repo_id = transfer.repo_id.to_string();
        let revision = transfer.revision.to_string();
        let filename = transfer.filename;
        let cancel_token = cancel_token.clone();

        info!(
            "Downloading {} from {}@{} ({})",
            model_id, repo_id, revision, filename
        );

        // hf-hub has no working internal retry (its retry knobs are hardcoded
        // to zero), so a single transient fault — dropped connection, a 429
        // from the resolve endpoint, a CDN blip — would otherwise fail the
        // whole download. Each attempt resumes from the `.sync.part`
        // committed-offset marker, so a retry only re-fetches what the failed
        // attempt hadn't finished.
        // Start moderately parallel for normal-network throughput, then stay
        // sequential after the first failure. Eight simultaneous connections
        // were all reset on an affected network in #1579, while one stream
        // succeeded; four is a less aggressive fast path, and every retry uses
        // the known-compatible request pattern.
        const ATTEMPT_STREAMS: [usize; 4] = [4, 1, 1, 1];
        let mut attempt: usize = 1;
        let hf_error = loop {
            let stream_count = ATTEMPT_STREAMS[attempt - 1];
            info!(
                "HF download attempt {}/{} for {} using {} concurrent stream(s)",
                attempt,
                ATTEMPT_STREAMS.len(),
                model_id,
                stream_count
            );

            // Fresh client per attempt so a wedged connection from the previous
            // try can't poison the retry.
            let api = ApiBuilder::from_env()
                // Ignore cached and environment-provided credentials. A stale token
                // can make otherwise-public downloads fail authentication.
                .with_token(None)
                .with_progress(false)
                .with_max_files(stream_count)
                .build()
                .map_err(|e| anyhow::anyhow!("Failed to init Hugging Face API: {}", e))?;
            let repo = api.repo(Repo::with_revision(
                repo_id.clone(),
                RepoType::Model,
                revision.clone(),
            ));
            let progress =
                HfDownloadProgress::new(self.app_handle.clone(), transfer.progress.clone());

            // hf-hub has no internal timeouts, so a wedged connection would
            // otherwise hang this attempt forever and neither the retry loop
            // nor the mirror fallback would ever fire. The watchdog cancels a
            // per-attempt child token when progress goes stale; a user cancel
            // on the parent propagates through the same child. Each wake also
            // re-emits progress, so the reported rate decays through a lull.
            let attempt_token = cancel_token.child_token();
            let watchdog = tokio::spawn({
                let probe = progress.clone();
                let attempt_token = attempt_token.clone();
                async move {
                    loop {
                        tokio::time::sleep(PROGRESS_TICK).await;
                        if attempt_token.is_cancelled() {
                            break;
                        }
                        probe.tick();
                        if probe.last_activity().elapsed() > DOWNLOAD_STALL_TIMEOUT {
                            attempt_token.cancel();
                            break;
                        }
                    }
                }
            });
            // hf-hub only observes its token inside the chunk loop — the
            // metadata/resolve request and cache lock run before it, so a hang
            // there would ignore the cancel entirely. Race the whole future
            // against the token: on cancel, grant a short grace so an attempt
            // that IS in the chunk loop can unwind gracefully (committing the
            // `.sync.part` resume offset), then drop the future outright,
            // which aborts whatever request it was wedged in.
            let mut download = std::pin::pin!(repo.download_with_progress_cancellable(
                filename,
                progress,
                attempt_token.clone()
            ));
            let result = tokio::select! {
                r = &mut download => r,
                _ = attempt_token.cancelled() => {
                    match tokio::time::timeout(Duration::from_secs(5), &mut download).await {
                        Ok(r) => r,
                        Err(_) => Err(hf_hub::api::tokio::ApiError::Cancelled),
                    }
                }
            };
            watchdog.abort();

            match result {
                Ok(_) => break None,
                Err(hf_hub::api::tokio::ApiError::Cancelled) if cancel_token.is_cancelled() => {
                    // User cancelled. hf-hub leaves the partially downloaded
                    // `.sync.part` in the shared cache, so a later attempt resumes
                    // instead of restarting. The guard resets is_downloading and
                    // drops the token; `cancel_download` already emitted
                    // `model-download-cancelled`.
                    info!("HF download cancelled for: {}", model_id);
                    return Ok(false);
                }
                Err(hf_hub::api::tokio::ApiError::Cancelled) => {
                    let err = anyhow::anyhow!(
                        "transfer stalled: no progress for {}s",
                        DOWNLOAD_STALL_TIMEOUT.as_secs()
                    );
                    // A parallel attempt may be what wedged the network. Give
                    // the connection pool a brief pause, then retry once using
                    // the known-compatible single-stream path. A sequential
                    // stall already cost DOWNLOAD_STALL_TIMEOUT, so further
                    // retries would likely just repeat it — use the mirror.
                    if stream_count == 1 || attempt >= ATTEMPT_STREAMS.len() {
                        break Some(err);
                    }
                    let delay = Duration::from_secs(1_u64 << attempt);
                    warn!(
                        "HF download attempt {}/{} stalled for {} using {} concurrent stream(s); retrying with {} stream(s) in {}s",
                        attempt,
                        ATTEMPT_STREAMS.len(),
                        model_id,
                        stream_count,
                        ATTEMPT_STREAMS[attempt],
                        delay.as_secs()
                    );
                    tokio::select! {
                        _ = tokio::time::sleep(delay) => {}
                        _ = cancel_token.cancelled() => {
                            info!("HF download cancelled for: {}", model_id);
                            return Ok(false);
                        }
                    }
                    attempt += 1;
                }
                Err(e) => {
                    // {:?} keeps the error source chain (reset vs TLS vs timeout);
                    // Display truncates it to "error sending request".
                    let err = anyhow::anyhow!("{:?}", e);
                    if attempt >= ATTEMPT_STREAMS.len() {
                        break Some(err);
                    }
                    let delay = Duration::from_secs(1_u64 << attempt);
                    warn!(
                        "HF download attempt {}/{} failed for {} using {} concurrent stream(s): {}; retrying with {} stream(s) in {}s",
                        attempt,
                        ATTEMPT_STREAMS.len(),
                        model_id,
                        stream_count,
                        err,
                        ATTEMPT_STREAMS[attempt],
                        delay.as_secs()
                    );
                    tokio::select! {
                        _ = tokio::time::sleep(delay) => {}
                        _ = cancel_token.cancelled() => {
                            info!("HF download cancelled for: {}", model_id);
                            return Ok(false);
                        }
                    }
                    attempt += 1;
                }
            }
        };

        if let Some(hf_error) = hf_error {
            // `attempt`, not the schedule length: a sequential stall breaks out early.
            error!(
                "HF download failed for {} after {} attempt(s): {:?}",
                model_id, attempt, hf_error
            );
            let mirrors = &transfer.mirrors;
            if mirrors.is_empty() {
                return Err(anyhow::anyhow!(
                    "Hugging Face download failed after {} attempt(s): {}",
                    attempt,
                    hf_error
                ));
            }
            let mut completed = false;
            for mirror in mirrors {
                info!("Falling back to mirror for {}: {}", model_id, mirror.url);
                match self
                    .download_from_mirror(
                        &transfer.progress,
                        filename,
                        mirror,
                        cancel_token.clone(),
                    )
                    .await
                {
                    Ok(true) => {
                        completed = true;
                        break;
                    }
                    Ok(false) => {
                        info!("Mirror download cancelled for: {}", model_id);
                        return Ok(false);
                    }
                    Err(e) => {
                        warn!(
                            "Mirror download failed for {} from {}: {:?}",
                            model_id, mirror.url, e
                        );
                    }
                }
            }
            if !completed {
                return Err(anyhow::anyhow!(
                    "Download failed from Hugging Face ({}) and {} mirror(s)",
                    hf_error,
                    mirrors.len()
                ));
            }
        }

        Ok(true)
    }

    /// Direct-HTTP download of a catalog model's file from a mirror into the
    /// models dir (HF-model resolution accepts that location too). Returns
    /// `Ok(true)` on completion, `Ok(false)` if cancelled (partial kept).
    async fn download_from_mirror(
        &self,
        progress: &ProgressTarget,
        filename: &str,
        mirror: &crate::catalog::MirrorFile,
        cancel_token: CancellationToken,
    ) -> Result<bool> {
        fs::create_dir_all(&self.models_dir)?;
        let model_path = self.models_dir.join(filename);
        let partial_path = self.models_dir.join(format!("{}.partial", filename));

        if model_path.exists() {
            return Ok(true);
        }

        match self
            .download_http_resumable(
                progress,
                &mirror.url,
                &partial_path,
                Some(mirror.size_bytes),
                Some(&mirror.sha256),
                &cancel_token,
            )
            .await?
        {
            HttpDownloadOutcome::Cancelled => Ok(false),
            HttpDownloadOutcome::Completed => {
                fs::rename(&partial_path, &model_path)?;
                info!(
                    "Mirror download of {} completed and verified ({:?})",
                    filename, model_path
                );
                Ok(true)
            }
        }
    }

    pub async fn download_model(&self, model_id: &str) -> Result<()> {
        let model_info = {
            let models = self.available_models.lock().unwrap();
            models.get(model_id).cloned()
        };

        let model_info =
            model_info.ok_or_else(|| anyhow::anyhow!("Model not found: {}", model_id))?;

        let (url, expected_sha256) = match &model_info.source {
            ModelSource::Url { url, sha256 } => (url.clone(), sha256.clone()),
            ModelSource::HuggingFace { repo_id, revision } => {
                return self
                    .download_hf_model(&model_info, repo_id.clone(), revision.clone())
                    .await;
            }
            ModelSource::Local => {
                return Err(anyhow::anyhow!("No download source for model"));
            }
        };
        let model_path = self.models_dir.join(&model_info.filename);
        let partial_path = self
            .models_dir
            .join(format!("{}.partial", &model_info.filename));

        // Don't download if complete version already exists
        if model_path.exists() {
            // Clean up any partial file that might exist
            if partial_path.exists() {
                let _ = fs::remove_file(&partial_path);
            }
            self.update_download_status()?;
            return Ok(());
        }

        // Mark as downloading
        {
            let mut models = self.available_models.lock().unwrap();
            if let Some(model) = models.get_mut(model_id) {
                model.is_downloading = true;
            }
        }

        // Create cancellation token for this download
        let cancel_token = CancellationToken::new();
        {
            let mut flags = self.cancel_flags.lock().unwrap();
            flags.insert(model_id.to_string(), cancel_token.clone());
        }

        // Guard ensures is_downloading and cancel_flags are cleaned up on every
        // error path. Disarmed only on success (which sets is_downloaded = true).
        let mut cleanup = DownloadCleanup {
            available_models: &self.available_models,
            cancel_flags: &self.cancel_flags,
            model_id: model_id.to_string(),
            disarmed: false,
        };

        // URL sources carry no authoritative size, so the helper falls back to
        // the server's content-length for progress and completeness checks.
        match self
            .download_http_resumable(
                &ProgressTarget::own(model_id),
                &url,
                &partial_path,
                None,
                expected_sha256.as_deref(),
                &cancel_token,
            )
            .await?
        {
            HttpDownloadOutcome::Cancelled => {
                info!("Download cancelled for: {}", model_id);
                // Keep partial file for resume functionality.
                // Guard handles is_downloading + cancel_flags cleanup on drop.
                return Ok(());
            }
            HttpDownloadOutcome::Completed => {}
        }

        fs::rename(&partial_path, &model_path)?;

        // Disarm the guard — success path does its own cleanup because it
        // additionally sets is_downloaded = true.
        cleanup.disarmed = true;
        {
            let mut models = self.available_models.lock().unwrap();
            if let Some(model) = models.get_mut(model_id) {
                model.is_downloading = false;
                model.is_downloaded = true;
                model.partial_size = 0;
            }
        }
        self.cancel_flags.lock().unwrap().remove(model_id);

        // Emit completion event
        let _ = self.app_handle.emit("model-download-complete", model_id);

        info!(
            "Successfully downloaded model {} to {:?}",
            model_id, model_path
        );

        Ok(())
    }

    pub fn delete_model(&self, model_id: &str) -> Result<()> {
        debug!("ModelManager: delete_model called for: {}", model_id);

        let model_info = {
            let models = self.available_models.lock().unwrap();
            models.get(model_id).cloned()
        };

        let model_info =
            model_info.ok_or_else(|| anyhow::anyhow!("Model not found: {}", model_id))?;

        debug!("ModelManager: Found model info: {:?}", model_info);

        if let ModelSource::HuggingFace { repo_id, revision } = &model_info.source {
            // Only this entry's own file, every cached copy of it. Other
            // quants of the repo are separate entries: deleting the Q8_0
            // default must not take a user's Q5_K_M with it. Per product
            // decision this hard-removes from every HF cache, including one
            // shared with other apps. A file that can't be removed (in use on
            // Windows, permissions) fails the delete so the UI says so; copies
            // removed before it stay removed, and the entry keeps reading as
            // downloaded while any copy remains.
            let mut deleted = Self::delete_hf_cache_file(repo_id, revision, &model_info.filename)?;
            // Also remove a models-dir copy (mirror fallback / manual drop-in)
            // and any resumable partial next to it.
            for path in [
                self.models_dir.join(&model_info.filename),
                self.models_dir
                    .join(format!("{}.partial", &model_info.filename)),
            ] {
                if path.exists() {
                    info!("Deleting model file at: {:?}", path);
                    fs::remove_file(&path)?;
                    deleted = true;
                }
            }
            // Files already missing (e.g. removed outside Handy) is not a failure —
            // deleting is idempotent, so this still needs to fall through and clear
            // the stale "Downloaded" entry rather than erroring out and leaving it stuck.
            if !deleted {
                debug!(
                    "ModelManager: no HF cache/model files found on disk for {}; clearing stale entry",
                    model_id
                );
            }
            // Alternate quants exist only while their files are on disk.
            if Self::is_catalog_alternate_quant(repo_id, &model_info.filename) {
                self.available_models.lock().unwrap().remove(model_id);
            }
            self.update_download_status()?;
            let _ = self.app_handle.emit("model-deleted", model_id);
            return Ok(());
        }

        let model_path = self.models_dir.join(&model_info.filename);
        let partial_path = self
            .models_dir
            .join(format!("{}.partial", &model_info.filename));
        debug!("ModelManager: Model path: {:?}", model_path);
        debug!("ModelManager: Partial path: {:?}", partial_path);

        let mut deleted_something = false;

        // Delete complete model file if it exists
        if model_path.exists() {
            info!("Deleting model file at: {:?}", model_path);
            fs::remove_file(&model_path)?;
            info!("Model file deleted successfully");
            deleted_something = true;
        }

        // Delete partial file if it exists
        if partial_path.exists() {
            info!("Deleting partial file at: {:?}", partial_path);
            fs::remove_file(&partial_path)?;
            info!("Partial file deleted successfully");
            deleted_something = true;
        }

        // Files already missing (e.g. removed outside Handy) is not a failure —
        // deleting is idempotent, so this still needs to fall through and clear
        // the stale "Downloaded" entry rather than erroring out and leaving it stuck.
        if !deleted_something {
            debug!(
                "ModelManager: no files found on disk for {}; clearing stale entry",
                model_id
            );
        }

        // Custom models should be removed from the list entirely since they
        // have no download URL and can't be re-downloaded
        if model_info.is_custom {
            let mut models = self.available_models.lock().unwrap();
            models.remove(model_id);
            debug!("ModelManager: removed custom model from available models");
        } else {
            // Update download status (marks predefined models as not downloaded)
            self.update_download_status()?;
            debug!("ModelManager: download status updated");
        }

        // Emit event to notify UI
        let _ = self.app_handle.emit("model-deleted", model_id);

        Ok(())
    }

    /// Reconcile a model that was advertised as downloaded but whose path has
    /// since disappeared. This is deliberately narrower than a full rescan: it
    /// only runs after a definitive missing-path check and cannot disturb an
    /// unrelated in-flight download.
    fn mark_model_unavailable(&self, model_id: &str) {
        let removed = {
            let mut models = self.available_models.lock().unwrap();
            let should_remove = models
                .get(model_id)
                .is_some_and(Self::disappears_when_missing);
            if should_remove {
                models.remove(model_id);
                true
            } else if let Some(model) = models.get_mut(model_id) {
                model.is_downloaded = false;
                false
            } else {
                return;
            }
        };

        if removed {
            info!("Removing vanished discovered model '{}'", model_id);
        } else {
            info!("Marking model '{}' as unavailable on disk", model_id);
        }
        // Keep the persisted preference here: an already-loaded engine may
        // still be usable, and re-downloading this model should restore it.
        // Startup and explicit Rescan perform the broader selection cleanup.
        let _ = self.app_handle.emit("models-updated", ());
    }

    pub fn get_model_path(&self, model_id: &str) -> Result<PathBuf> {
        let model_info = self
            .get_model_info(model_id)
            .ok_or_else(|| anyhow::anyhow!("Model not found: {}", model_id))?;

        if !model_info.is_downloaded {
            return Err(anyhow::anyhow!("Model not available: {}", model_id));
        }

        // Ensure we don't return partial files/directories
        if model_info.is_downloading {
            return Err(anyhow::anyhow!(
                "Model is currently downloading: {}",
                model_id
            ));
        }

        if let ModelSource::HuggingFace { repo_id, revision } = &model_info.source {
            if let Some(path) = hf_cached_path(repo_id, revision, &model_info.filename) {
                return Ok(path);
            }
            // Mirror-fallback download or manual drop-in in the models dir.
            // The complete file only ever appears after verification, so a
            // stale `.partial` alongside it is leftover noise, not a veto —
            // clear it rather than declaring the model missing.
            let local_path = self.models_dir.join(&model_info.filename);
            if local_path.exists() {
                let partial_path = self
                    .models_dir
                    .join(format!("{}.partial", &model_info.filename));
                if partial_path.exists() {
                    let _ = fs::remove_file(&partial_path);
                }
                return Ok(local_path);
            }
            self.mark_model_unavailable(model_id);
            return Err(anyhow::anyhow!(
                "Complete model file not found in HF cache or models dir: {}",
                model_id
            ));
        }

        let model_path = self.models_dir.join(&model_info.filename);
        let partial_path = self
            .models_dir
            .join(format!("{}.partial", &model_info.filename));

        if !model_path.exists() {
            self.mark_model_unavailable(model_id);
            return Err(anyhow::anyhow!(
                "Complete model file not found: {}",
                model_id
            ));
        }
        if partial_path.exists() {
            return Err(anyhow::anyhow!("Model file is incomplete: {}", model_id));
        }
        Ok(model_path)
    }

    /// The spoken-language detector's file, when it is fully on disk: in the
    /// HF cache, or in the models dir (mirror fallback / manual drop-in).
    pub fn language_detector_path(&self) -> Option<PathBuf> {
        let detector = crate::catalog::LANGUAGE_DETECTOR.as_ref()?;
        hf_cached_path(&detector.repo_id, &detector.revision, &detector.filename).or_else(|| {
            let local = self.models_dir.join(&detector.filename);
            local.is_file().then_some(local)
        })
    }

    pub fn cancel_download(&self, model_id: &str) -> Result<()> {
        debug!("ModelManager: cancel_download called for: {}", model_id);

        // Trigger the cancellation token to stop the download. The HF path
        // aborts its in-flight chunk tasks and unwinds promptly; the URL path
        // observes it on the next chunk of its stream loop.
        {
            let flags = self.cancel_flags.lock().unwrap();
            if let Some(token) = flags.get(model_id) {
                token.cancel();
                info!("Cancellation token triggered for: {}", model_id);
            } else {
                warn!("No active download found for: {}", model_id);
            }
        }

        // Update state immediately for UI responsiveness
        {
            let mut models = self.available_models.lock().unwrap();
            if let Some(model) = models.get_mut(model_id) {
                model.is_downloading = false;
            }
        }

        // Update download status to reflect current state
        self.update_download_status()?;

        // Emit cancellation event so all UI components can clear their state
        let _ = self.app_handle.emit("model-download-cancelled", model_id);

        info!("Download cancellation initiated for: {}", model_id);
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn detector_then_model_report_as_one_bar() {
        // 45 MB detector, then a 700 MB model: one bar from 0 to 745 MB.
        let detector = ProgressTarget {
            model_id: "m".into(),
            offset: 0,
            total: Some(745),
        };
        let p = detector.progress(45, 45, None);
        assert_eq!((p.model_id.as_str(), p.downloaded, p.total), ("m", 45, 745));

        let model = ProgressTarget {
            model_id: "m".into(),
            offset: 45,
            total: None,
        };
        let p = model.progress(350, 700, Some(1.0));
        assert_eq!((p.downloaded, p.total), (395, 745));
    }
    use std::fs::File;
    use std::io::Write;
    use tempfile::TempDir;

    fn add_cached_model(cache: &Path, repo_id: &str, revision: &str, filename: &str) -> PathBuf {
        let repo_dir = cache.join(format!("models--{}", repo_id.replace('/', "--")));
        let snapshot = repo_dir.join("snapshots").join(revision).join(filename);
        fs::create_dir_all(snapshot.parent().unwrap()).unwrap();
        fs::create_dir_all(repo_dir.join("refs")).unwrap();
        fs::write(repo_dir.join("refs").join(revision), revision).unwrap();
        fs::write(&snapshot, b"model").unwrap();
        snapshot
    }

    #[test]
    fn test_hf_cached_path_falls_back_to_legacy_cache() {
        let active = TempDir::new().unwrap();
        let legacy = TempDir::new().unwrap();
        let expected = add_cached_model(
            legacy.path(),
            "handy-computer/test-model",
            "old-revision",
            "model.gguf",
        );
        let caches = vec![
            Cache::new(active.path().to_path_buf()),
            Cache::new(legacy.path().to_path_buf()),
        ];

        assert_eq!(
            hf_cached_path_in(
                &caches,
                "handy-computer/test-model",
                "old-revision",
                "model.gguf"
            ),
            Some(expected)
        );
    }

    #[test]
    fn test_hf_cached_path_prefers_active_cache() {
        let active = TempDir::new().unwrap();
        let legacy = TempDir::new().unwrap();
        let expected = add_cached_model(
            active.path(),
            "handy-computer/test-model",
            "revision",
            "model.gguf",
        );
        add_cached_model(
            legacy.path(),
            "handy-computer/test-model",
            "revision",
            "model.gguf",
        );
        let caches = vec![
            Cache::new(active.path().to_path_buf()),
            Cache::new(legacy.path().to_path_buf()),
        ];

        assert_eq!(
            hf_cached_path_in(
                &caches,
                "handy-computer/test-model",
                "revision",
                "model.gguf"
            ),
            Some(expected)
        );
    }

    /// A file in snapshot `commit` with no ref pointing at it — how
    /// huggingface_hub leaves a download made at a commit revision, and how an
    /// earlier pin looks once the catalog moves on.
    fn add_unreferenced_snapshot_file(
        cache: &Path,
        repo_id: &str,
        commit: &str,
        filename: &str,
    ) -> PathBuf {
        let path = cache
            .join(format!("models--{}", repo_id.replace('/', "--")))
            .join("snapshots")
            .join(commit)
            .join(filename);
        fs::create_dir_all(path.parent().unwrap()).unwrap();
        fs::write(&path, b"model").unwrap();
        path
    }

    fn catalog_model(id_prefix: &str) -> &'static ModelDescriptor {
        crate::catalog::CATALOG
            .iter()
            .find(|d| d.id.starts_with(id_prefix))
            .unwrap_or_else(|| panic!("catalog has {id_prefix}"))
    }

    fn hf_source(desc: &ModelDescriptor) -> (&str, &str) {
        match &desc.source {
            ModelSource::HuggingFace { repo_id, revision } => (repo_id, revision),
            _ => panic!("catalog descriptors are HF-sourced"),
        }
    }

    #[test]
    fn test_every_retired_model_has_a_downloadable_replacement() {
        // A missing replacement would silently hide a row in the migration UI.
        let mut registry = HashMap::new();
        ModelManager::seed_catalog_models(&mut registry);
        for retired in RETIRED_ONNX_MODELS {
            let replacement = registry
                .values()
                .find(|info| {
                    matches!(&info.source, ModelSource::HuggingFace { repo_id, .. }
                        if repo_id == retired.replacement_repo)
                })
                .unwrap_or_else(|| {
                    panic!(
                        "{}: replacement {} is not offered",
                        retired.id, retired.replacement_repo
                    )
                });
            assert!(
                !crate::catalog::mirror_fallbacks(&replacement.id).is_empty(),
                "{}: replacement {} has no mirror fallback",
                retired.id,
                replacement.id
            );
        }
    }

    #[test]
    fn test_cache_lookup_prefers_pin_then_main_then_any_snapshot() {
        let cache = TempDir::new().unwrap();
        let repo = "someone/model";
        let revision = "a".repeat(40);
        let old = add_unreferenced_snapshot_file(cache.path(), repo, "unknown", "model.gguf");
        let main = add_cached_model(cache.path(), repo, "main", "model.gguf");
        let pin = add_unreferenced_snapshot_file(cache.path(), repo, &revision, "model.gguf");
        let caches = vec![Cache::new(cache.path().to_path_buf())];

        assert_eq!(
            hf_cached_paths_in(&caches, repo, &revision, "model.gguf"),
            vec![pin.clone(), main.clone(), old.clone()]
        );
        for expected in [pin, main, old] {
            assert_eq!(
                hf_cached_path_in(&caches, repo, &revision, "model.gguf"),
                Some(expected.clone())
            );
            fs::remove_file(expected).unwrap();
        }
        assert!(hf_cached_path_in(&caches, repo, &revision, "model.gguf").is_none());
    }

    #[test]
    fn test_old_q5_is_discovered_and_survives_deleting_all_q8_copies() {
        let desc = catalog_model("handy-computer/whisper-large-v3-gguf/");
        let (repo, revision) = hf_source(desc);
        let q5 = desc.files.iter().find(|f| f.quant == "Q5_K_M").unwrap();
        let q8 = desc.default_file().unwrap();
        assert_eq!(q8.quant, "Q8_0");

        let cache = TempDir::new().unwrap();
        let legacy = TempDir::new().unwrap();
        let old = add_unreferenced_snapshot_file(cache.path(), repo, "unknown", &q5.filename);
        let caches = vec![
            Cache::new(cache.path().to_path_buf()),
            Cache::new(legacy.path().to_path_buf()),
        ];
        for cache in &caches {
            for rev in [revision, "main", "unknown"] {
                add_unreferenced_snapshot_file(cache.path(), repo, rev, &q8.filename);
            }
        }
        let readme = old.parent().unwrap().join("README.md");
        fs::write(&readme, "unrelated file").unwrap();

        let mut models = HashMap::new();
        ModelManager::seed_catalog_models(&mut models);
        ModelManager::discover_hf_cache_models_in(cache.path(), &mut models);
        let info = &models[&format!("{repo}/{}", q5.filename)];
        assert!(info.is_downloaded);
        assert_eq!(info.name, format!("{} (Q5_K_M)", desc.name));
        assert!(models.contains_key(&desc.id));

        assert!(
            ModelManager::delete_hf_cache_file_in(&caches, repo, revision, &q8.filename).unwrap()
        );
        assert!(hf_cached_paths_in(&caches, repo, revision, &q8.filename).is_empty());
        assert_eq!(
            hf_cached_path_in(&caches, repo, revision, &q5.filename),
            Some(old)
        );
        assert!(readme.exists());
    }

    /// An HF-style cached file: a snapshot symlink to a blob named after its
    /// content, so copies at several revisions can share one blob.
    #[cfg(unix)]
    fn add_cached_blob(cache: &Path, repo_id: &str, commit: &str, filename: &str) -> PathBuf {
        let repo_dir = cache.join(format!("models--{}", repo_id.replace('/', "--")));
        let blob = repo_dir.join("blobs").join("b".repeat(64));
        fs::create_dir_all(blob.parent().unwrap()).unwrap();
        fs::write(&blob, b"model").unwrap();
        let pointer = repo_dir.join("snapshots").join(commit).join(filename);
        fs::create_dir_all(pointer.parent().unwrap()).unwrap();
        std::os::unix::fs::symlink(&blob, &pointer).unwrap();
        pointer
    }

    #[cfg(unix)]
    #[test]
    fn test_delete_preserves_other_filenames_sharing_a_blob() {
        let cache = TempDir::new().unwrap();
        let repo = "someone/model";
        let first = add_cached_blob(cache.path(), repo, "first", "model.gguf");
        let second = add_cached_blob(cache.path(), repo, "second", "model.gguf");
        let other = add_cached_blob(cache.path(), repo, "second", "other.gguf");
        let blob = fs::canonicalize(&other).unwrap();
        let caches = vec![Cache::new(cache.path().to_path_buf())];

        assert!(
            ModelManager::delete_hf_cache_file_in(&caches, repo, "main", "model.gguf").unwrap()
        );
        assert!(fs::symlink_metadata(first).is_err());
        assert!(fs::symlink_metadata(second).is_err());
        assert!(other.is_file());
        assert!(
            ModelManager::delete_hf_cache_file_in(&caches, repo, "main", "other.gguf").unwrap()
        );
        assert!(!blob.exists());
    }

    #[cfg(unix)]
    #[test]
    fn test_delete_reports_a_file_it_cant_remove() {
        // A file that can't be removed (in use on Windows, permissions) must
        // fail the delete, not report success while the model stays on disk.
        use std::os::unix::fs::PermissionsExt;

        let desc = catalog_model("handy-computer/canary-180m-flash-gguf/");
        let (repo_id, revision) = hf_source(desc);
        let filename = &desc.default_file().unwrap().filename;
        let caches_in = |cache: &TempDir| vec![Cache::new(cache.path().to_path_buf())];
        let lock =
            |dir: &Path, mode| fs::set_permissions(dir, fs::Permissions::from_mode(mode)).unwrap();

        // Plain file (hf-hub's no-symlink layout) in a read-only snapshot.
        let cache = TempDir::new().unwrap();
        let file = add_cached_model(cache.path(), repo_id, revision, filename);
        lock(file.parent().unwrap(), 0o555);
        let result =
            ModelManager::delete_hf_cache_file_in(&caches_in(&cache), repo_id, revision, filename);
        lock(file.parent().unwrap(), 0o755);
        assert!(result.is_err(), "undeletable file read as {result:?}");
        assert!(file.exists());

        // Symlinked blob in a read-only blobs dir: the pointer stays, so the
        // entry still (correctly) reads as downloaded.
        let cache = TempDir::new().unwrap();
        let pointer = add_cached_blob(cache.path(), repo_id, revision, filename);
        let blobs = hf_repo_dir(&pointer).unwrap().join("blobs");
        lock(&blobs, 0o555);
        let result =
            ModelManager::delete_hf_cache_file_in(&caches_in(&cache), repo_id, revision, filename);
        lock(&blobs, 0o755);
        assert!(result.is_err(), "undeletable blob read as {result:?}");
        assert!(pointer.exists(), "pointer removed while its blob stayed");
    }

    #[test]
    fn test_effective_language_falls_back_to_canonical_chinese() {
        let languages = vec!["zh-Hant".to_string()];

        assert_eq!(effective_language("auto", &[], &languages, false), "zh");
    }

    #[test]
    fn test_effective_language_falls_back_to_the_one_preferred_language() {
        let languages = vec!["en".to_string(), "es-ES".to_string(), "de".to_string()];
        let spanish = vec!["es".to_string()];
        let several = vec!["es".to_string(), "de".to_string()];
        let unheard = vec!["ja".to_string()];

        // A model that must be told: the one language they speak.
        assert_eq!(
            effective_language("auto", &spanish, &languages, false),
            "es-ES"
        );
        // Several, or one the model doesn't hear: the English fallback.
        assert_eq!(
            effective_language("auto", &several, &languages, false),
            "en"
        );
        assert_eq!(
            effective_language("auto", &unheard, &languages, false),
            "en"
        );
        // A model that detects stays on auto; a usable intent still wins.
        assert_eq!(
            effective_language("auto", &spanish, &languages, true),
            "auto"
        );
        assert_eq!(effective_language("de", &spanish, &languages, false), "de");
    }

    #[test]
    fn test_effective_language_resolves_bare_intent_to_concrete_locale() {
        // A model advertising full BCP-47 locales (e.g. Nemotron Streaming):
        // a bare intent must resolve to the exact code the engine expects, not
        // be handed back as the bare form the prompt table may not contain.
        let languages = vec![
            "en-US".to_string(),
            "en-GB".to_string(),
            "es-ES".to_string(),
            "zh-CN".to_string(),
            "ja-JP".to_string(),
        ];

        assert_eq!(effective_language("en", &[], &languages, true), "en-US");
        assert_eq!(effective_language("es", &[], &languages, true), "es-ES");
        // `zh`/`ja` have no bare entry in this model's table; resolve to locale.
        assert_eq!(effective_language("zh", &[], &languages, true), "zh-CN");
        assert_eq!(effective_language("ja", &[], &languages, true), "ja-JP");
        // An unsupported intent still auto-detects when the model can.
        assert_eq!(effective_language("fr", &[], &languages, true), "auto");
    }

    #[test]
    fn test_effective_language_preserves_intent_across_model_code_variants() {
        assert_eq!(
            effective_language("no", &[], &["nb".to_string()], true),
            "nb"
        );
        assert_eq!(
            effective_language("nb", &[], &["no".to_string()], true),
            "no"
        );
        assert_eq!(
            effective_language("tl", &[], &["fil".to_string()], true),
            "fil"
        );
        assert_eq!(
            effective_language("fil", &[], &["tl".to_string()], true),
            "tl"
        );
        assert_eq!(
            effective_language("jv", &[], &["jw".to_string()], true),
            "jw"
        );
        assert_eq!(
            effective_language("he", &[], &["iw".to_string()], true),
            "iw"
        );
    }

    #[test]
    fn test_effective_language_prefers_exact_norwegian_code() {
        let languages = vec!["no".to_string(), "nb".to_string()];

        assert_eq!(effective_language("nb", &[], &languages, true), "nb");
        assert_eq!(effective_language("no", &[], &languages, true), "no");
    }

    #[test]
    fn test_canonicalize_supported_languages_collapses_chinese_scripts() {
        let languages = canonicalize_supported_languages(
            vec!["en", "zh", "zh-Hans", "zh-Hant", "yue"]
                .into_iter()
                .map(String::from)
                .collect(),
        );

        assert_eq!(languages, vec!["en", "zh", "yue"]);
    }

    fn build_test_gguf_string_metadata(kvs: &[(&str, &str)]) -> Vec<u8> {
        let mut out = Vec::new();
        out.extend_from_slice(b"GGUF");
        out.extend_from_slice(&3u32.to_le_bytes());
        out.extend_from_slice(&0u64.to_le_bytes());
        out.extend_from_slice(&(kvs.len() as u64).to_le_bytes());
        for (key, value) in kvs {
            push_gguf_str(&mut out, key);
            out.extend_from_slice(&8u32.to_le_bytes()); // GGUF string value type.
            push_gguf_str(&mut out, value);
        }
        out
    }

    #[test]
    fn test_discover_custom_transcribe_models() {
        let temp_dir = TempDir::new().unwrap();
        let models_dir = temp_dir.path().to_path_buf();

        // Create test .bin files
        let mut custom_file = File::create(models_dir.join("my-custom-model.bin")).unwrap();
        custom_file.write_all(b"fake model data").unwrap();

        let mut another_file = File::create(models_dir.join("whisper_medical_v2.bin")).unwrap();
        another_file.write_all(b"another fake model").unwrap();

        // Custom GGUF model (also supported by transcribe-cpp)
        let mut gguf_file = File::create(models_dir.join("my-gguf-model.gguf")).unwrap();
        gguf_file
            .write_all(&build_test_gguf_string_metadata(&[(
                "general.name",
                "Friendly GGUF Name",
            )]))
            .unwrap();

        // Create files that should be ignored
        File::create(models_dir.join(".hidden-model.bin")).unwrap(); // Hidden file
        File::create(models_dir.join("readme.txt")).unwrap(); // Non-model file
        File::create(models_dir.join("ggml-small.bin")).unwrap(); // Predefined filename
        File::create(models_dir.join("download.bin.partial")).unwrap(); // Partial download
        fs::create_dir(models_dir.join("some-directory.bin")).unwrap(); // Directory

        // Set up available_models with a predefined Whisper model
        let mut models = HashMap::new();
        models.insert(
            "small".to_string(),
            ModelInfo {
                id: "small".to_string(),
                name: "Whisper Small".to_string(),
                description: "Test".to_string(),
                filename: "ggml-small.bin".to_string(),
                source: ModelSource::Url {
                    url: "https://example.com".to_string(),
                    sha256: None,
                },
                size_mb: 100,
                is_downloaded: false,
                is_downloading: false,
                partial_size: 0,
                accuracy_score: 0.5,
                speed_score: 0.5,
                supports_translation: true,
                is_recommended: false,
                supported_languages: vec!["en".to_string()],
                supports_language_selection: true,
                is_custom: false,
                supports_streaming: false,
                // Legacy entry: preserve the historical "Auto offered" behavior.
                // (Catalog GGUFs and on-disk probes derive this from metadata.)
                supports_language_detection: true,
            },
        );

        // Discover custom models
        ModelManager::discover_custom_transcribe_models(&models_dir, &mut models).unwrap();

        // Should have discovered 2 custom models (my-custom-model and whisper_medical_v2)
        assert!(models.contains_key("my-custom-model"));
        assert!(models.contains_key("whisper_medical_v2"));

        // Verify custom model properties
        let custom = models.get("my-custom-model").unwrap();
        assert_eq!(custom.name, "My Custom Model");
        assert_eq!(custom.filename, "my-custom-model.bin");
        assert!(matches!(custom.source, ModelSource::Local)); // Custom models have no remote source
        assert!(custom.is_downloaded);
        assert!(custom.is_custom);
        assert!(ModelManager::disappears_when_missing(custom));
        assert_eq!(custom.accuracy_score, 0.0);
        assert_eq!(custom.speed_score, 0.0);
        assert!(custom.supported_languages.is_empty());

        // Verify underscore handling
        let medical = models.get("whisper_medical_v2").unwrap();
        assert_eq!(medical.name, "Whisper Medical V2");

        // Verify .gguf models are discovered too (extension stripped for the id)
        assert!(models.contains_key("my-gguf-model"));
        let gguf = models.get("my-gguf-model").unwrap();
        assert_eq!(gguf.filename, "my-gguf-model.gguf");
        assert_eq!(gguf.name, "Friendly GGUF Name");
        assert!(gguf.is_custom);

        // Should NOT have discovered hidden, non-model, predefined, partial, or directories
        assert!(!models.contains_key(".hidden-model"));
        assert!(!models.contains_key("readme"));
        assert!(!models.contains_key("download.bin"));
        assert!(!models.contains_key("some-directory"));
    }

    #[test]
    fn test_discover_custom_models_empty_dir() {
        let temp_dir = TempDir::new().unwrap();
        let models_dir = temp_dir.path().to_path_buf();

        let mut models = HashMap::new();
        let count_before = models.len();

        ModelManager::discover_custom_transcribe_models(&models_dir, &mut models).unwrap();

        // No new models should be added
        assert_eq!(models.len(), count_before);
    }

    #[test]
    fn a_mirrored_language_detector_is_not_a_custom_model() {
        let temp_dir = TempDir::new().unwrap();
        let detector = crate::catalog::LANGUAGE_DETECTOR.as_ref().unwrap();
        fs::write(temp_dir.path().join(&detector.filename), b"gguf").unwrap();

        let mut models = HashMap::new();
        ModelManager::discover_custom_transcribe_models(temp_dir.path(), &mut models).unwrap();
        assert!(models.is_empty());
    }

    #[test]
    fn test_discover_custom_models_nonexistent_dir() {
        let models_dir = PathBuf::from("/nonexistent/path/that/does/not/exist");

        let mut models = HashMap::new();
        let count_before = models.len();

        // Should not error, just return Ok
        let result = ModelManager::discover_custom_transcribe_models(&models_dir, &mut models);
        assert!(result.is_ok());
        assert_eq!(models.len(), count_before);
    }

    #[test]
    fn test_catalog_quant_rendering() {
        let desc = ModelDescriptor {
            id: "org/repo/model-Q8_0.gguf".to_string(),
            source: ModelSource::HuggingFace {
                repo_id: "org/repo".to_string(),
                revision: "main".to_string(),
            },
            name: "Model".to_string(),
            description: "desc".to_string(),
            caps: CapabilityProbe::default(),
            files: vec![
                QuantFile {
                    filename: "model-Q4_K_M.gguf".to_string(),
                    quant: "Q4_K_M".to_string(),
                    size_bytes: 1,
                },
                QuantFile {
                    filename: "model-Q8_0.gguf".to_string(),
                    quant: "Q8_0".to_string(),
                    size_bytes: 2,
                },
            ],
            default_quant: Some("Q8_0".to_string()),
            speed_score: 0.5,
            accuracy_score: 0.5,
            recommended_rank: None,
            recommended: true,
        };
        let status = DiskStatus::default();

        // Default quant: plain name, badge intact.
        let default_info = desc.to_model_info(&status);
        assert_eq!(default_info.name, "Model");
        assert!(default_info.is_recommended);

        // Alternate quant: suffixed name, own id, no badge.
        let alt_info = desc.to_model_info_for_file(&desc.files[0], &status);
        assert_eq!(alt_info.id, "org/repo/model-Q4_K_M.gguf");
        assert_eq!(alt_info.name, "Model (Q4_K_M)");
        assert_eq!(alt_info.filename, "model-Q4_K_M.gguf");
        assert!(!alt_info.is_recommended);
        assert!(!alt_info.is_custom);

        // Catalog defaults stay visible for re-download when their file is gone.
        assert!(!ModelManager::disappears_when_missing(&default_info));

        let mut selection_models = HashMap::new();
        selection_models.insert(default_info.id.clone(), default_info.clone());
        assert!(!ModelManager::selected_model_is_available(
            &selection_models,
            &default_info.id
        ));
        selection_models
            .get_mut(&default_info.id)
            .unwrap()
            .is_downloaded = true;
        assert!(ModelManager::selected_model_is_available(
            &selection_models,
            &default_info.id
        ));

        // The default rendered through the per-file path matches to_model_info,
        // so seeded entries and discovered defaults can never diverge.
        let same = desc.to_model_info_for_file(&desc.files[1], &status);
        assert_eq!(same.id, default_info.id);
        assert_eq!(same.name, default_info.name);
        assert_eq!(same.is_recommended, default_info.is_recommended);
    }

    #[test]
    fn test_discover_catalog_alternate_quant_in_models_dir() {
        // A real catalog model with more than one quant.
        let desc = crate::catalog::CATALOG
            .iter()
            .find(|d| d.files.len() > 1)
            .expect("catalog offers multi-quant models");
        let default_filename = default_quant_file(&desc.files, desc.default_quant.as_deref())
            .unwrap()
            .filename
            .clone();
        let alt = desc
            .files
            .iter()
            .find(|f| f.filename != default_filename)
            .unwrap();

        let temp_dir = TempDir::new().unwrap();
        // Content is never probed for catalog-matched files, so empty files do.
        fs::write(temp_dir.path().join(&alt.filename), b"").unwrap();
        fs::write(temp_dir.path().join(&default_filename), b"").unwrap();

        let mut models = HashMap::new();
        ModelManager::seed_catalog_models(&mut models);
        let seeded = models.len();
        ModelManager::discover_custom_transcribe_models(temp_dir.path(), &mut models).unwrap();

        // The alternate quant surfaces as a catalog-grade HF entry…
        let ModelSource::HuggingFace { repo_id, .. } = &desc.source else {
            panic!("catalog descriptors are HF-sourced");
        };
        let alt_id = format!("{}/{}", repo_id, alt.filename);
        let info = models.get(&alt_id).expect("alternate quant discovered");
        assert_eq!(info.name, format!("{} ({})", desc.name, alt.quant));
        assert_eq!(info.description, desc.description);
        assert!(info.is_downloaded);
        assert!(!info.is_custom);
        assert!(matches!(info.source, ModelSource::HuggingFace { .. }));
        assert!(ModelManager::disappears_when_missing(info));

        // …while the default-quant file dedups onto its seeded entry: exactly
        // one new id, and no filename-stem custom entries for either file.
        assert_eq!(models.len(), seeded + 1);
        assert!(!models.contains_key(alt.filename.trim_end_matches(".gguf")));
        assert!(!models.contains_key(default_filename.trim_end_matches(".gguf")));
    }

    fn push_gguf_str(out: &mut Vec<u8>, val: &str) {
        out.extend_from_slice(&(val.len() as u64).to_le_bytes());
        out.extend_from_slice(val.as_bytes());
    }

    fn write_synthetic_gguf(path: &Path, arch: &str, languages: &[&str]) {
        let mut out: Vec<u8> = Vec::new();
        out.extend_from_slice(&0x4655_4747u32.to_le_bytes()); // magic "GGUF"
        out.extend_from_slice(&3u32.to_le_bytes()); // version
        out.extend_from_slice(&0u64.to_le_bytes()); // tensor_count
        out.extend_from_slice(&2u64.to_le_bytes()); // kv_count
                                                    // general.architecture : string
        push_gguf_str(&mut out, "general.architecture");
        out.extend_from_slice(&8u32.to_le_bytes()); // STRING
        push_gguf_str(&mut out, arch);
        // general.languages : array<string>
        push_gguf_str(&mut out, "general.languages");
        out.extend_from_slice(&9u32.to_le_bytes()); // ARRAY
        out.extend_from_slice(&8u32.to_le_bytes()); // elem STRING
        out.extend_from_slice(&(languages.len() as u64).to_le_bytes());
        for l in languages {
            push_gguf_str(&mut out, l);
        }
        fs::write(path, out).unwrap();
    }

    #[test]
    fn test_discover_hf_cache_keeps_the_cache_folder_casing() {
        // HF repo ids are case-insensitive, so another tool can cache a catalog
        // repo under other casing. On a case-sensitive filesystem only that
        // casing finds the file again, so it must not take the catalog's.
        let filename = "SenseVoiceSmall-Q8_0.gguf";
        let folder_repo = "handy-computer/sensevoicesmall-gguf";
        assert!(crate::catalog::file_in_catalog(
            filename,
            Some("handy-computer/SenseVoiceSmall-gguf")
        )
        .is_some());

        let cache = TempDir::new().unwrap();
        let path = add_cached_model(cache.path(), folder_repo, "main", filename);
        write_synthetic_gguf(&path, "sensevoice", &["en", "zh"]);

        let mut models = HashMap::new();
        ModelManager::discover_hf_cache_models_in(cache.path(), &mut models);

        let info = models
            .values()
            .find(|m| m.filename == filename)
            .expect("cached file is listed");
        assert!(
            matches!(&info.source, ModelSource::HuggingFace { repo_id, .. } if repo_id == folder_repo),
            "listed under {:?}, not the cache folder's casing",
            info.source
        );
    }

    #[test]
    fn test_discover_hf_cache_models_filters_by_arch() {
        let tmp = TempDir::new().unwrap();
        let root = tmp.path();

        // ASR repo: a whisper gguf -> should be discovered.
        let repo = root.join("models--handy-computer--whisper-test");
        fs::create_dir_all(repo.join("snapshots").join("abc123")).unwrap();
        fs::create_dir_all(repo.join("refs")).unwrap();
        fs::write(repo.join("refs").join("main"), "abc123").unwrap();
        write_synthetic_gguf(
            &repo
                .join("snapshots")
                .join("abc123")
                .join("whisper-q8.gguf"),
            "whisper",
            &["en", "de"],
        );

        // Non-ASR (llama) gguf -> must be ignored.
        let repo2 = root.join("models--someone--llama-7b");
        fs::create_dir_all(repo2.join("snapshots").join("def456")).unwrap();
        fs::create_dir_all(repo2.join("refs")).unwrap();
        fs::write(repo2.join("refs").join("main"), "def456").unwrap();
        write_synthetic_gguf(
            &repo2.join("snapshots").join("def456").join("llama-q8.gguf"),
            "llama",
            &[],
        );

        let mut models = HashMap::new();
        ModelManager::discover_hf_cache_models_in(root, &mut models);

        let id = "handy-computer/whisper-test/whisper-q8.gguf";
        let m = models.get(id).expect("whisper gguf should be discovered");
        assert!(m.is_downloaded);
        assert!(
            matches!(&m.source, ModelSource::HuggingFace { repo_id, revision }
            if repo_id == "handy-computer/whisper-test" && revision == "abc123")
        );
        assert_eq!(
            m.supported_languages,
            vec!["en".to_string(), "de".to_string()]
        );
        assert!(
            !models.contains_key("someone/llama-7b/llama-q8.gguf"),
            "non-ASR gguf must be ignored"
        );
    }
}