Skip to content

armgit / kokon

Public Imported from GitHub
0

Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.

57.8 KB
Raw Blame
//! What the first-run wizard installs: the stable-diffusion.cpp build the app was verified
//! with, the official Qwen-Image 2.1 Turbo weights, and the VRAM presets that choose between them.
//!
//! Every file is pinned by URL, size and SHA-256 (from the Hugging Face / GitHub APIs,
//! 2026-10-08; engines and upscaler 2026-10-12). If a link moves, the wizard reports it and
//! asks the user to download the file by hand from `page` and to open an issue at [`ISSUES_URL`].

use std::path::{Path, PathBuf};

use serde::Serialize;

use crate::config::{GpuBackend, TextEncoderPlacement};

/// Where users report broken download links. Set before publishing the repository.
pub const ISSUES_URL: &str = "https://github.com/GabrieleLozupone/kokon/issues/new";

/// Folder under the stable-diffusion.cpp folder that holds the Qwen weights.
pub const MODEL_SUBDIR: &str = "models/qwen21";

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum FileKind {
    /// stable-diffusion.cpp binaries (a zip extracted into the folder).
    Engine,
    Model,
}

/// Release of the engine builds below. Written into [`ENGINE_MARKER`] after extraction, so an
/// engine of another release (files present, marker missing or different) is updated. A newer
/// release published in the engine manifest replaces these at runtime ([`engine_tag`]).
pub const ENGINE_TAG: &str = "kokon-1013-1814814";
/// File in an engine's folder naming the release it was extracted from.
pub const ENGINE_MARKER: &str = "kokon-engine.txt";

#[derive(Debug, Clone, Copy, Serialize)]
pub struct Download {
    pub id: &'static str,
    pub label: &'static str,
    pub kind: FileKind,
    pub url: &'static str,
    /// Tried in order when `url` fails for good (moved link, refused, changed file).
    pub fallback_urls: &'static [&'static str],
    /// Page where the file can be downloaded by hand when `url` stops working.
    pub page: &'static str,
    pub size: u64,
    pub sha256: &'static str,
    /// Destination relative to the stable-diffusion.cpp folder (for a zip: the archive path,
    /// extracted into its own folder and then deleted).
    pub dest: &'static str,
    /// Files a zip provides (relative to the stable-diffusion.cpp folder); their presence
    /// means it is installed.
    pub provides: &'static [&'static str],
    /// For an engine zip: the release its folder must be marked with ([`ENGINE_MARKER`]).
    pub engine_tag: Option<&'static str>,
}

/// `base` + a catalog path written with `/`, as native components. An absolute path (a model
/// downloaded into a folder of the user's, [`Download::at`]) is used as is.
pub fn join_rel(base: &Path, rel: &str) -> PathBuf {
    if Path::new(rel).is_absolute() {
        return PathBuf::from(rel);
    }
    rel.split('/').filter(|c| !c.is_empty()).fold(base.to_path_buf(), |p, c| p.join(c))
}

impl Download {
    pub fn is_zip(&self) -> bool {
        !self.provides.is_empty()
    }

    pub fn path(&self, sdcpp_dir: &Path) -> PathBuf {
        join_rel(sdcpp_dir, self.dest)
    }

    /// The file name it is saved under.
    pub fn file_name(&self) -> &'static str {
        self.dest.rsplit('/').next().unwrap_or(self.dest)
    }

    /// The same file, saved at `path` (anywhere) instead of the stable-diffusion.cpp folder.
    pub fn at(self, path: &Path) -> Download {
        Download { dest: Box::leak(path.to_string_lossy().into_owned().into_boxed_str()), ..self }
    }

    /// Every URL to try, in order.
    pub fn urls(&self) -> impl Iterator<Item = &'static str> {
        std::iter::once(self.url).chain(self.fallback_urls.iter().copied())
    }

    /// Installed: a zip's files exist (an engine's folder also carries its release marker), or
    /// the file exists with the expected size. The hash is checked after every download; a
    /// size match is enough for files already on disk.
    pub fn is_present(&self, sdcpp_dir: &Path) -> bool {
        if self.is_zip() {
            let files = self.provides.iter().all(|f| join_rel(sdcpp_dir, f).is_file());
            return files && self.engine_tag.is_none_or(|t| self.installed_tag(sdcpp_dir).as_deref() == Some(t));
        }
        std::fs::metadata(self.path(sdcpp_dir)).map(|m| m.is_file() && m.len() == self.size).unwrap_or(false)
    }

    /// The release an engine folder is marked with, if any.
    pub fn installed_tag(&self, sdcpp_dir: &Path) -> Option<String> {
        std::fs::read_to_string(zip_dir(self, sdcpp_dir).join(ENGINE_MARKER)).ok().map(|s| s.trim().to_string())
    }

    /// Marks an extracted engine with its release.
    pub fn write_tag(&self, sdcpp_dir: &Path) -> std::io::Result<()> {
        match self.engine_tag {
            Some(t) => std::fs::write(zip_dir(self, sdcpp_dir).join(ENGINE_MARKER), t),
            None => Ok(()),
        }
    }
}

/// Kokon's engine release: every engine is built from branch `kokon` of Kokon's
/// stable-diffusion.cpp fork (upstream plus the prompt enhancer's text generation and Kokon's
/// fixes) by `.github/workflows/kokon.yml`, with upstream's flags otherwise. CUDA builds use CUDA
/// graphs (ggml from Kokon's fork). Linux builds on Ubuntu 22.04 (smoke-tested on Ubuntu
/// 22.04/24.04, Debian 12, Fedora 40/42); macOS for 15.0 (upstream's Mac zip needs macOS 26).
/// Sizes and SHA-256 from GitHub's asset digests.
const KOKON_RELEASE: &str = "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/kokon-1013-1814814";
/// Upstream release the Windows CUDA runtime comes from (CUDA 12.8.1, the version the engines
/// are built with).
#[cfg(not(target_os = "linux"))]
const SDCPP_UPSTREAM_RELEASE: &str = "https://github.com/leejet/stable-diffusion.cpp/releases/tag/master-929-3f8527a";
/// Release the Linux CUDA runtime comes from (CUDA 12.8).
#[cfg(target_os = "linux")]
const KOKON_LINUX_RELEASE: &str = "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/kokon-linux-1d0a58a";

/// CUDA 12 build; it runs on GTX 10xx to RTX 50xx.
#[cfg(not(target_os = "linux"))]
pub const ENGINE_CUDA: Download = Download {
    id: "engine_cuda",
    label: "stable-diffusion.cpp (CUDA 12)",
    kind: FileKind::Engine,
    url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-1013-1814814/sd-kokon-1814814-bin-win-cuda12-x64.zip",
    fallback_urls: &[],
    page: KOKON_RELEASE,
    size: WIN_CUDA_SIZE,
    sha256: WIN_CUDA_SHA256,
    dest: "sd-kokon-1814814-bin-win-cuda12-x64.zip",
    provides: &["sd-server.exe", "stable-diffusion.dll", "ggml-cuda.dll"],
    engine_tag: Some(ENGINE_TAG),
};

/// CUDA 12.8.1, unchanged since the upstream release: no marker, never downloaded again.
#[cfg(not(target_os = "linux"))]
pub const CUDA_RUNTIME: Download = Download {
    id: "cuda_runtime",
    label: "CUDA 12 runtime (cuBLAS)",
    kind: FileKind::Engine,
    url: "https://github.com/leejet/stable-diffusion.cpp/releases/download/master-929-3f8527a/cudart-sd-bin-win-cu12-x64.zip",
    fallback_urls: &[],
    page: SDCPP_UPSTREAM_RELEASE,
    size: 563_452_046,
    sha256: "fe20366827d357c00797eebb58244dddab7fd9a348d70090c3871004c320f38d",
    dest: "cudart-sd-bin-win-cu12-x64.zip",
    provides: &["cudart64_12.dll", "cublas64_12.dll", "cublasLt64_12.dll"],
    engine_tag: None,
};

/// Same commit, Vulkan build: AMD, Intel and NVIDIA cards through the GPU driver's Vulkan
/// runtime (nothing else to install). Kept in its own folder so it can sit next to the
/// CUDA build.
#[cfg(not(target_os = "linux"))]
pub const ENGINE_VULKAN: Download = Download {
    id: "engine_vulkan",
    label: "stable-diffusion.cpp (Vulkan)",
    kind: FileKind::Engine,
    url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-1013-1814814/sd-kokon-1814814-bin-win-vulkan-x64.zip",
    fallback_urls: &[],
    page: KOKON_RELEASE,
    size: WIN_VULKAN_SIZE,
    sha256: WIN_VULKAN_SHA256,
    dest: "engine-vulkan/sd-kokon-1814814-bin-win-vulkan-x64.zip",
    provides: &["engine-vulkan/sd-server.exe", "engine-vulkan/stable-diffusion.dll", "engine-vulkan/ggml-vulkan.dll"],
    engine_tag: Some(ENGINE_TAG),
};

/// Linux builds (upstream's Linux zips need glibc 2.38 and have no CUDA variant). The libraries
/// find each other and the CUDA runtime next to them (RPATH `$ORIGIN`).
#[cfg(target_os = "linux")]
pub const ENGINE_CUDA: Download = Download {
    id: "engine_cuda",
    label: "stable-diffusion.cpp (CUDA 12)",
    kind: FileKind::Engine,
    url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-1013-1814814/sd-kokon-1814814-bin-Linux-Ubuntu-22.04-x86_64-cuda12.zip",
    fallback_urls: &[],
    page: KOKON_RELEASE,
    size: LINUX_CUDA_SIZE,
    sha256: LINUX_CUDA_SHA256,
    dest: "sd-kokon-1814814-bin-Linux-Ubuntu-22.04-x86_64-cuda12.zip",
    provides: &["sd-server", "libstable-diffusion.so", "libggml-cuda.so"],
    engine_tag: Some(ENGINE_TAG),
};

/// CUDA 12.8 runtime libraries (NVIDIA redistributables), next to the CUDA engine. Unchanged
/// since kokon-linux-1d0a58a: no marker, never downloaded again.
#[cfg(target_os = "linux")]
pub const CUDA_RUNTIME: Download = Download {
    id: "cuda_runtime",
    label: "CUDA 12 runtime (cuBLAS)",
    kind: FileKind::Engine,
    url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-linux-1d0a58a/cudart-sd-bin-linux-cu12-x64.zip",
    fallback_urls: &[],
    page: KOKON_LINUX_RELEASE,
    size: 593_744_419,
    sha256: "5b05f377ed203691ad22b471697efccd5c304ee0c6cc6f06c1acabcaa121f097",
    dest: "cudart-sd-bin-linux-cu12-x64.zip",
    provides: &["libcudart.so.12", "libcublas.so.12", "libcublasLt.so.12"],
    engine_tag: None,
};

#[cfg(target_os = "linux")]
pub const ENGINE_VULKAN: Download = Download {
    id: "engine_vulkan",
    label: "stable-diffusion.cpp (Vulkan)",
    kind: FileKind::Engine,
    url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-1013-1814814/sd-kokon-1814814-bin-Linux-Ubuntu-22.04-x86_64-vulkan.zip",
    fallback_urls: &[],
    page: KOKON_RELEASE,
    size: LINUX_VULKAN_SIZE,
    sha256: LINUX_VULKAN_SHA256,
    dest: "engine-vulkan/sd-kokon-1814814-bin-Linux-Ubuntu-22.04-x86_64-vulkan.zip",
    provides: &["engine-vulkan/sd-server", "engine-vulkan/libstable-diffusion.so", "engine-vulkan/libggml-vulkan.so"],
    engine_tag: Some(ENGINE_TAG),
};

/// macOS 15+, universal binary with the Metal shaders embedded. Ad-hoc signed; downloaded by the
/// app (not a browser) it gets no quarantine flag.
pub const ENGINE_METAL: Download = Download {
    id: "engine_metal",
    label: "stable-diffusion.cpp (Metal)",
    kind: FileKind::Engine,
    url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-1013-1814814/sd-kokon-1814814-bin-Darwin-macOS-15.0-universal.zip",
    fallback_urls: &[],
    page: KOKON_RELEASE,
    size: MACOS_METAL_SIZE,
    sha256: MACOS_METAL_SHA256,
    dest: "engine-metal/sd-kokon-1814814-bin-Darwin-macOS-15.0-universal.zip",
    provides: &["engine-metal/sd-server", "engine-metal/libstable-diffusion.dylib"],
    engine_tag: Some(ENGINE_TAG),
};

// From the kokon-1013-1814814 release (GitHub asset digests, run 39850202406).
#[cfg(not(target_os = "linux"))]
const WIN_CUDA_SIZE: u64 = 343_854_810;
#[cfg(not(target_os = "linux"))]
const WIN_CUDA_SHA256: &str = "5ef1a5306c280e871991893a41d0f8af853a3394b9a639d554f9c0734ee0ad35";
#[cfg(not(target_os = "linux"))]
const WIN_VULKAN_SIZE: u64 = 29_559_595;
#[cfg(not(target_os = "linux"))]
const WIN_VULKAN_SHA256: &str = "29427c56a00f35d8f61180a6ff352563dd3a726b7d0b9b6f8732e87f876511eb";
#[cfg(target_os = "linux")]
const LINUX_CUDA_SIZE: u64 = 352_747_528;
#[cfg(target_os = "linux")]
const LINUX_CUDA_SHA256: &str = "a7a712f86f5d605883d2496dacf283009d00d2d5880b4b8b1cb8cf9e595bb62f";
#[cfg(target_os = "linux")]
const LINUX_VULKAN_SIZE: u64 = 38_181_852;
#[cfg(target_os = "linux")]
const LINUX_VULKAN_SHA256: &str = "9c085070da4ea07356f92bddfb5882133de40ef36de30d8e8d6ddde064f33890";
const MACOS_METAL_SIZE: u64 = 36_981_824;
const MACOS_METAL_SHA256: &str = "0cba039a1ce063daa977e3ea927dab0a0bf1414002e74e80902afdf0ef6bb274";

/// The engine files of a backend, in download order: the engine manifest's release when one
/// newer than the built-in pins was applied ([`apply_engine_release`]), else the pins.
pub fn engine_downloads(backend: GpuBackend) -> Vec<Download> {
    let o = *ENGINE_OVERRIDE.read().unwrap();
    let (cuda, vulkan, metal) = o.map(|r| (r.cuda, r.vulkan, r.metal)).unwrap_or((ENGINE_CUDA, ENGINE_VULKAN, ENGINE_METAL));
    match backend {
        GpuBackend::Cuda => vec![cuda, CUDA_RUNTIME],
        GpuBackend::Vulkan => vec![vulkan],
        GpuBackend::Metal => vec![metal],
    }
}

/// The engine release the app wants installed: the manifest's, or [`ENGINE_TAG`].
pub fn engine_tag() -> &'static str {
    ENGINE_OVERRIDE.read().unwrap().map(|r| r.tag).unwrap_or(ENGINE_TAG)
}

#[derive(Debug, Clone, Copy)]
struct EngineRelease {
    tag: &'static str,
    cuda: Download,
    vulkan: Download,
    metal: Download,
}

static ENGINE_OVERRIDE: std::sync::RwLock<Option<EngineRelease>> = std::sync::RwLock::new(None);

/// Tests that change or depend on the engine override take this lock.
#[cfg(test)]
pub(crate) static ENGINE_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

/// One engine build in the manifest.
#[derive(Debug, Clone, PartialEq, serde::Deserialize, Serialize)]
pub struct ManifestAsset {
    pub url: String,
    pub size: u64,
    pub sha256: String,
}

/// A release of Kokon's engines (`kokon-<n>-<commit>` in Kokon's stable-diffusion.cpp fork).
#[derive(Debug, Clone, PartialEq, serde::Deserialize, Serialize)]
pub struct KokonEngines {
    pub tag: String,
    /// Oldest app version the release works with (older apps ignore it).
    pub min_app: String,
    pub win_cuda: ManifestAsset,
    pub win_vulkan: ManifestAsset,
    pub linux_cuda: ManifestAsset,
    pub linux_vulkan: ManifestAsset,
    pub macos: ManifestAsset,
}

/// `engine.json` in the Kokon repository: the newest engine release tested with Kokon. Lets a
/// tested engine reach users without an app release. Apps from 0.10 read only the `kokon` entry;
/// the file's other keys (an upstream release) serve apps up to 0.9.4, which ignore this one.
#[derive(Debug, Clone, Default, PartialEq, serde::Deserialize, Serialize)]
pub struct EngineManifest {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub kokon: Option<KokonEngines>,
}

/// Build number of a Kokon engine release tag (`kokon-1013-1814814` -> 1013).
pub fn release_number(tag: &str) -> Option<u32> {
    tag.strip_prefix("kokon-")?.split('-').next()?.parse().ok()
}

fn version_tuple(v: &str) -> Option<(u32, u32, u32)> {
    let mut it = v.trim().trim_start_matches('v').split(['.', '-']).map(|p| p.parse::<u32>().ok());
    Some((it.next()??, it.next()??, it.next().flatten().unwrap_or(0)))
}

/// Uses the manifest's Kokon release as the engine release when it is valid, meant for
/// `app_version`, and newer than the built-in pins (an app update that pins a newer engine is
/// never downgraded by an old manifest). Returns whether it is now in use.
pub fn apply_engine_release(m: &EngineManifest, app_version: &str) -> Result<bool, String> {
    let Some(k) = &m.kokon else {
        *ENGINE_OVERRIDE.write().unwrap() = None;
        return Ok(false);
    };
    let (Some(n), Some(builtin)) = (release_number(&k.tag), release_number(ENGINE_TAG)) else {
        return Err(format!("not a Kokon engine release tag: {}", k.tag));
    };
    if version_tuple(app_version) < version_tuple(&k.min_app) || version_tuple(&k.min_app).is_none() {
        return Ok(false);
    }
    if n <= builtin {
        *ENGINE_OVERRIDE.write().unwrap() = None;
        return Ok(false);
    }
    let leak = |s: String| -> &'static str { Box::leak(s.into_boxed_str()) };
    let tag = leak(k.tag.clone());
    let commit = k.tag.rsplit('-').next().unwrap_or_default();
    let release = format!("https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/{}/", k.tag);
    let page = leak(format!("https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/{}", k.tag));
    let prefix = format!("sd-kokon-{commit}-bin-");
    let build = |a: &ManifestAsset, base: Download, folder: &str| -> Result<Download, String> {
        let file = a
            .url
            .strip_prefix(&release)
            .filter(|f| f.starts_with(&prefix) && f.ends_with(".zip") && !f.contains(['/', '\\']))
            .ok_or_else(|| format!("unexpected engine URL: {}", a.url))?;
        if a.sha256.len() != 64 || !a.sha256.chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()) || a.size == 0 {
            return Err(format!("bad size or SHA-256 for {}", a.url));
        }
        Ok(Download { url: leak(a.url.clone()), page, size: a.size, sha256: leak(a.sha256.clone()), dest: leak(format!("{folder}{file}")), engine_tag: Some(tag), ..base })
    };
    // Every build is checked, whatever the platform: a manifest is good or ignored as a whole.
    let win = (build(&k.win_cuda, ENGINE_CUDA, "")?, build(&k.win_vulkan, ENGINE_VULKAN, "engine-vulkan/")?);
    let linux = (build(&k.linux_cuda, ENGINE_CUDA, "")?, build(&k.linux_vulkan, ENGINE_VULKAN, "engine-vulkan/")?);
    let metal = build(&k.macos, ENGINE_METAL, "engine-metal/")?;
    let (cuda, vulkan) = if cfg!(target_os = "linux") { linux } else { win };
    *ENGINE_OVERRIDE.write().unwrap() = Some(EngineRelease { tag, cuda, vulkan, metal });
    Ok(true)
}

const QWEN_TE: &str = "https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct-GGUF/tree/main";

/// The image model: Qwen's official 8-step distilled Qwen-Image 2.1 (Qwen/Qwen-Image-2.1-Turbo,
/// Qwen Research License like the base model), as unsloth's GGUF. Same-seed A/B on an RTX 5070 Ti
/// (2026-10-10): ~2x faster than the 20-step base model at equal quality, faithful edits. The
/// base Qwen-Image 2.1 weights were dropped on 2026-10-09. Every preset uses this 4-bit file
/// (0.11.1): a tie with the Q4_K below on a same-seed vote (2026-10-25, RTX 5070 Ti, ~6 % slower
/// per job there), from a widely used source, and the file the Mac engine is checked against.
pub const TURBO_Q4_K_M: Download = Download {
    id: "turbo_q4_k_m",
    label: "Qwen-Image 2.1 Turbo Q4_K_M",
    kind: FileKind::Model,
    url: "https://huggingface.co/unsloth/Qwen-Image-2.1-Turbo-GGUF/resolve/main/qwen-image-2.1-turbo-Q4_K_M.gguf",
    fallback_urls: &[],
    page: "https://huggingface.co/unsloth/Qwen-Image-2.1-Turbo-GGUF",
    size: 4_199_565_120,
    sha256: "8940e8b522af886e0c0f5afddf720e82dd223cb9a43580b5f61c4d740452ac20",
    dest: "models/qwen21/qwen-image-2.1-turbo-Q4_K_M.gguf",
    provides: &[],
    engine_tag: None,
};

/// The image model installed up to 0.11.0 (DogukanUrker's GGUF conversion, made with
/// stable-diffusion.cpp). Kept while its owner has not chosen the Q4_K_M ([`official_dit`]);
/// deleted once they have ([`unused_old_dit`]).
pub const TURBO_Q4_K: Download = Download {
    id: "turbo_q4_k",
    label: "Qwen-Image 2.1 Turbo Q4_K",
    kind: FileKind::Model,
    url: "https://huggingface.co/DogukanUrker/Qwen-Image-2.1-Turbo-GGUF/resolve/main/qwen-image-2.1-turbo-Q4_K.gguf",
    fallback_urls: &[],
    page: "https://huggingface.co/DogukanUrker/Qwen-Image-2.1-Turbo-GGUF",
    size: 4_050_916_384,
    sha256: "f8d5611b495848b632f8ae14dc7da6525fe2796eb80998f8dee5e04d0a2f69eb",
    dest: "models/qwen21/qwen-image-2.1-turbo-Q4_K.gguf",
    provides: &[],
    engine_tag: None,
};

/// The image model the official files of preset `p` use in `sdcpp_dir`: the preset's once it is
/// there, else the Q4_K of an earlier install (its owner has not accepted the new one), else the
/// preset's to download. Like [`official_vae`], nothing here downloads it uninvited.
pub fn official_dit(p: &Preset, sdcpp_dir: &Path) -> Download {
    if p.diffusion.id == TURBO_Q4_K_M.id && !TURBO_Q4_K_M.is_present(sdcpp_dir) && TURBO_Q4_K.is_present(sdcpp_dir) { TURBO_Q4_K } else { p.diffusion }
}

/// The Q4_K in the app's own folder once the Q4_K_M is there and no profile uses it any more,
/// so it can be deleted.
pub fn unused_old_dit(cfg: &crate::config::AppConfig) -> Option<PathBuf> {
    let old = TURBO_Q4_K.path(&cfg.sdcpp_dir);
    let used = cfg.profiles.iter().any(|p| p.diffusion_model == old);
    (TURBO_Q4_K_M.is_present(&cfg.sdcpp_dir) && !used && old.is_file()).then_some(old)
}

/// The VAE of new installs (0.9.3): Qwen's VAE with the decoder fine-tuned by madebyollin
/// (author of TAESD) to remove the 2-px checkerboard of the original (#21). Same tensors and
/// shapes, Qwen Research License like the model. Same-seed A/B on 5 cases at 1536² (2026-10-16):
/// checkerboard 10–48% → 1–4% (coherent 2-px amplitude, noise ≈ 2–3%), slightly more fine
/// detail, colours within 1/255, same speed.
pub const VAE: Download = Download {
    id: "vae",
    label: "Qwen-Image 2.1 VAE (texture fix)",
    kind: FileKind::Model,
    url: "https://huggingface.co/madebyollin/texture-fix-vae-for-qwen-image-2.1/resolve/main/texture_fix_vae_for_qwen_image_2.1_bf16.safetensors",
    fallback_urls: &[],
    page: "https://huggingface.co/madebyollin/texture-fix-vae-for-qwen-image-2.1",
    size: 675_509_688,
    sha256: "36f56608b02077a50a08ea3dbcdb88351298ceba49948f41f9f87186378e6908",
    dest: "models/qwen21/texture_fix_vae_for_qwen_image_2.1_bf16.safetensors",
    provides: &[],
    engine_tag: None,
};

/// Qwen's original VAE, installed up to 0.9.2. Kept while its owner has not chosen the texture
/// fix ([`official_vae`]); deleted once they have ([`unused_original_vae`]).
pub const VAE_ORIGINAL: Download = Download {
    id: "vae_original",
    label: "Qwen-Image 2.1 VAE",
    kind: FileKind::Model,
    url: "https://huggingface.co/Comfy-Org/Qwen-Image-2.1/resolve/main/vae/qwen_image_2.1_vae_bf16.safetensors",
    fallback_urls: &[],
    page: "https://huggingface.co/Comfy-Org/Qwen-Image-2.1/tree/main/vae",
    size: 675_509_688,
    sha256: "bb21f7473051e1ac368515dd3f2e15cd44d7a11748ee8823e1ddca3e4876b7c9",
    dest: "models/qwen21/qwen_image_2.1_vae_bf16.safetensors",
    provides: &[],
    engine_tag: None,
};

/// The VAE the official files use in `sdcpp_dir`: the texture fix once it is there, else the
/// original of an earlier install (its owner has not accepted the new one), else the texture
/// fix to download. Updating is the user's choice, so nothing here downloads it uninvited.
pub fn official_vae(sdcpp_dir: &Path) -> Download {
    if !VAE.is_present(sdcpp_dir) && VAE_ORIGINAL.is_present(sdcpp_dir) { VAE_ORIGINAL } else { VAE }
}

/// The original VAE in the app's own folder once the texture fix replaced it: no profile
/// uses it any more, so it can be deleted.
pub fn unused_original_vae(cfg: &crate::config::AppConfig) -> Option<PathBuf> {
    let old = VAE_ORIGINAL.path(&cfg.sdcpp_dir);
    let used = cfg.profiles.iter().any(|p| p.vae == old);
    (VAE.is_present(&cfg.sdcpp_dir) && !used && old.is_file()).then_some(old)
}

/// What the image-model update (0.11.1) offers for the active model.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum DitUpdate {
    /// The official files still use the Q4_K: switch to the Q4_K_M and delete the Q4_K.
    Official,
    /// The user's own image model is that same Q4_K (any name, any folder): a suggestion to use
    /// the Q4_K_M from the app's folder instead. Their file is never touched.
    Own,
}

/// [`DitUpdate`] for the active model; None when it already uses the Q4_K_M or the user chose
/// another file (their choice: no offer).
pub fn dit_update(cfg: &crate::config::AppConfig) -> Option<DitUpdate> {
    dit_update_with(cfg, crate::modelfile::is_old_turbo_q4k)
}

/// [`dit_update`], `is_old` telling whether a file of the user's is the Q4_K.
fn dit_update_with(cfg: &crate::config::AppConfig, is_old: impl Fn(&Path) -> bool) -> Option<DitUpdate> {
    let p = cfg.profile();
    if p.is_official() {
        (p.diffusion_model == TURBO_Q4_K.path(&cfg.sdcpp_dir)).then_some(DitUpdate::Official)
    } else {
        is_old(&p.diffusion_model).then_some(DitUpdate::Own)
    }
}

/// Text encoder from Qwen's own GGUF repository (the one sd.cpp's docs point to).
pub const TEXT_ENCODER_Q4_K_M: Download = Download {
    id: "text_encoder_q4_k_m",
    label: "Qwen3-VL 8B text encoder Q4_K_M",
    kind: FileKind::Model,
    url: "https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct-GGUF/resolve/main/Qwen3VL-8B-Instruct-Q4_K_M.gguf",
    fallback_urls: &[],
    page: QWEN_TE,
    size: 5_027_784_800,
    sha256: "67d1659bfe71b89d50b45a4ad1a9e5b997e5bb16ce5da66a6a6167abd569e9e2",
    dest: "models/qwen21/Qwen3VL-8B-Instruct-Q4_K_M.gguf",
    provides: &[],
    engine_tag: None,
};

pub const TEXT_ENCODER_Q8_0: Download = Download {
    id: "text_encoder_q8_0",
    label: "Qwen3-VL 8B text encoder Q8_0",
    kind: FileKind::Model,
    url: "https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct-GGUF/resolve/main/Qwen3VL-8B-Instruct-Q8_0.gguf",
    fallback_urls: &[],
    page: QWEN_TE,
    size: 8_709_519_456,
    sha256: "0d264b3941185d00a74f75c4245521dae088ff1efc90ab8d1754e83f5844adb0",
    dest: "models/qwen21/Qwen3VL-8B-Instruct-Q8_0.gguf",
    provides: &[],
    engine_tag: None,
};

/// Vision projector: lets the text encoder see reference images (needed for editing).
pub const VISION_PROJECTOR: Download = Download {
    id: "vision_projector",
    label: "Qwen3-VL vision projector",
    kind: FileKind::Model,
    url: "https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct-GGUF/resolve/main/mmproj-Qwen3VL-8B-Instruct-F16.gguf",
    fallback_urls: &[],
    page: QWEN_TE,
    size: 1_159_029_824,
    sha256: "ca524100ebf825c9a870db1c580d03879e0da0ab2541697e2458e64891cf9d38",
    dest: "models/qwen21/mmproj-Qwen3VL-8B-Instruct-F16.gguf",
    provides: &[],
    engine_tag: None,
};

/// Name sd-server knows the upscaler by (its file stem in `--hires-upscalers-dir`).
pub const UPSCALER_NAME: &str = "4xNomos2_hq_mosr";
/// Folder of the upscaler, relative to the stable-diffusion.cpp folder.
pub const UPSCALERS_SUBDIR: &str = "models/upscalers";

/// 4xNomos2_hq_mosr by Philip Hofmann (CC BY 4.0), a MoSR model: enlarges results and runs
/// Upscale. Replaced the ESRGAN models on 2026-10-12: more natural skin, hair and text, and
/// ~8x faster than UltraSharp on an RTX 5070 Ti. Bundled with the app (copied into place at
/// start, see `installer::install_bundled`); downloaded from our mirror, then the author's
/// release, only when that copy is missing.
pub const UPSCALER: Download = Download {
    id: "upscaler",
    label: "4xNomos2 MoSR upscaler",
    kind: FileKind::Model,
    url: "https://github.com/GabrieleLozupone/kokon/releases/download/models-1/4xNomos2_hq_mosr.pth",
    fallback_urls: &["https://github.com/Phhofm/models/releases/download/4xNomos2_hq_mosr/4xNomos2_hq_mosr.pth"],
    page: "https://github.com/Phhofm/models/releases/tag/4xNomos2_hq_mosr",
    size: 17_213_494,
    sha256: "c60dbfc7e6f7d27e03517d1bec3f3cbd16e8cd4288eefd1358952f73f8497ddc",
    dest: "models/upscalers/4xNomos2_hq_mosr.pth",
    provides: &[],
    engine_tag: None,
};

/// Adobe TrustMark, variant P (MIT code and weights): the invisible AI watermark every result
/// gets (watermark.rs; AI Act Art. 50(2), with the XMP of provenance.rs). Bundled with the app
/// like the upscaler (copied into place at start) so marking never waits for a download; Adobe's
/// model host is the fallback. Pinned by size and SHA-256 (downloaded 2026-11-04).
pub const TRUSTMARK_P_ENCODER: Download = Download {
    id: "trustmark_p_encoder",
    label: "TrustMark P encoder (AI watermark)",
    kind: FileKind::Model,
    url: "https://cai-watermark.adobe.net/watermarking/trustmark-models/encoder_P.onnx",
    fallback_urls: &[],
    page: "https://github.com/adobe/trustmark",
    size: 17_312_208,
    sha256: "053441c9c9f05fc158ccba71c610d9d58fcd2c82d1912bf0ffcee988cf2f74c8",
    dest: "models/watermark/encoder_P.onnx",
    provides: &[],
    engine_tag: None,
};

/// The TrustMark P decoder: reads the watermark (skip an image already marked, "Check an image").
pub const TRUSTMARK_P_DECODER: Download = Download {
    id: "trustmark_p_decoder",
    label: "TrustMark P decoder (AI watermark check)",
    kind: FileKind::Model,
    url: "https://cai-watermark.adobe.net/watermarking/trustmark-models/decoder_P.onnx",
    fallback_urls: &[],
    page: "https://github.com/adobe/trustmark",
    size: 47_400_467,
    sha256: "be6d7c33f8a7b376f179e75f3f7c58ff816a9ac7bb6d37fd0a729a635f624c35",
    dest: "models/watermark/decoder_P.onnx",
    provides: &[],
    engine_tag: None,
};

const ESRGAN_MODELS: &str = "https://huggingface.co/uwg/upscaler/tree/main/ESRGAN";

/// 4x_NMKD-Superscale-SP_178000_G by Nmkd (ESRGAN, WTFPL): the default upscaler since
/// 2026-10-12. Sharper and more natural than UltraSharp on most renders; can draw a faint grid
/// on JPEG blocks and dark areas (`AppConfig::upscale_blend` tones it down).
pub const SUPERSCALE: Download = Download {
    id: "upscaler_superscale",
    label: "Superscale-SP upscaler",
    kind: FileKind::Model,
    url: "https://huggingface.co/uwg/upscaler/resolve/main/ESRGAN/4x_NMKD-Superscale-SP_178000_G.pth",
    fallback_urls: &[],
    page: ESRGAN_MODELS,
    size: 66_958_607,
    sha256: "1d1b0078fe71446e0469d8d4df59e96baa80d83cda600d68237d655830821bcc",
    dest: "models/upscalers/4x_NMKD-Superscale-SP_178000_G.pth",
    provides: &[],
    engine_tag: None,
};

/// 4x-UltraSharp by Kim2091 (ESRGAN, CC BY-NC-SA 4.0: non-commercial): the default before
/// 2026-10-12, now an optional download (very clean, but smooths skin into an AI look and can
/// invent lines).
pub const ULTRASHARP: Download = Download {
    id: "upscaler_ultrasharp",
    label: "UltraSharp upscaler",
    kind: FileKind::Model,
    url: "https://huggingface.co/uwg/upscaler/resolve/main/ESRGAN/4x-UltraSharp.pth",
    fallback_urls: &[],
    page: ESRGAN_MODELS,
    size: 66_961_958,
    sha256: "a5812231fc936b42af08a5edba784195495d303d5b3248c24489ef0c4021fe01",
    dest: "models/upscalers/4x-UltraSharp.pth",
    provides: &[],
    engine_tag: None,
};

/// Every upscaler model Kokon can install, in the order Settings lists them.
pub const UPSCALER_DOWNLOADS: &[Download] = &[SUPERSCALE, UPSCALER, ULTRASHARP];

/// The download of the upscaler named `name` (file stem).
pub fn upscaler_download(name: &str) -> Option<Download> {
    UPSCALER_DOWNLOADS.iter().copied().find(|d| d.dest.rsplit('/').next().and_then(|f| f.rsplit_once('.')).is_some_and(|(stem, _)| stem == name))
}

/// Upscaler files Settings offers to delete when they are not the selected model (in the
/// app's own folder only).
pub const LEGACY_UPSCALERS: &[&str] = &["models/upscalers/4x-UltraSharp.pth", "models/upscalers/4x_NMKD-Superscale-SP_178000_G.pth"];

/// Hardware presets: which weights to download and how to run them, by VRAM.
#[derive(Debug, Clone, Copy, Serialize)]
pub struct Preset {
    pub id: &'static str,
    pub label: &'static str,
    /// Smallest reported VRAM (MiB) this preset is recommended for.
    pub min_vram_mib: u64,
    /// Name on a Mac: the unified memory sizes it is chosen for (through
    /// `planner::unified_memory_planning_mib`), since "12 GB" would read as RAM there.
    pub unified_label: &'static str,
    /// `summary` for a Mac (no "system RAM": it is the same memory).
    pub unified_summary: &'static str,
    /// The image model (a Turbo quantization).
    pub diffusion: Download,
    pub text_encoder: Download,
    pub text_encoder_placement: TextEncoderPlacement,
    /// Free VRAM sd-server leaves out of its budget (`--max-vram -N`). CUDA loads a kernel's code
    /// on first use, outside that budget: on an emulated 8 GB card 1 GiB left too little and the
    /// first job after every start crashed ("shared object initialization failed"); 1.5 GiB ran
    /// clean with the prompt enhancer still fully on the GPU (2026-10-19).
    pub vram_reserve_gib: f32,
    /// Measured on real hardware of this class (otherwise only derived).
    pub verified: bool,
    pub summary: &'static str,
}

/// Ordered by VRAM. Cards report a bit less than their nominal size (16 GB → 16303 MiB),
/// so thresholds sit between classes.
pub const PRESETS: &[Preset] = &[
    // Beta (0.9.3): the 12 GB files, with the planner's smaller working sizes. Emulated 8 GB on a
    // 5070 Ti ran every mode without running out of memory (2026-10-14); users report it works
    // on an RTX 3060 Ti and an RTX 5050 Laptop (1–2 min per edit). Not offered on Macs, whose
    // 16 GB models plan below this and stay on the 12 GB preset's Mac name.
    Preset {
        id: "8gb",
        label: "8 GB (beta)",
        unified_label: "",
        unified_summary: "",
        min_vram_mib: 0,
        diffusion: TURBO_Q4_K_M,
        text_encoder: TEXT_ENCODER_Q4_K_M,
        text_encoder_placement: TextEncoderPlacement::Ram,
        vram_reserve_gib: 1.5,
        verified: false,
        summary: "4-bit model; text encoder in system RAM; images of about 1 megapixel",
    },
    Preset {
        id: "12gb",
        label: "12 GB",
        unified_label: "16–24 GB Mac",
        unified_summary: "4-bit image model and text encoder; images of about 1–1.5 megapixels",
        min_vram_mib: 10 * 1024,
        diffusion: TURBO_Q4_K_M,
        text_encoder: TEXT_ENCODER_Q4_K_M,
        text_encoder_placement: TextEncoderPlacement::Ram,
        vram_reserve_gib: 1.0,
        verified: true,
        summary: "4-bit model; text encoder in system RAM; smaller working sizes",
    },
    Preset {
        id: "16gb",
        label: "16 GB",
        unified_label: "32–36 GB Mac",
        unified_summary: "4-bit image model and text encoder; native 2K for Quality",
        min_vram_mib: 14 * 1024,
        diffusion: TURBO_Q4_K_M,
        text_encoder: TEXT_ENCODER_Q4_K_M,
        text_encoder_placement: TextEncoderPlacement::Ram,
        vram_reserve_gib: 1.0,
        verified: true,
        summary: "4-bit model; text encoder in system RAM; native 2K for Quality",
    },
    Preset {
        id: "24gb",
        label: "24 GB",
        unified_label: "48 GB Mac",
        unified_summary: "4-bit image model and text encoder; larger edits fit",
        min_vram_mib: 20 * 1024,
        diffusion: TURBO_Q4_K_M,
        text_encoder: TEXT_ENCODER_Q4_K_M,
        text_encoder_placement: TextEncoderPlacement::Ram,
        vram_reserve_gib: 1.0,
        verified: false,
        summary: "4-bit model; text encoder in system RAM; larger edits fit",
    },
    Preset {
        id: "32gb",
        label: "32 GB+",
        unified_label: "64 GB+ Mac",
        unified_summary: "4-bit image model and 8-bit text encoder",
        min_vram_mib: 28 * 1024,
        diffusion: TURBO_Q4_K_M,
        text_encoder: TEXT_ENCODER_Q8_0,
        text_encoder_placement: TextEncoderPlacement::Ram,
        vram_reserve_gib: 1.0,
        verified: false,
        summary: "4-bit model and 8-bit text encoder",
    },
];

pub const DEFAULT_PRESET: &str = "16gb";

pub fn preset(id: &str) -> Option<&'static Preset> {
    PRESETS.iter().find(|p| p.id == id)
}

impl Preset {
    /// Offered on this kind of memory: presets without a Mac name are for graphics cards only.
    pub fn offered(&self, unified: bool) -> bool {
        !unified || !self.unified_label.is_empty()
    }
}

/// The preset for a card with `vram_mib` (None: unknown GPU → the 16 GB default); `unified`
/// for a Mac's planning memory. Below every threshold, the smallest preset offered.
pub fn recommended_preset(vram_mib: Option<u64>, unified: bool) -> &'static Preset {
    let offered = || PRESETS.iter().filter(move |p| p.offered(unified));
    match vram_mib {
        Some(v) => offered().rev().find(|p| v >= p.min_vram_mib).or_else(|| offered().next()).unwrap(),
        None => preset(DEFAULT_PRESET).unwrap(),
    }
}

/// Everything a preset needs on `backend` in `sdcpp_dir`, in download order (small, essential
/// files first). Superscale-SP is the default upscaler on PCs only (on Metal it takes minutes
/// per image).
pub fn downloads_for(p: &Preset, backend: GpuBackend, sdcpp_dir: &Path) -> Vec<Download> {
    let mut v = engine_downloads(backend);
    v.push(UPSCALER);
    v.extend([TRUSTMARK_P_ENCODER, TRUSTMARK_P_DECODER]);
    if backend != GpuBackend::Metal {
        v.push(SUPERSCALE);
    }
    v.extend([official_vae(sdcpp_dir), VISION_PROJECTOR, p.text_encoder, official_dit(p, sdcpp_dir)]);
    v
}

/// The model files a profile can download: official files it points to that are not there
/// (a piece the user chose to download, or an official file deleted from their folder), each
/// saved where the profile expects it. Existing files are never replaced, whatever their name.
pub fn profile_model_downloads(profile: &crate::config::ModelProfile) -> Vec<Download> {
    let official = [TURBO_Q4_K_M, TURBO_Q4_K, VAE, VAE_ORIGINAL, TEXT_ENCODER_Q4_K_M, TEXT_ENCODER_Q8_0, VISION_PROJECTOR];
    profile
        .files()
        .into_iter()
        .filter(|(_, p, _)| !p.exists())
        .filter_map(|(_, p, _)| {
            let name = p.file_name()?.to_string_lossy().to_string();
            official.iter().find(|d| d.file_name().eq_ignore_ascii_case(&name)).map(|d| d.at(p))
        })
        .collect()
}

/// Everything a user profile needs on `backend`: the engine, the upscalers, then the model
/// files of [`profile_model_downloads`]. The official profile uses [`downloads_for`].
pub fn downloads_for_profile(profile: &crate::config::ModelProfile, backend: GpuBackend) -> Vec<Download> {
    let mut v = engine_downloads(backend);
    v.push(UPSCALER);
    v.extend([TRUSTMARK_P_ENCODER, TRUSTMARK_P_DECODER]);
    if backend != GpuBackend::Metal {
        v.push(SUPERSCALE);
    }
    v.extend(profile_model_downloads(profile));
    v
}

/// Folder a zip is extracted into: the folder of its `dest`.
pub fn zip_dir(d: &Download, sdcpp_dir: &Path) -> PathBuf {
    d.path(sdcpp_dir).parent().map(Path::to_path_buf).unwrap_or_else(|| sdcpp_dir.to_path_buf())
}

/// Message shown when a download keeps failing (moved link, changed file, server down).
pub fn manual_download_hint(d: &Download, sdcpp_dir: &Path) -> String {
    let target = if d.is_zip() { format!("extract it into {}", zip_dir(d, sdcpp_dir).display()) } else { format!("save it as {}", d.path(sdcpp_dir).display()) };
    format!(
        "Download {} by hand from {} and {target}, then press Check again. Please also open an issue at {ISSUES_URL} so the link can be fixed.",
        d.label, d.page
    )
}

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

    #[test]
    fn presets_follow_vram() {
        assert_eq!(recommended_preset(Some(12_288), false).id, "12gb");
        assert_eq!(recommended_preset(Some(11_264), false).id, "12gb", "RTX 2080 Ti");
        assert_eq!(recommended_preset(Some(10_240), false).id, "12gb", "RTX 3080 10 GB");
        assert_eq!(recommended_preset(Some(8_188), false).id, "8gb");
        assert_eq!(recommended_preset(Some(6_144), false).id, "8gb", "smaller cards get the lightest preset");
        assert_eq!(recommended_preset(Some(16_303), false).id, "16gb");
        assert_eq!(recommended_preset(Some(24_564), false).id, "24gb");
        assert_eq!(recommended_preset(Some(32_607), false).id, "32gb");
        assert_eq!(recommended_preset(Some(49_140), false).id, "32gb");
        assert_eq!(recommended_preset(None, false).id, "16gb");
        // Macs never get the graphics-card-only 8 GB preset.
        assert_eq!(recommended_preset(Some(5_000), true).id, "12gb");
        assert!(!preset("8gb").unwrap().offered(true) && preset("12gb").unwrap().offered(true));
    }

    #[test]
    fn catalog_is_well_formed() {
        let all = [ENGINE_CUDA, CUDA_RUNTIME, ENGINE_VULKAN, ENGINE_METAL, TURBO_Q4_K_M, TURBO_Q4_K, VAE, VAE_ORIGINAL, TEXT_ENCODER_Q4_K_M, TEXT_ENCODER_Q8_0, VISION_PROJECTOR, UPSCALER, SUPERSCALE, ULTRASHARP];
        for d in all {
            assert!(d.urls().all(|u| u.starts_with("https://")), "{}", d.id);
            assert_eq!(d.sha256.len(), 64, "{}", d.id);
            assert!(d.sha256.chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()), "{}", d.id);
            assert!(d.size > 0);
            assert!(!d.dest.contains('\\') && d.provides.iter().all(|f| !f.contains('\\')), "portable paths: {}", d.id);
            assert_eq!(d.is_zip(), d.kind == FileKind::Engine, "{}", d.id);
        }
        // Every engine build is marked with this release; the unchanged CUDA runtime is not.
        for d in [ENGINE_CUDA, ENGINE_VULKAN, ENGINE_METAL] {
            assert_eq!(d.engine_tag, Some(ENGINE_TAG), "{}", d.id);
            let commit = ENGINE_TAG.rsplit('-').next().unwrap();
            assert!(d.url.contains(&format!("-{commit}")), "{}", d.id);
        }
        assert_eq!(CUDA_RUNTIME.engine_tag, None);
        // sd-server finds the upscaler by file stem in the upscalers folder.
        assert_eq!(UPSCALER.dest, format!("{UPSCALERS_SUBDIR}/{UPSCALER_NAME}.pth"));
        assert_eq!(UPSCALER.urls().count(), 2, "mirror, then the author's release");
        assert!(LEGACY_UPSCALERS.iter().all(|f| f.starts_with(UPSCALERS_SUBDIR) && *f != UPSCALER.dest));
        // Every model offered in Settings can be installed, except the plain resize.
        for (name, _) in crate::config::UPSCALER_CHOICES {
            assert_eq!(upscaler_download(name).is_some(), *name != crate::config::LANCZOS, "{name}");
        }
        assert_eq!(upscaler_download(crate::config::UPSCALER_CHOICES[0].0).unwrap().id, "upscaler_superscale");
        let metal = downloads_for(&PRESETS[0], GpuBackend::Metal, Path::new("new"));
        assert!(metal.iter().all(|d| d.id != "upscaler_superscale"), "Macs default to Lanczos: no Superscale download");
        for p in PRESETS {
            let cuda = downloads_for(p, GpuBackend::Cuda, Path::new("new"));
            assert_eq!(cuda.len(), 10);
            assert!(cuda.iter().any(|d| d.id == "upscaler") && cuda.iter().any(|d| d.id == "upscaler_superscale"), "MoSR (bundled) and the default model");
            let vk = downloads_for(p, GpuBackend::Vulkan, Path::new("new"));
            assert_eq!(vk.len(), 9);
            assert!(vk.iter().all(|d| d.id != "engine_cuda" && d.id != "cuda_runtime"));
        }
    }

    fn manifest(n: u32) -> EngineManifest {
        let asset = |f: &str| ManifestAsset {
            url: format!("https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-{n}-abcdef0/sd-kokon-abcdef0-bin-{f}.zip"),
            size: 1,
            sha256: "0".repeat(64),
        };
        EngineManifest {
            kokon: Some(KokonEngines {
                tag: format!("kokon-{n}-abcdef0"),
                min_app: "0.10.0".into(),
                win_cuda: asset("win-cuda12-x64"),
                win_vulkan: asset("win-vulkan-x64"),
                linux_cuda: asset("Linux-Ubuntu-22.04-x86_64-cuda12"),
                linux_vulkan: asset("Linux-Ubuntu-22.04-x86_64-vulkan"),
                macos: asset("Darwin-macOS-15.0-universal"),
            }),
        }
    }

    fn edit(n: u32, f: impl FnOnce(&mut KokonEngines)) -> EngineManifest {
        let mut m = manifest(n);
        f(m.kokon.as_mut().unwrap());
        m
    }

    #[test]
    fn engine_manifest_overrides_only_newer_releases() {
        let _guard = ENGINE_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
        assert_eq!(release_number(ENGINE_TAG), Some(1013));
        assert_eq!(apply_engine_release(&manifest(1013), "0.10.0"), Ok(false), "same as built in");
        assert_eq!(engine_tag(), ENGINE_TAG);
        assert_eq!(apply_engine_release(&manifest(1100), "0.9.4"), Ok(false), "too old an app");
        assert_eq!(apply_engine_release(&manifest(1100), "0.10.0"), Ok(true));
        assert_eq!(engine_tag(), "kokon-1100-abcdef0");
        let cuda = &engine_downloads(GpuBackend::Cuda);
        assert_eq!(cuda[0].engine_tag, Some("kokon-1100-abcdef0"));
        assert_eq!(cuda[0].provides, ENGINE_CUDA.provides);
        assert!(cuda[0].page.ends_with("/kokon-1100-abcdef0"));
        assert_eq!(cuda[1].id, "cuda_runtime");
        let vulkan = engine_downloads(GpuBackend::Vulkan)[0];
        if cfg!(target_os = "linux") {
            assert_eq!(cuda[0].dest, "sd-kokon-abcdef0-bin-Linux-Ubuntu-22.04-x86_64-cuda12.zip");
            assert_eq!(vulkan.dest, "engine-vulkan/sd-kokon-abcdef0-bin-Linux-Ubuntu-22.04-x86_64-vulkan.zip");
        } else {
            assert_eq!(cuda[0].dest, "sd-kokon-abcdef0-bin-win-cuda12-x64.zip");
            assert_eq!(vulkan.dest, "engine-vulkan/sd-kokon-abcdef0-bin-win-vulkan-x64.zip");
        }
        assert_eq!(engine_downloads(GpuBackend::Metal)[0].dest, "engine-metal/sd-kokon-abcdef0-bin-Darwin-macOS-15.0-universal.zip");
        // Only that release's downloads in the fork, with a real hash; any bad build rejects it all.
        assert!(apply_engine_release(&edit(1101, |k| k.win_cuda.url = "https://example.com/sd.zip".into()), "0.10.0").is_err());
        assert!(apply_engine_release(&edit(1101, |k| k.macos.sha256 = "xyz".into()), "0.10.0").is_err());
        let other_commit = "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-1101-abcdef0/sd-kokon-1234567-bin-win-vulkan-x64.zip";
        assert!(apply_engine_release(&edit(1101, |k| k.linux_vulkan.url = other_commit.into()), "0.10.0").is_err(), "another commit's build");
        assert!(apply_engine_release(&edit(1101, |k| k.tag = "master-1101-abcdef0".into()), "0.10.0").is_err());
        assert_eq!(engine_tag(), "kokon-1100-abcdef0", "a bad manifest keeps the last good release");
        // An app that pins a newer engine drops an older manifest release.
        assert_eq!(apply_engine_release(&manifest(980), "0.10.0"), Ok(false));
        assert_eq!(engine_tag(), ENGINE_TAG);
        // engine.json as published: the upstream keys for apps up to 0.9.4 next to Kokon's.
        let json = include_str!("../../../engine.json");
        let m: EngineManifest = serde_json::from_str(json).unwrap();
        assert!(apply_engine_release(&m, "0.10.0").is_ok());
        assert_eq!(apply_engine_release(&EngineManifest::default(), "0.10.0"), Ok(false));
        assert_eq!(engine_tag(), ENGINE_TAG);
    }

    #[test]
    fn published_engine_json_matches_the_built_in_pins() {
        // engine.json on master and the app's pins name the same release and the same files, so a
        // release never ships pins its own manifest disagrees with.
        let m: EngineManifest = serde_json::from_str(include_str!("../../../engine.json")).unwrap();
        let k = m.kokon.expect("engine.json has a kokon entry");
        assert_eq!(k.tag, ENGINE_TAG);
        assert!(version_tuple(env!("CARGO_PKG_VERSION")) >= version_tuple(&k.min_app), "min_app {} above this app", k.min_app);
        assert_eq!((k.macos.size, k.macos.sha256.as_str()), (MACOS_METAL_SIZE, MACOS_METAL_SHA256));
        assert_eq!(k.macos.url, ENGINE_METAL.url);
        #[cfg(not(target_os = "linux"))]
        {
            assert_eq!((k.win_cuda.url.as_str(), k.win_cuda.size, k.win_cuda.sha256.as_str()), (ENGINE_CUDA.url, WIN_CUDA_SIZE, WIN_CUDA_SHA256));
            assert_eq!((k.win_vulkan.url.as_str(), k.win_vulkan.size, k.win_vulkan.sha256.as_str()), (ENGINE_VULKAN.url, WIN_VULKAN_SIZE, WIN_VULKAN_SHA256));
        }
        #[cfg(target_os = "linux")]
        {
            assert_eq!((k.linux_cuda.url.as_str(), k.linux_cuda.size, k.linux_cuda.sha256.as_str()), (ENGINE_CUDA.url, LINUX_CUDA_SIZE, LINUX_CUDA_SHA256));
            assert_eq!((k.linux_vulkan.url.as_str(), k.linux_vulkan.size, k.linux_vulkan.sha256.as_str()), (ENGINE_VULKAN.url, LINUX_VULKAN_SIZE, LINUX_VULKAN_SHA256));
        }
    }

    #[test]
    fn engines_of_another_release_need_updating() {
        let dir = tempfile::tempdir().unwrap();
        for f in ENGINE_CUDA.provides.iter().chain(CUDA_RUNTIME.provides) {
            std::fs::write(join_rel(dir.path(), f), b"x").unwrap();
        }
        assert!(!ENGINE_CUDA.is_present(dir.path()), "an engine without the marker is from an older release");
        assert!(CUDA_RUNTIME.is_present(dir.path()), "the runtime needs no marker");
        std::fs::write(dir.path().join(ENGINE_MARKER), "kokon-old").unwrap();
        assert!(!ENGINE_CUDA.is_present(dir.path()));
        ENGINE_CUDA.write_tag(dir.path()).unwrap();
        assert_eq!(ENGINE_CUDA.installed_tag(dir.path()).as_deref(), Some(ENGINE_TAG));
        assert!(ENGINE_CUDA.is_present(dir.path()));
        // Each build has its own marker: the CUDA one does not count for Vulkan.
        std::fs::create_dir_all(dir.path().join("engine-vulkan")).unwrap();
        for f in ENGINE_VULKAN.provides {
            std::fs::write(join_rel(dir.path(), f), b"x").unwrap();
        }
        assert!(!ENGINE_VULKAN.is_present(dir.path()));
        ENGINE_VULKAN.write_tag(dir.path()).unwrap();
        assert!(dir.path().join("engine-vulkan").join(ENGINE_MARKER).is_file());
        assert!(ENGINE_VULKAN.is_present(dir.path()));
    }

    #[test]
    fn user_profiles_download_only_missing_official_files() {
        let dir = tempfile::tempdir().unwrap();
        let own = dir.path().join("own");
        std::fs::create_dir_all(&own).unwrap();
        // The user's diffusion model is there; the VAE is the official file (deleted, or chosen
        // to download); the text encoder is the user's own and missing (a drive not connected).
        std::fs::write(own.join("turbo_int8.safetensors"), b"x").unwrap();
        let vae = own.join(VAE.file_name());
        let p = crate::config::ModelProfile::user(own.join("turbo_int8.safetensors"), vae.clone(), own.join("mine.safetensors"), Some(dir.path().join("dl").join(VISION_PROJECTOR.file_name())));
        let models = profile_model_downloads(&p);
        assert_eq!(models.iter().map(|d| d.id).collect::<Vec<_>>(), ["vae", "vision_projector"], "own files are never downloaded");
        assert_eq!(models[0].path(Path::new("ignored")), vae, "saved where the profile expects it");
        assert_eq!(models[1].path(dir.path()), dir.path().join("dl").join(VISION_PROJECTOR.file_name()));
        assert_eq!((models[0].size, models[0].sha256), (VAE.size, VAE.sha256));
        // An official name with other content (wrong size) is the user's file: never replaced.
        std::fs::write(&vae, b"mine").unwrap();
        assert_eq!(profile_model_downloads(&p).len(), 1);
        let all = downloads_for_profile(&p, GpuBackend::Vulkan);
        assert_eq!(all.iter().map(|d| d.id).collect::<Vec<_>>(), ["engine_vulkan", "upscaler", "trustmark_p_encoder", "trustmark_p_decoder", "upscaler_superscale", "vision_projector"]);
    }

    #[test]
    fn texture_fix_vae_replaces_the_original_only_once_downloaded() {
        let dir = tempfile::tempdir().unwrap();
        let d = dir.path();
        std::fs::create_dir_all(join_rel(d, MODEL_SUBDIR)).unwrap();
        let fill = |f: Download| std::fs::File::create(f.path(d)).unwrap().set_len(f.size).unwrap();
        let mut cfg = crate::config::AppConfig { sdcpp_dir: d.to_path_buf(), ..Default::default() };
        cfg.normalize();
        // A new install gets the texture fix.
        assert_eq!(official_vae(d).id, "vae");
        assert_eq!(cfg.profile().vae, VAE.path(d));
        // An earlier install keeps its original VAE until the user accepts the new one.
        fill(VAE_ORIGINAL);
        cfg.normalize();
        assert_eq!(official_vae(d).id, "vae_original");
        assert_eq!(cfg.profile().vae, VAE_ORIGINAL.path(d));
        assert!(downloads_for(preset("16gb").unwrap(), GpuBackend::Cuda, d).iter().all(|x| x.id != "vae"), "never downloaded uninvited");
        assert_eq!(unused_original_vae(&cfg), None, "in use");
        // Once downloaded, the official files switch and the original can go.
        fill(VAE);
        cfg.normalize();
        assert_eq!(cfg.profile().vae, VAE.path(d));
        assert_eq!(unused_original_vae(&cfg), Some(VAE_ORIGINAL.path(d)));
        // ...unless the user's own profile points to it.
        cfg.set_user_files(crate::config::ModelProfile::user(d.join("m.gguf"), VAE_ORIGINAL.path(d), d.join("te.gguf"), None));
        assert_eq!(unused_original_vae(&cfg), None);
        assert!(!cfg.uses_improved_vae());
        // Accepting it moves that profile to the app's copy; the user's file is never deleted
        // (only the app's folder is cleaned, and only files no profile uses).
        cfg.use_improved_vae();
        assert!(cfg.uses_improved_vae());
        assert_eq!(cfg.profile().vae, VAE.path(d));
        assert_eq!(unused_original_vae(&cfg), Some(VAE_ORIGINAL.path(d)));
    }

    #[test]
    fn q4_k_m_replaces_the_q4_k_only_once_accepted() {
        use crate::config::{AppConfig, ModelProfile};
        let dir = tempfile::tempdir().unwrap();
        let d = dir.path();
        std::fs::create_dir_all(join_rel(d, MODEL_SUBDIR)).unwrap();
        let fill = |f: Download| std::fs::File::create(f.path(d)).unwrap().set_len(f.size).unwrap();
        let mut cfg = AppConfig { sdcpp_dir: d.to_path_buf(), ..Default::default() };
        cfg.normalize();
        // A new install gets the Q4_K_M on every preset, and nothing is offered.
        for p in PRESETS {
            assert_eq!(official_dit(p, d).id, "turbo_q4_k_m", "{}", p.id);
            assert!(downloads_for(p, GpuBackend::Cuda, d).iter().any(|x| x.id == "turbo_q4_k_m"));
        }
        assert_eq!(cfg.profile().diffusion_model, TURBO_Q4_K_M.path(d));
        assert_eq!(dit_update(&cfg), None);
        // An earlier install keeps its Q4_K until the user accepts (postponing changes nothing),
        // and no preset or engine update downloads the Q4_K_M uninvited.
        fill(TURBO_Q4_K);
        cfg.normalize();
        assert_eq!(cfg.profile().diffusion_model, TURBO_Q4_K.path(d));
        assert_eq!(cfg.profile().display_name, "Qwen-Image 2.1 Turbo Q4_K (official)");
        for p in PRESETS {
            assert!(downloads_for(p, GpuBackend::Vulkan, d).iter().all(|x| x.id != "turbo_q4_k_m"), "{}", p.id);
        }
        assert_eq!(dit_update(&cfg), Some(DitUpdate::Official));
        assert_eq!(unused_old_dit(&cfg), None, "in use");
        // An unfinished download changes nothing and deletes nothing.
        std::fs::write(TURBO_Q4_K_M.path(d), b"part").unwrap();
        cfg.use_new_dit();
        assert_eq!(cfg.profile().diffusion_model, TURBO_Q4_K.path(d));
        assert_eq!(unused_old_dit(&cfg), None);
        // Once downloaded and verified, the official files switch and the Q4_K can go.
        fill(TURBO_Q4_K_M);
        cfg.use_new_dit();
        assert_eq!(cfg.profile().diffusion_model, TURBO_Q4_K_M.path(d));
        assert_eq!(cfg.profile().display_name, "Qwen-Image 2.1 Turbo Q4_K_M (official)");
        assert_eq!(dit_update(&cfg), None);
        assert_eq!(unused_old_dit(&cfg), Some(TURBO_Q4_K.path(d)));
        // ...unless a profile of the user's points to it.
        cfg.set_user_files(ModelProfile::user(TURBO_Q4_K.path(d), VAE.path(d), d.join("te.gguf"), None));
        assert_eq!(unused_old_dit(&cfg), None);
    }

    #[test]
    fn own_files_only_get_a_suggestion() {
        use crate::config::{AppConfig, ModelProfile};
        let dir = tempfile::tempdir().unwrap();
        let d = dir.path().join("sd");
        std::fs::create_dir_all(join_rel(&d, MODEL_SUBDIR)).unwrap();
        let mine = dir.path().join("elsewhere").join("my turbo.gguf");
        std::fs::create_dir_all(mine.parent().unwrap()).unwrap();
        std::fs::write(&mine, b"the user's Q4_K").unwrap();
        let is_old = |p: &Path| p == mine;
        let mut cfg = AppConfig { sdcpp_dir: d.clone(), ..Default::default() };
        let own = |dit: &Path| ModelProfile::user(dit.to_path_buf(), dir.path().join("vae.safetensors"), dir.path().join("te.gguf"), None);
        // Their file is the old Q4_K (any name, any folder): a suggestion.
        cfg.set_user_files(own(&mine));
        assert_eq!(dit_update_with(&cfg, is_old), Some(DitUpdate::Own));
        // Already the Q4_K_M, or any other file: their choice, no offer.
        cfg.set_user_files(own(&dir.path().join("qwen-image-2.1-turbo-Q4_K_M.gguf")));
        assert_eq!(dit_update_with(&cfg, is_old), None);
        cfg.set_user_files(own(&dir.path().join("qwen_image_2.1_turbo-Q8_0.gguf")));
        assert_eq!(dit_update_with(&cfg, is_old), None);
        // Accepted: the profile points to the app's copy; their file stays where it is and is
        // never a candidate for deletion.
        cfg.set_user_files(own(&mine));
        std::fs::File::create(TURBO_Q4_K_M.path(&d)).unwrap().set_len(TURBO_Q4_K_M.size).unwrap();
        cfg.use_new_dit();
        assert_eq!(cfg.active_profile, crate::config::USER_PROFILE_ID);
        assert_eq!(cfg.profile().diffusion_model, TURBO_Q4_K_M.path(&d));
        assert_eq!(dit_update_with(&cfg, is_old), None);
        assert!(mine.is_file());
        assert_eq!(unused_old_dit(&cfg), None);
    }

    #[test]
    fn presence_checks() {
        let dir = tempfile::tempdir().unwrap();
        assert!(!VAE.is_present(dir.path()));
        std::fs::create_dir_all(join_rel(dir.path(), MODEL_SUBDIR)).unwrap();
        std::fs::write(VAE.path(dir.path()), b"short").unwrap();
        assert!(!VAE.is_present(dir.path()), "a partial file is not installed");
        for f in ENGINE_CUDA.provides {
            std::fs::write(dir.path().join(f), b"x").unwrap();
        }
        ENGINE_CUDA.write_tag(dir.path()).unwrap();
        assert!(ENGINE_CUDA.is_present(dir.path()));
        let hint = manual_download_hint(&ENGINE_CUDA, dir.path());
        assert!(hint.contains("extract it into") && hint.contains(ISSUES_URL));
        // The Vulkan build lives in its own folder: the CUDA files don't count for it.
        assert!(!ENGINE_VULKAN.is_present(dir.path()));
        std::fs::create_dir_all(dir.path().join("engine-vulkan")).unwrap();
        for f in ENGINE_VULKAN.provides {
            std::fs::write(join_rel(dir.path(), f), b"x").unwrap();
        }
        ENGINE_VULKAN.write_tag(dir.path()).unwrap();
        assert!(ENGINE_VULKAN.is_present(dir.path()));
        let mut cfg = crate::config::AppConfig::default();
        cfg.sdcpp_dir = dir.path().to_path_buf();
        cfg.gpu_backend = GpuBackend::Vulkan;
        if !cfg!(target_os = "macos") {
            // The Vulkan build is a Windows or Linux download (no Mac one).
            assert_eq!(cfg.server_exe(), join_rel(dir.path(), ENGINE_VULKAN.provides[0]), "installer and launcher agree on the path");
        }
        cfg.gpu_backend = GpuBackend::Metal;
        if !cfg!(windows) {
            assert_eq!(cfg.server_exe(), join_rel(dir.path(), ENGINE_METAL.provides[0]));
        }
        assert!(manual_download_hint(&ENGINE_VULKAN, dir.path()).contains("engine-vulkan"));
    }
}