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.
TypeScript ai-photo-editorcomfyui-alternativegenerative-fillimage-editingimage-generationinpaintinglinuxlocal-aimacosmcpmcp-servernano-banana-alternativeofflinephoto-editorprivacyqwen-imageqwen-image-2-1stable-diffusion-cppvulkanwindows
//! Persistent configuration and model profiles. Stored as JSON in
//! `%APPDATA%\Kokon\config.json`; every field has a default so older or
//! partial files keep loading.
use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use crate::error::{AppError, ErrorCode};
pub const APP_NAME: &str = "Kokon";
/// Folder names before the app was renamed Kokon (2026-10-08); moved on first start.
const LEGACY_CONFIG_DIR: &str = "Qwen Local Studio";
const LEGACY_DATA_DIR: &str = "QwenLocalStudio";
/// Distinct from the installer's program folder `%LOCALAPPDATA%\Kokon`, so uninstalling
/// never touches the gallery or the models.
pub const DATA_DIR_NAME: &str = "KokonData";
pub const DEFAULT_SERVER_PORT: u16 = 39150;
pub const DEFAULT_SERVICE_PORT: u16 = 39151;
/// Port for access from other devices (`remote_access`); the token API stays on loopback.
pub const DEFAULT_REMOTE_PORT: u16 = 39152;
/// Schema 8 (2026-10-12): the upscalers folder setting is gone (always `<sdcpp>/models/upscalers`)
/// and ESRGAN tile sizes reset to automatic.
/// Schema 9 (2026-10-16, #14): profiles record their model and source; model paths edited by
/// hand on the official profile move to a profile of the user's own files.
/// Schema 10 (2026-10-19): the 8 GB preset's VRAM reserve 1 -> 1.5 GiB (unless set by hand).
const SCHEMA_VERSION: u32 = 10;
/// `upscaler_model` value for a plain Lanczos resize (no model).
pub const LANCZOS: &str = "lanczos";
/// Upscalers offered in Settings: (file stem, label). Superscale-SP is a setup download, MoSR is
/// bundled with the app, UltraSharp is an optional download (`catalog::UPSCALER_DOWNLOADS`).
pub const UPSCALER_CHOICES: &[(&str, &str)] = &[
("4x_NMKD-Superscale-SP_178000_G", "Superscale-SP"),
(crate::catalog::UPSCALER_NAME, "MoSR (experimental)"),
("4x-UltraSharp", "UltraSharp"),
(LANCZOS, "Lanczos (plain resize)"),
];
/// Default model (user choice, 2026-10-12, after MoSR drew a grid on clean renders): Superscale-SP
/// on PCs, Lanczos on Macs, where ESRGAN takes minutes (1024² to 2048² on an M2 Pro: Superscale-SP
/// 5 min 45 s, Lanczos 1 s).
pub const DEFAULT_UPSCALER: &str = if cfg!(target_os = "macos") { LANCZOS } else { UPSCALER_CHOICES[0].0 };
/// Extensions sd-server accepts for model-backed upscalers (common.cpp, commit 3f8527a).
pub const UPSCALER_EXTENSIONS: &[&str] = &["pth", "safetensors", "gguf", "pt"];
/// Profile id of the official Qwen-Image 2.1 weights (the default since schema 5).
pub const OFFICIAL_PROFILE_ID: &str = "qwen-image-2.1";
/// Profile id of Qwen-Image 2.1 files the user already had (#14): one per model.
pub const USER_PROFILE_ID: &str = "qwen-image-2.1-user";
/// The model a profile's files are (`ModelProfile::model`). Today the only one; future model
/// definitions (strategy, presets, prompts) will be looked up by this id.
pub const QWEN_IMAGE_21: &str = "qwen-image-2.1";
/// Where the text encoder's weights live. Compute always runs on the selected GPU except
/// for `Cpu`, which also computes on the CPU (slow for image editing, measured ~35×).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum TextEncoderPlacement {
/// Weights in system RAM, compute on GPU (`--params-backend te=cpu`). Recommended.
#[default]
Ram,
/// Weights and compute on GPU (fastest prompt encoding, slower sampling on 16 GB).
Gpu,
/// Weights and compute on CPU (`--backend te=cpu`). Lowest VRAM, slow editing.
Cpu,
/// Let stable-diffusion.cpp's auto-fit decide.
Auto,
/// Every model's weights reloaded from disk when needed (`--params-backend disk`).
/// Least memory, slower; for Macs with 16 GB of unified memory.
Disk,
}
/// Which stable-diffusion.cpp build runs the model. Each build lives in its own folder, so
/// Folder of Kokon's Mac engine, in the stable-diffusion.cpp folder (beside `engine-metal`), and its executable
/// (the engine's kernels and resources are the `KokonEngineMac_KokonEngine.bundle` next to it).
pub const MAC_ENGINE_DIR: &str = "engine-mac";
pub const MAC_ENGINE_EXE: &str = "kokon-engine-mac";
/// switching back and forth needs no re-download.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GpuBackend {
/// NVIDIA (CUDA 12 build). The verified path.
Cuda,
/// AMD, Intel and NVIDIA through Vulkan. Works on NVIDIA; AMD/Intel unverified.
Vulkan,
/// Apple Silicon (Metal build, macOS 15+). Beta.
Metal,
}
impl Default for GpuBackend {
/// The engine of this platform when nothing is configured.
fn default() -> Self {
if cfg!(target_os = "macos") { GpuBackend::Metal } else { GpuBackend::Cuda }
}
}
impl GpuBackend {
/// ggml device-name prefix (`cuda0`, `vulkan0`).
pub fn device_prefix(self) -> &'static str {
match self {
GpuBackend::Cuda => "cuda",
GpuBackend::Vulkan => "vulkan",
// ggml registers the Mac GPU as "MTL0" (`--list-devices`, seen on an M2 Pro).
GpuBackend::Metal => "mtl",
}
}
/// Folder of this build, relative to the stable-diffusion.cpp folder ("" = the folder
/// itself, where the CUDA build has always been).
pub fn engine_subdir(self) -> &'static str {
match self {
GpuBackend::Cuda => "",
GpuBackend::Vulkan => "engine-vulkan",
GpuBackend::Metal => "engine-metal",
}
}
/// Engine for a GPU vendor as reported by `diagnostics::query_gpus`.
pub fn for_vendor(vendor: &str) -> Self {
match vendor {
"nvidia" => GpuBackend::Cuda,
"apple" => GpuBackend::Metal,
_ => GpuBackend::Vulkan,
}
}
}
/// Effort of the refine pass of older versions (two-pass generation, removed 2026-10-06;
/// Detailed upscale, removed 2026-10-09). Kept to read their gallery records.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum RefineMode {
/// Kept for old configs; behaves like Fast.
Off,
/// Fewer refine steps + EasyCache.
#[default]
Fast,
/// More refine steps, no cache.
Best,
}
/// Per-model planning settings. Sampling itself is fixed by the Turbo model: its 8-step
/// schedule (`planner::TURBO_SIGMAS`) at CFG 1.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct RecommendedSettings {
pub sampler: String,
/// Pixel area used by Auto resolution at each quality level.
pub area_fast: u64,
pub area_balanced: u64,
pub area_quality: u64,
pub align: u32,
pub max_side: u32,
pub max_references: u32,
}
impl Default for RecommendedSettings {
fn default() -> Self {
// Official Qwen-Image 2.1 Turbo settings (Qwen/Qwen-Image-2.1-Turbo model card): its
// saved 8-step schedule with flow-matching Euler, no CFG, native 2K buckets. The
// presets differ only in size: ~1 MP, 1.5K and native 2K.
Self { sampler: "euler".into(), area_fast: 1024 * 1024, area_balanced: 1536 * 1536, area_quality: 2048 * 2048, align: 32, max_side: 4096, max_references: 10 }
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct ProfileCapabilities {
pub text_to_image: bool,
pub edit: bool,
pub multi_reference: bool,
pub inpaint: bool,
pub outpaint: bool,
pub alpha: bool,
}
impl Default for ProfileCapabilities {
fn default() -> Self {
Self { text_to_image: true, edit: true, multi_reference: true, inpaint: true, outpaint: true, alpha: true }
}
}
/// Where a profile's files come from.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ProfileSource {
/// Downloaded by Setup from the catalog, tested with Kokon. Paths follow the folder and preset.
Official,
/// Files the user already had (any folder, any quantization), not tested by Kokon.
User,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct ModelProfile {
pub id: String,
pub display_name: String,
/// The model these files are ([`QWEN_IMAGE_21`]).
pub model: String,
pub source: ProfileSource,
/// Folder the user's files were found in (Setup searches it again when one has moved).
pub scan_dir: Option<PathBuf>,
pub diffusion_model: PathBuf,
pub vae: PathBuf,
pub text_encoder: PathBuf,
pub vision_projector: Option<PathBuf>,
/// Extra sd-server arguments specific to this model.
pub backend_args: Vec<String>,
pub recommended_settings: RecommendedSettings,
pub capabilities: ProfileCapabilities,
}
impl Default for ModelProfile {
fn default() -> Self {
Self::official(&default_sdcpp_dir(), crate::catalog::preset(crate::catalog::DEFAULT_PRESET).unwrap())
}
}
impl ModelProfile {
/// The official weights a hardware preset downloads (GGUF of Qwen/Qwen-Image-2.1-Turbo,
/// Qwen's own Qwen3-VL GGUF, the 2.1 VAE).
pub fn official(sdcpp_dir: &Path, preset: &crate::catalog::Preset) -> Self {
use crate::catalog::{official_dit, official_vae, VISION_PROJECTOR};
let diffusion = official_dit(preset, sdcpp_dir);
let quant = diffusion.dest.rsplit('-').next().unwrap_or("").trim_end_matches(".gguf");
Self {
id: OFFICIAL_PROFILE_ID.into(),
display_name: format!("Qwen-Image 2.1 Turbo {quant} (official)"),
model: QWEN_IMAGE_21.into(),
source: ProfileSource::Official,
scan_dir: None,
diffusion_model: diffusion.path(sdcpp_dir),
vae: official_vae(sdcpp_dir).path(sdcpp_dir),
text_encoder: preset.text_encoder.path(sdcpp_dir),
vision_projector: Some(VISION_PROJECTOR.path(sdcpp_dir)),
backend_args: vec![],
recommended_settings: RecommendedSettings::default(),
capabilities: ProfileCapabilities::default(),
}
}
/// (label, path, required) for every model file.
pub fn files(&self) -> Vec<(&'static str, &Path, bool)> {
let mut v = vec![
("Diffusion model", self.diffusion_model.as_path(), true),
("VAE", self.vae.as_path(), true),
("Text encoder (Qwen3-VL)", self.text_encoder.as_path(), true),
];
if let Some(p) = &self.vision_projector {
v.push(("Vision projector (mmproj)", p.as_path(), true));
}
v
}
/// Files the user already had.
pub fn user(diffusion_model: PathBuf, vae: PathBuf, text_encoder: PathBuf, vision_projector: Option<PathBuf>) -> Self {
Self {
id: USER_PROFILE_ID.into(),
display_name: "Qwen-Image 2.1 (your files)".into(),
source: ProfileSource::User,
scan_dir: None,
diffusion_model,
vae,
text_encoder,
vision_projector,
..Self::default()
}
}
pub fn is_official(&self) -> bool {
self.source == ProfileSource::Official
}
fn same_files(&self, o: &ModelProfile) -> bool {
(&self.diffusion_model, &self.vae, &self.text_encoder, &self.vision_projector) == (&o.diffusion_model, &o.vae, &o.text_encoder, &o.vision_projector)
}
pub fn model_name(&self) -> String {
self.diffusion_model.file_stem().map(|s| s.to_string_lossy().into_owned()).unwrap_or_else(|| self.display_name.clone())
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct AppConfig {
pub schema_version: u32,
pub sdcpp_dir: PathBuf,
/// stable-diffusion.cpp build that runs the model.
pub gpu_backend: GpuBackend,
pub server_port: u16,
pub service_port: u16,
/// Open the browser UI to other devices on the network (`remote_port`, all interfaces).
/// Needs a password first (`remote::PasswordFile`). Changed only through `/remote`: a
/// whole-config save keeps the current values (`Engine::set_config`).
pub remote_access: bool,
pub remote_port: u16,
pub active_profile: String,
pub profiles: Vec<ModelProfile>,
/// ggml device name for diffusion + VAE, e.g. "cuda0" (see `sd-server --list-devices`).
/// A name of another engine (e.g. "cuda0" with Vulkan) means device 0 of the active one.
pub device: String,
pub text_encoder_placement: TextEncoderPlacement,
/// VRAM kept free, in GiB (passed as a negative `--max-vram`).
pub vram_reserve_gib: f32,
pub flash_attention: bool,
/// Native CUDA SageAttention in the diffusion model (`--sage-attn`); ~1.5x faster
/// steps at 2K on an RTX 5070 Ti with near-identical output. CUDA only (SM80+);
/// ignored by other engines.
pub sage_attention: bool,
/// The card the engine runs on is too old for SageAttention (`GpuInfo::lacks_sage_attention`).
/// Set by `Engine::config` from the detected GPU and shown in Settings; never read from
/// the settings file.
#[serde(skip_deserializing)]
pub sage_unsupported: bool,
/// VAE tile size in pixels (`--vae-tiling --vae-tile-size N`); 0 disables tiling.
/// Untiled 2K decodes need ~18 GB, OOM and retry with 256px tiles (~22 s); 768px
/// tiles decode 2K in ~4 s on a 16 GB card.
pub vae_tile_size: u32,
/// Storage type of the Qwen 2.1 prefix cache (text + reference K/V reused across steps,
/// `--model-args qwen_image_2_1_prefix_cache_type=...`). "auto" picks FP32 whenever
/// SageAttention is on: ~8 GiB for a 2 MP reference, which never fits on 16 GB, so every
/// edit fell back to the full sequence. "q8_0" (~2.2 GiB at 2 MP) fits; "f16" halves FP32;
/// "off" disables the cache.
pub prefix_cache_type: String,
/// Load all weights when the server starts (`--eager-load`) instead of on the first
/// step of the first job (~7 s of per-segment loading).
pub eager_load: bool,
/// Upscaler model (file stem in the upscalers folder); the bundled MoSR runs when its file
/// is missing.
pub upscaler_model: String,
/// Upscaler tile size in pixels; 0 = automatic (`planner::upscale_tile`).
pub upscale_tile_size: u32,
/// Share of the upscaler's result kept over a plain Lanczos enlargement (0..1; 1 = only
/// the upscaler). Lower values tone down texture the model invents.
pub upscale_blend: f32,
/// Shrink the input before the upscaler so its x4 output is ~1.41x the target
/// (`pipeline::prescale_size`): the model then sees the kind of image it was trained on,
/// which avoided grid patterns on clean renders in an A/B on 8 images (2026-10-12).
pub upscale_prescale: bool,
pub extra_server_args: Vec<String>,
/// Kokon's own engine for Apple Silicon (`engine-mac/`, `kokon-engine-mac serve`) instead of sd.cpp's Metal build:
/// the GPU, the CPU's matrix unit and the Neural Engine together, ~4x faster text to image on an M2 Pro. Experimental;
/// false in a new config, but the default on Macs with 16 GB+ since 0.12: the desktop app switches it on once at
/// start (`macEngineDefaultDue` in src/lib/logic.ts) unless the user already chose (Settings → Performance). Text to image, edits with references, brushed edits, extending an
/// image and Prompt+; no LoRAs or second passes yet (`Capabilities::mac_engine_unsupported`). sd.cpp stays the fallback,
/// the engine on Windows and Linux and on smaller Macs.
pub mac_engine: bool,
pub output_dir: PathBuf,
pub keep_server_running: bool,
/// When no desktop window is attached (e.g. MCP only), unload the model after this
/// many idle minutes. 0 disables.
pub idle_unload_minutes: u32,
pub setup_complete: bool,
/// Hardware preset chosen in the setup wizard (`catalog::PRESETS`).
pub hardware_preset: String,
/// Plan as if the GPU had this much VRAM (MiB); 0 = use the detected size. For testing
/// smaller cards on a larger one, together with a VRAM ballast (scripts/dev).
pub vram_override_mib: u64,
/// System prompts of the prompt enhancer for text-to-image, edits and new images from
/// references; "" = the built-in ones (`enhancer::T2I_SYSTEM_PROMPT`, `EDIT_SYSTEM_PROMPT`,
/// `COMPOSE_SYSTEM_PROMPT`).
pub enhancer_t2i_prompt: String,
pub enhancer_edit_prompt: String,
pub enhancer_compose_prompt: String,
/// The user's LoRAs (Settings → LoRA), each a copy in `lora_dir`. Changed only through the
/// LoRA endpoints: a whole-config save keeps the current list (`Engine::set_config`).
pub loras: Vec<LoraEntry>,
/// Opaque UI preferences (last quality, resolution mode, aspect...).
pub ui: serde_json::Value,
}
impl Default for AppConfig {
fn default() -> Self {
let sdcpp = default_sdcpp_dir();
Self {
schema_version: SCHEMA_VERSION,
profiles: vec![ModelProfile::official(&sdcpp, crate::catalog::preset(crate::catalog::DEFAULT_PRESET).unwrap())],
active_profile: OFFICIAL_PROFILE_ID.into(),
sdcpp_dir: sdcpp,
gpu_backend: GpuBackend::default(),
server_port: DEFAULT_SERVER_PORT,
service_port: DEFAULT_SERVICE_PORT,
remote_access: false,
remote_port: DEFAULT_REMOTE_PORT,
device: "cuda0".into(),
text_encoder_placement: TextEncoderPlacement::Ram,
vram_reserve_gib: 1.0,
flash_attention: true,
sage_attention: true,
sage_unsupported: false,
vae_tile_size: 768,
prefix_cache_type: "q8_0".into(),
eager_load: true,
upscaler_model: DEFAULT_UPSCALER.into(),
upscale_tile_size: 0,
upscale_blend: 1.0,
upscale_prescale: false,
extra_server_args: vec![],
mac_engine: false,
output_dir: default_output_dir(),
keep_server_running: false,
idle_unload_minutes: 15,
setup_complete: false,
hardware_preset: crate::catalog::DEFAULT_PRESET.into(),
vram_override_mib: 0,
enhancer_t2i_prompt: String::new(),
enhancer_edit_prompt: String::new(),
enhancer_compose_prompt: String::new(),
loras: vec![],
ui: serde_json::json!({}),
}
}
}
/// A LoRA the user loaded. Kokon's copy is `<lora_dir>/<id>.safetensors` (see `lora.rs`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct LoraEntry {
/// File stem of the copy; also how requests name it.
pub id: String,
/// Shown in the app (the original file's name until the user renames it).
pub name: String,
/// The file the user picked (never changed by Kokon).
pub source: PathBuf,
pub weight: f32,
/// Added in front of the prompt when the LoRA is used.
pub trigger_words: String,
/// On in every new project of the app (MCP never uses LoRAs).
pub on_by_default: bool,
/// Size of the copy in bytes.
pub size: u64,
/// From the check: the LoRA works only in part.
pub warning: Option<String>,
/// What the copy changed (split layers, alpha).
pub notes: Vec<String>,
pub added_at: String,
}
impl Default for LoraEntry {
fn default() -> Self {
Self { id: String::new(), name: String::new(), source: PathBuf::new(), weight: 1.0, trigger_words: String::new(), on_by_default: false, size: 0, warning: None, notes: vec![], added_at: String::new() }
}
}
impl LoraEntry {
pub fn file_name(&self) -> String {
format!("{}.safetensors", self.id)
}
}
/// `QLS_OUTPUT_DIR` sets it for a new install (the Docker image's `/gallery` volume).
pub fn default_output_dir() -> PathBuf {
if let Ok(p) = std::env::var("QLS_OUTPUT_DIR") {
return PathBuf::from(p);
}
dirs::picture_dir()
.or_else(|| dirs::home_dir().map(|h| h.join("Pictures")))
.unwrap_or_else(|| PathBuf::from("."))
.join(APP_NAME)
}
/// Where the setup wizard installs stable-diffusion.cpp and the models on a new install:
/// `%LOCALAPPDATA%\KokonData\sdcpp`.
pub fn default_sdcpp_dir() -> PathBuf {
data_dir().join("sdcpp")
}
/// `%APPDATA%\Kokon` (roaming) — configuration.
pub fn config_dir() -> PathBuf {
if let Ok(p) = std::env::var("QLS_CONFIG_DIR") {
return PathBuf::from(p);
}
migrate_dir(&dirs::config_dir().unwrap_or_else(std::env::temp_dir), LEGACY_CONFIG_DIR, APP_NAME)
}
/// `%LOCALAPPDATA%\KokonData` — gallery database, inputs, thumbnails, logs, models
/// installed by the setup screen.
pub fn data_dir() -> PathBuf {
if let Ok(p) = std::env::var("QLS_DATA_DIR") {
return PathBuf::from(p);
}
migrate_dir(&dirs::data_local_dir().unwrap_or_else(std::env::temp_dir), LEGACY_DATA_DIR, DATA_DIR_NAME)
}
/// The data folder of the app's previous name (for relocating stored paths).
fn legacy_data_dir() -> PathBuf {
dirs::data_local_dir().unwrap_or_else(std::env::temp_dir).join(LEGACY_DATA_DIR)
}
/// `base\new`, moving `base\old` there first if only the old folder exists (a rename on the
/// same drive). If the move fails, e.g. while a service of the old version still holds its
/// files, the old folder stays in use and the move is retried on the next start.
pub fn migrate_dir(base: &Path, old: &str, new: &str) -> PathBuf {
let new_path = base.join(new);
let old_path = base.join(old);
// Unit tests must never move the real folders of this PC (tests call it with temp dirs).
if cfg!(test) && !base.starts_with(std::env::temp_dir()) {
return new_path;
}
if new_path.exists() || !old_path.is_dir() {
return new_path;
}
match std::fs::rename(&old_path, &new_path) {
Ok(()) => {
tracing::info!("moved {} to {}", old_path.display(), new_path.display());
new_path
}
Err(e) => {
tracing::warn!("could not move {} to {} ({e}); using the old folder", old_path.display(), new_path.display());
old_path
}
}
}
/// `p` inside the old data folder after that folder was moved: the same path in the new one.
fn relocate(p: &mut PathBuf, old: &Path, new: &Path) {
if old.exists() || old == new {
return;
}
if let Ok(rest) = p.strip_prefix(old) {
*p = new.join(rest);
}
}
impl AppConfig {
pub fn path() -> PathBuf {
config_dir().join("config.json")
}
pub fn load() -> Self {
Self::load_from(&Self::path())
}
pub fn load_from(path: &Path) -> Self {
match std::fs::read_to_string(path) {
// Windows PowerShell 5.1 writes UTF-8 with a BOM; accept it.
Ok(s) => match serde_json::from_str::<AppConfig>(s.trim_start_matches('\u{feff}')) {
Ok(mut c) => {
if c.profiles.is_empty() {
c.profiles.push(ModelProfile::official(&c.sdcpp_dir, c.preset()));
c.active_profile = OFFICIAL_PROFILE_ID.into();
}
if c.schema_version < 8 {
// ESRGAN tile sizes don't carry over to MoSR, which picks its own by
// GPU memory. The custom upscalers folder key is ignored.
c.upscale_tile_size = 0;
// 0.9.0's default moves to the new one; a model picked by hand stays.
if c.upscaler_model.trim() == "4x-UltraSharp" {
c.upscaler_model = DEFAULT_UPSCALER.into();
}
}
if c.schema_version < 7 {
// Turbo only (2026-10-09): the official profile moves from the base
// Qwen-Image 2.1 weights to the preset's Turbo model, and every profile
// gets the new presets (the old step/CFG settings no longer exist).
let preset = c.preset();
for p in &mut c.profiles {
if p.id == OFFICIAL_PROFILE_ID {
let official = ModelProfile::official(&c.sdcpp_dir, preset);
p.display_name = official.display_name;
p.diffusion_model = official.diffusion_model;
}
p.recommended_settings = RecommendedSettings::default();
}
}
// Paths into the data folder of the app's old name (models installed by the
// setup screen) follow the folder to its new name.
if std::env::var("QLS_DATA_DIR").is_err() {
c.relocate_paths(&legacy_data_dir(), &data_dir());
}
if c.schema_version < 9 {
// Older files have no source: every profile but the official one is
// the user's.
for p in &mut c.profiles {
if p.id != OFFICIAL_PROFILE_ID {
p.source = ProfileSource::User;
}
}
c.keep_hand_edited_paths();
}
if c.schema_version < 10 && c.hardware_preset == "8gb" && c.vram_reserve_gib == 1.0 {
c.vram_reserve_gib = c.preset().vram_reserve_gib;
}
// The official weights are always available as a profile, built for the
// configured folder and preset; the active one stays as it is.
c.normalize();
c.schema_version = c.schema_version.max(SCHEMA_VERSION);
c
}
Err(e) => {
tracing::warn!("config at {} is invalid ({e}); using defaults", path.display());
let _ = std::fs::copy(path, path.with_extension("json.invalid"));
Self::default()
}
},
Err(_) => Self::default(),
}
}
pub fn save(&self) -> Result<(), AppError> {
self.save_to(&Self::path())
}
/// Atomic write: temp file + rename.
pub fn save_to(&self, path: &Path) -> Result<(), AppError> {
if let Some(dir) = path.parent() {
std::fs::create_dir_all(dir).map_err(|e| AppError::io("create the settings folder", dir, e))?;
}
let tmp = path.with_extension("json.tmp");
let json = serde_json::to_string_pretty(self).map_err(AppError::internal)?;
std::fs::write(&tmp, json).map_err(|e| AppError::io("write settings", &tmp, e))?;
std::fs::rename(&tmp, path).map_err(|e| AppError::io("save settings", path, e))?;
Ok(())
}
pub fn profile(&self) -> &ModelProfile {
self.profiles.iter().find(|p| p.id == self.active_profile).unwrap_or(&self.profiles[0])
}
pub fn user_profile(&self) -> Option<&ModelProfile> {
self.profiles.iter().find(|p| p.id == USER_PROFILE_ID)
}
/// Keeps the invariants every saved config has: the official profile exists and points to
/// the official files of the configured folder and preset (its tuning is kept), every
/// other profile is the user's, and the active profile exists.
pub fn normalize(&mut self) {
// A prompt equal to the built-in one is saved as "" so it follows future defaults.
for (custom, default) in [
(&mut self.enhancer_t2i_prompt, crate::enhancer::T2I_SYSTEM_PROMPT),
(&mut self.enhancer_edit_prompt, crate::enhancer::EDIT_SYSTEM_PROMPT),
(&mut self.enhancer_compose_prompt, crate::enhancer::COMPOSE_SYSTEM_PROMPT),
] {
if custom.trim().is_empty() || custom.trim() == default {
custom.clear();
}
}
for p in &mut self.profiles {
p.source = if p.id == OFFICIAL_PROFILE_ID { ProfileSource::Official } else { ProfileSource::User };
if p.model.trim().is_empty() {
p.model = QWEN_IMAGE_21.into();
}
}
let mut official = ModelProfile::official(&self.sdcpp_dir, self.preset());
match self.profiles.iter_mut().find(|p| p.id == OFFICIAL_PROFILE_ID) {
Some(p) => {
official.recommended_settings = p.recommended_settings.clone();
official.backend_args = p.backend_args.clone();
official.capabilities = p.capabilities.clone();
*p = official;
}
None => self.profiles.insert(0, official),
}
if !self.profiles.iter().any(|p| p.id == self.active_profile) {
self.active_profile = OFFICIAL_PROFILE_ID.into();
}
}
/// Before schema 9, own files were set by editing the official profile's paths
/// (Settings → Models, or config.json by hand). When those files are all there, they move
/// to the user profile (active if the official one was), so presets can't overwrite them.
fn keep_hand_edited_paths(&mut self) {
let canonical = ModelProfile::official(&self.sdcpp_dir, self.preset());
let Some(p) = self.profiles.iter().find(|p| p.id == OFFICIAL_PROFILE_ID) else { return };
if p.same_files(&canonical) || !p.files().iter().all(|(_, f, _)| f.is_file()) || self.user_profile().is_some() {
return;
}
let mut user = ModelProfile::user(p.diffusion_model.clone(), p.vae.clone(), p.text_encoder.clone(), p.vision_projector.clone());
user.recommended_settings = p.recommended_settings.clone();
user.backend_args = p.backend_args.clone();
tracing::info!("model paths edited on the official profile moved to the profile of your own files");
self.profiles.push(user);
if self.active_profile == OFFICIAL_PROFILE_ID {
self.active_profile = USER_PROFILE_ID.into();
}
}
/// Saves the user's own files as the user profile and makes it active. Tuning of an
/// earlier user profile is kept.
pub fn set_user_files(&mut self, mut profile: ModelProfile) {
profile.id = USER_PROFILE_ID.into();
profile.source = ProfileSource::User;
if let Some(old) = self.user_profile() {
profile.recommended_settings = old.recommended_settings.clone();
profile.backend_args = old.backend_args.clone();
}
self.profiles.retain(|p| p.id != USER_PROFILE_ID);
self.profiles.push(profile);
self.active_profile = USER_PROFILE_ID.into();
}
/// The active model uses the texture-fix VAE (#21).
pub fn uses_improved_vae(&self) -> bool {
self.profile().vae.file_name().is_some_and(|n| n.eq_ignore_ascii_case(crate::catalog::VAE.file_name()))
}
/// Makes the active model use the texture-fix VAE in the app's folder, once downloaded. The
/// official files switch by themselves (`catalog::official_vae`); the user's own profile
/// points to it instead of their VAE, which stays where it is.
pub fn use_improved_vae(&mut self) {
let vae = crate::catalog::VAE.path(&self.sdcpp_dir);
let active = self.active_profile.clone();
if let Some(p) = self.profiles.iter_mut().find(|p| p.id == active && !p.is_official()) {
p.vae = vae;
}
self.normalize();
}
/// Makes the active model use the Q4_K_M image model in the app's folder, once downloaded.
/// The official files switch by themselves (`catalog::official_dit`); the user's own profile
/// points to it instead of their file, which stays where it is.
pub fn use_new_dit(&mut self) {
let dit = crate::catalog::TURBO_Q4_K_M.path(&self.sdcpp_dir);
let active = self.active_profile.clone();
if let Some(p) = self.profiles.iter_mut().find(|p| p.id == active && !p.is_official()) {
p.diffusion_model = dit;
}
self.normalize();
}
/// Makes the official files the active model (they may still need downloading).
pub fn use_official(&mut self) {
self.normalize();
self.active_profile = OFFICIAL_PROFILE_ID.into();
}
/// Model files of the active profile that are not there (label, path).
pub fn missing_files(&self) -> Vec<(&'static str, PathBuf)> {
self.profile().files().into_iter().filter(|(_, p, required)| *required && !p.is_file()).map(|(l, p, _)| (l, p.to_path_buf())).collect()
}
/// Why the inference server cannot start: the engine or a model file is missing.
pub fn missing_files_error(&self) -> Option<AppError> {
let exe = self.server_exe();
if !exe.is_file() && self.uses_mac_engine() {
return Some(
AppError::new(ErrorCode::MissingModel, format!("Kokon's Mac engine was not found in {}.", exe.parent().unwrap_or(&exe).display()))
.suggest("Turn off Kokon's Mac engine in Settings → Performance to use the standard engine."),
);
}
if !exe.is_file() {
return Some(
AppError::new(ErrorCode::MissingModel, format!("sd-server was not found in {}.", self.engine_dir().display()))
.suggest("Install it from Settings → Models → Set up models…, or set the stable-diffusion.cpp folder in Settings."),
);
}
let missing = self.missing_files();
let (label, path) = missing.first()?;
let more = match missing.len() {
1 => String::new(),
n => format!(" (and {} more)", n - 1),
};
Some(
AppError::new(ErrorCode::MissingModel, format!("{label} not found: {}{more}", path.display()))
.suggest("If it is on a drive that is not connected, connect it and try again. Otherwise open Setup to find the file again, choose other files, or download the missing ones."),
)
}
/// VRAM (MiB) the user's own files take beyond the official ones, which the planner's
/// budgets were measured with: a larger diffusion model (and, with unified memory, a larger
/// text encoder) leaves less room for the images. 0 for the official files.
pub fn model_vram_extra_mib(&self, unified: bool) -> u64 {
let p = self.profile();
if p.is_official() {
return 0;
}
let size = |f: &Path| std::fs::metadata(f).map(|m| m.len()).unwrap_or(0);
let te = size(&p.text_encoder) + p.vision_projector.as_deref().map(size).unwrap_or(0);
extra_weights_mib(size(&p.diffusion_model), te, unified)
}
pub fn relocate_paths(&mut self, old: &Path, new: &Path) {
relocate(&mut self.sdcpp_dir, old, new);
for p in &mut self.profiles {
for f in [&mut p.diffusion_model, &mut p.vae, &mut p.text_encoder] {
relocate(f, old, new);
}
if let Some(v) = p.vision_projector.as_mut() {
relocate(v, old, new);
}
}
}
pub fn preset(&self) -> &'static crate::catalog::Preset {
crate::catalog::preset(&self.hardware_preset).unwrap_or_else(|| crate::catalog::preset(crate::catalog::DEFAULT_PRESET).unwrap())
}
/// Uses `preset`'s runtime settings, and its files for the official profile (tuning kept).
/// The active profile stays: a preset never replaces the user's own files. Setup also calls
/// [`Self::use_official`] when it installs the official files.
pub fn apply_preset(&mut self, preset: &crate::catalog::Preset) {
self.hardware_preset = preset.id.into();
self.text_encoder_placement = preset.text_encoder_placement;
self.vram_reserve_gib = preset.vram_reserve_gib;
self.normalize();
}
/// VRAM the planner should assume: the override when set, otherwise the detected size.
pub fn planning_vram_mib(&self, detected: Option<u64>) -> Option<u64> {
if self.vram_override_mib > 0 { Some(self.vram_override_mib) } else { detected }
}
/// Folder of the active stable-diffusion.cpp build.
pub fn engine_dir(&self) -> PathBuf {
match self.gpu_backend.engine_subdir() {
"" => self.sdcpp_dir.clone(),
sub => self.sdcpp_dir.join(sub),
}
}
pub fn server_exe(&self) -> PathBuf {
if self.uses_mac_engine() {
return self.mac_engine_exe();
}
self.engine_dir().join(if cfg!(windows) { "sd-server.exe" } else { "sd-server" })
}
/// Kokon's Mac engine, on or off: the copy inside the app (next to kokon-service; `tauri dev` puts one there too),
/// else the one `engine-mac/tools/install-dev.sh` puts in the stable-diffusion.cpp folder.
pub fn mac_engine_exe(&self) -> PathBuf {
let here = std::env::current_exe().ok().and_then(|e| e.parent().map(Path::to_path_buf));
mac_engine_in(here.as_deref(), &self.sdcpp_dir)
}
/// Kokon's Mac engine runs instead of sd-server: chosen in Settings, on the Metal backend only.
pub fn uses_mac_engine(&self) -> bool {
self.mac_engine && self.gpu_backend == GpuBackend::Metal
}
/// The configured device when it belongs to the active engine, else its first GPU.
pub fn effective_device(&self) -> String {
let dev = self.device.trim().to_ascii_lowercase();
let prefix = self.gpu_backend.device_prefix();
match dev.strip_prefix(prefix) {
Some(i) if !i.is_empty() && i.chars().all(|c| c.is_ascii_digit()) => dev,
// Engines number their devices independently: fall back to the first one.
_ => format!("{prefix}0"),
}
}
/// `--vae-tile-size` the engine runs with: the setting, at most
/// [`crate::planner::VULKAN_VAE_TILE`] on Vulkan; 0 = no server-side tiling.
pub fn server_vae_tile_size(&self) -> u32 {
match self.gpu_backend {
GpuBackend::Vulkan => self.vae_tile_size.min(crate::planner::VULKAN_VAE_TILE),
_ => self.vae_tile_size,
}
}
/// SageAttention is requested and the engine and card support it.
pub fn uses_sage_attention(&self) -> bool {
self.sage_attention && !self.sage_unsupported && self.gpu_backend == GpuBackend::Cuda
}
/// Folder of the upscaler (`--hires-upscalers-dir`).
/// Kokon's copies of the user's LoRAs (`--lora-model-dir`). Not `models/loras`, where users
/// and tools keep their own files: the engine would list those too.
pub fn lora_dir(&self) -> PathBuf {
self.sdcpp_dir.join("models").join("kokon-loras")
}
pub fn upscalers_dir(&self) -> PathBuf {
crate::catalog::join_rel(&self.sdcpp_dir, crate::catalog::UPSCALERS_SUBDIR)
}
/// The upscaler that runs (name, file): the chosen model when its file is in the upscalers
/// folder (sd-server resolves `<dir>/<name>.<ext>` the same way), else the bundled MoSR.
pub fn upscaler(&self) -> Option<(String, PathBuf)> {
let name = self.upscaler_model.trim();
if name == LANCZOS {
return None;
}
let dir = self.upscalers_dir();
if !name.is_empty() && name != crate::catalog::UPSCALER_NAME {
if let Some(p) = UPSCALER_EXTENSIONS.iter().map(|e| dir.join(format!("{name}.{e}"))).find(|p| p.is_file()) {
return Some((name.to_string(), p));
}
}
let d = crate::catalog::UPSCALER;
d.is_present(&self.sdcpp_dir).then(|| (crate::catalog::UPSCALER_NAME.to_string(), d.path(&self.sdcpp_dir)))
}
/// The file of [`Self::upscaler`].
pub fn upscaler_file(&self) -> Option<PathBuf> {
self.upscaler().map(|(_, p)| p)
}
/// A save from a browser (another device) changes the app's settings, not the computer's:
/// folders, model files, ports, engine arguments and network access keep their values in
/// `current`. Those take a path on the server or decide what runs there, and only the
/// desktop app (or the config file) sets them.
pub fn keep_computer_settings(&mut self, current: &AppConfig) {
self.sdcpp_dir = current.sdcpp_dir.clone();
self.output_dir = current.output_dir.clone();
self.profiles = current.profiles.clone();
self.active_profile = current.active_profile.clone();
self.extra_server_args = current.extra_server_args.clone();
self.server_port = current.server_port;
self.service_port = current.service_port;
self.remote_access = current.remote_access;
self.remote_port = current.remote_port;
}
pub fn validate(&self) -> Result<(), AppError> {
if self.server_port == self.service_port {
return Err(AppError::new(ErrorCode::InvalidConfig, "The inference server and the app service cannot use the same port."));
}
if self.remote_port == self.server_port || self.remote_port == self.service_port {
return Err(AppError::new(ErrorCode::InvalidConfig, "The port for other devices must differ from the app's own ports."));
}
if self.server_port < 1024 || self.service_port < 1024 || self.remote_port < 1024 {
return Err(AppError::new(ErrorCode::InvalidConfig, "Ports must be 1024 or higher."));
}
if !(0.0..=64.0).contains(&self.vram_reserve_gib) {
return Err(AppError::new(ErrorCode::InvalidConfig, "VRAM reserve must be between 0 and 64 GiB."));
}
if self.device.trim().is_empty() || !self.device.chars().all(|c| c.is_ascii_alphanumeric()) {
return Err(AppError::new(ErrorCode::InvalidConfig, "Device must be a backend name such as cuda0."));
}
if self.prefix_cache_type.is_empty() || !self.prefix_cache_type.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
return Err(AppError::new(ErrorCode::InvalidConfig, "Prefix cache type must be auto, off, or a weight type such as q8_0 or f16."));
}
if self.profiles.is_empty() {
return Err(AppError::new(ErrorCode::InvalidConfig, "No model profile configured."));
}
if !(0.0..=1.0).contains(&self.upscale_blend) {
return Err(AppError::new(ErrorCode::InvalidConfig, "Upscaler blend must be between 0 and 100 %."));
}
if self.vram_override_mib != 0 && !(4096..=196_608).contains(&self.vram_override_mib) {
return Err(AppError::new(ErrorCode::InvalidConfig, "Simulated VRAM must be between 4096 and 196608 MiB (or 0 to detect it)."));
}
let max = crate::enhancer::MAX_SYSTEM_PROMPT_CHARS;
if [&self.enhancer_t2i_prompt, &self.enhancer_edit_prompt, &self.enhancer_compose_prompt].iter().any(|p| p.chars().count() > max) {
return Err(AppError::new(ErrorCode::InvalidConfig, format!("Prompt enhancer instructions can be at most {max} characters.")));
}
Ok(())
}
}
/// [`AppConfig::model_vram_extra_mib`] for files of these sizes (bytes; text encoder plus
/// vision projector together). Smaller files give nothing back: the budgets stay as measured
/// (with the Q4_K; the default Q4_K_M counts its extra ~140 MiB).
fn extra_weights_mib(diffusion: u64, text_encoder: u64, unified: bool) -> u64 {
use crate::catalog::{TEXT_ENCODER_Q4_K_M, TURBO_Q4_K, VISION_PROJECTOR};
let mut extra = diffusion.saturating_sub(TURBO_Q4_K.size);
if unified {
extra += text_encoder.saturating_sub(TEXT_ENCODER_Q4_K_M.size + VISION_PROJECTOR.size);
}
extra >> 20
}
/// See [`AppConfig::mac_engine_exe`]: `app_dir` is kokon-service's folder.
fn mac_engine_in(app_dir: Option<&Path>, sdcpp_dir: &Path) -> PathBuf {
app_dir.map(|d| d.join(MAC_ENGINE_EXE)).filter(|p| p.is_file()).unwrap_or_else(|| sdcpp_dir.join(MAC_ENGINE_DIR).join(MAC_ENGINE_EXE))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn mac_engine_inside_the_app_first() {
let app = tempfile::tempdir().unwrap();
let sdcpp = tempfile::tempdir().unwrap();
let dev = sdcpp.path().join(MAC_ENGINE_DIR).join(MAC_ENGINE_EXE);
assert_eq!(mac_engine_in(Some(app.path()), sdcpp.path()), dev);
assert_eq!(mac_engine_in(None, sdcpp.path()), dev);
std::fs::write(app.path().join(MAC_ENGINE_EXE), b"").unwrap();
assert_eq!(mac_engine_in(Some(app.path()), sdcpp.path()), app.path().join(MAC_ENGINE_EXE));
}
/// Empty files at every path of `p`.
fn touch_files(p: &ModelProfile) {
for (_, f, _) in p.files() {
std::fs::create_dir_all(f.parent().unwrap()).unwrap();
std::fs::write(f, b"").unwrap();
}
}
fn own_files(dir: &Path) -> ModelProfile {
let m = dir.join("ComfyUI").join("models");
ModelProfile::user(m.join("diffusion_models").join("turbo_int8.safetensors"), m.join("vae").join("vae.safetensors"), m.join("text_encoders").join("qwen3vl_fused.safetensors"), None)
}
#[test]
fn enhancer_prompts_default_blank_and_are_capped() {
let mut c = AppConfig::default();
assert!(c.enhancer_t2i_prompt.is_empty() && c.enhancer_edit_prompt.is_empty(), "built-in by default");
// Older settings files have no such keys.
let old: AppConfig = serde_json::from_str(r#"{"schemaVersion":9}"#).unwrap();
assert!(old.enhancer_edit_prompt.is_empty() && old.enhancer_compose_prompt.is_empty());
// A restored default is saved blank, so it follows future defaults; a custom one stays.
c.enhancer_t2i_prompt = format!("{}\n", crate::enhancer::T2I_SYSTEM_PROMPT);
c.enhancer_edit_prompt = "Retouch jewelry only.".into();
c.normalize();
assert_eq!((c.enhancer_t2i_prompt.as_str(), c.enhancer_edit_prompt.as_str()), ("", "Retouch jewelry only."));
let v = serde_json::to_value(&c).unwrap();
assert_eq!(v["enhancerEditPrompt"], "Retouch jewelry only.");
assert!(c.validate().is_ok());
c.enhancer_compose_prompt = format!(" {} ", crate::enhancer::COMPOSE_SYSTEM_PROMPT);
c.normalize();
assert!(c.enhancer_compose_prompt.is_empty());
c.enhancer_edit_prompt = "x".repeat(crate::enhancer::MAX_SYSTEM_PROMPT_CHARS + 1);
assert!(c.validate().is_err());
c.enhancer_edit_prompt.clear();
c.enhancer_compose_prompt = "x".repeat(crate::enhancer::MAX_SYSTEM_PROMPT_CHARS + 1);
assert!(c.validate().is_err());
}
#[test]
fn hand_edited_official_paths_move_to_the_user_profile() {
let dir = tempfile::tempdir().unwrap();
let sd = dir.path().join("sd");
let mine = own_files(dir.path());
touch_files(&mine);
// badraymen's config (#14): the official profile pointed at ComfyUI files by hand.
let mut old = AppConfig { sdcpp_dir: sd.clone(), schema_version: 8, ..AppConfig::default() };
old.normalize();
let p = &mut old.profiles[0];
(p.diffusion_model, p.vae, p.text_encoder, p.vision_projector) = (mine.diffusion_model.clone(), mine.vae.clone(), mine.text_encoder.clone(), None);
p.backend_args = vec!["--x".into()];
let path = dir.path().join("config.json");
old.save_to(&path).unwrap();
let c = AppConfig::load_from(&path);
assert_eq!(c.active_profile, USER_PROFILE_ID, "the edited files stay in use");
let user = c.profile();
assert_eq!((user.source, user.diffusion_model.clone(), user.vision_projector.clone()), (ProfileSource::User, mine.diffusion_model.clone(), None));
assert_eq!(user.backend_args, vec!["--x".to_string()]);
assert_eq!(user.model, QWEN_IMAGE_21);
let off = c.profiles.iter().find(|p| p.id == OFFICIAL_PROFILE_ID).unwrap();
assert!(off.same_files(&ModelProfile::official(&sd, c.preset())) && off.is_official(), "the official profile is official again");
c.save_to(&path).unwrap();
assert_eq!(AppConfig::load_from(&path), c, "nothing changes on the next load");
// Edited paths whose files are gone are not kept: back to the official files.
std::fs::remove_file(&mine.vae).unwrap();
old.save_to(&path).unwrap();
let c = AppConfig::load_from(&path);
assert_eq!((c.active_profile.as_str(), c.profiles.len()), (OFFICIAL_PROFILE_ID, 1));
assert!(c.profile().same_files(&ModelProfile::official(&sd, c.preset())));
}
#[test]
fn presets_never_replace_the_users_files() {
let dir = tempfile::tempdir().unwrap();
let mut c = AppConfig { sdcpp_dir: dir.path().join("sd"), ..AppConfig::default() };
c.normalize();
let mut mine = own_files(dir.path());
mine.scan_dir = Some(dir.path().join("ComfyUI"));
c.set_user_files(mine.clone());
c.profiles.iter_mut().find(|p| p.id == USER_PROFILE_ID).unwrap().recommended_settings.area_fast = 768 * 768;
c.apply_preset(crate::catalog::preset("32gb").unwrap());
assert_eq!(c.active_profile, USER_PROFILE_ID);
assert_eq!((c.profile().text_encoder.clone(), c.hardware_preset.as_str()), (mine.text_encoder.clone(), "32gb"));
let off = c.profiles.iter().find(|p| p.id == OFFICIAL_PROFILE_ID).unwrap();
assert!(off.text_encoder.ends_with("Qwen3VL-8B-Instruct-Q8_0.gguf"), "the official profile follows the preset");
// Choosing files again keeps the tuning; switching to the official files keeps them.
c.set_user_files(own_files(dir.path()));
assert_eq!(c.profile().recommended_settings.area_fast, 768 * 768);
assert_eq!(c.profiles.len(), 2);
c.use_official();
assert_eq!(c.active_profile, OFFICIAL_PROFILE_ID);
assert!(c.user_profile().is_some(), "the user's profile is never deleted");
// The official files follow the folder.
c.sdcpp_dir = dir.path().join("elsewhere");
c.normalize();
assert!(c.profile().diffusion_model.starts_with(dir.path().join("elsewhere")));
// An active profile that is gone falls back to the official one.
c.active_profile = "nope".into();
c.normalize();
assert_eq!(c.active_profile, OFFICIAL_PROFILE_ID);
}
#[test]
fn missing_files_are_reported() {
let dir = tempfile::tempdir().unwrap();
let mut c = AppConfig { sdcpp_dir: dir.path().join("sd"), ..AppConfig::default() };
c.normalize();
assert!(c.missing_files_error().unwrap().message.contains("sd-server"), "the engine first");
std::fs::create_dir_all(c.engine_dir()).unwrap();
std::fs::write(c.server_exe(), b"").unwrap();
let mine = own_files(dir.path());
c.set_user_files(mine.clone());
assert_eq!(c.missing_files().len(), 3);
let e = c.missing_files_error().unwrap();
assert_eq!(e.code, ErrorCode::MissingModel);
assert!(e.message.starts_with("Diffusion model not found") && e.message.ends_with("(and 2 more)"), "{}", e.message);
touch_files(&mine);
assert!(c.missing_files().is_empty() && c.missing_files_error().is_none());
}
#[test]
fn larger_own_files_take_planning_memory() {
use crate::catalog::{TEXT_ENCODER_Q8_0, TURBO_Q4_K};
assert_eq!(extra_weights_mib(TURBO_Q4_K.size, 0, false), 0);
assert_eq!(extra_weights_mib(TURBO_Q4_K.size / 2, 0, false), 0, "smaller files give nothing back");
assert_eq!(extra_weights_mib(TURBO_Q4_K.size + (6 << 30), 0, false), 6 * 1024);
assert_eq!(extra_weights_mib(0, TEXT_ENCODER_Q8_0.size, false), 0, "the text encoder sits in system RAM");
assert!(extra_weights_mib(0, TEXT_ENCODER_Q8_0.size, true) > 2000, "unified memory: it shares the GPU's memory");
// The official profile is what the budgets were measured with.
assert_eq!(AppConfig::default().model_vram_extra_mib(true), 0);
}
#[test]
fn defaults_match_spec() {
let c = AppConfig::default();
let p = c.profile();
assert_eq!(p.id, OFFICIAL_PROFILE_ID);
assert!(p.diffusion_model.starts_with(default_sdcpp_dir()));
// A new install (no earlier model file in the folder) gets the Q4_K_M.
let dir = tempfile::tempdir().unwrap();
let mut fresh = AppConfig { sdcpp_dir: dir.path().to_path_buf(), ..AppConfig::default() };
fresh.normalize();
assert_eq!(fresh.profile().display_name, "Qwen-Image 2.1 Turbo Q4_K_M (official)");
assert!(fresh.profile().diffusion_model.ends_with("qwen-image-2.1-turbo-Q4_K_M.gguf"));
assert_eq!(c.hardware_preset, "16gb");
assert_eq!(c.planning_vram_mib(Some(16303)), Some(16303));
assert_eq!(c.device, "cuda0");
assert_eq!(c.vram_reserve_gib, 1.0);
assert!(c.flash_attention);
assert!(!c.keep_server_running);
assert!(c.validate().is_ok());
assert_eq!(p.files().len(), 4);
assert_eq!(c.upscale_tile_size, 0, "automatic");
let default_model = if cfg!(target_os = "macos") { "lanczos" } else { "4x_NMKD-Superscale-SP_178000_G" };
assert_eq!((c.upscaler_model.as_str(), c.upscale_blend, c.upscale_prescale), (default_model, 1.0, false));
assert_eq!(c.upscalers_dir(), default_sdcpp_dir().join("models").join("upscalers"));
}
#[test]
fn engine_choice_sets_folder_device_and_flags() {
let mut c = AppConfig::default();
c.gpu_backend = GpuBackend::Cuda;
assert_eq!(c.engine_dir(), c.sdcpp_dir);
assert_eq!(c.effective_device(), "cuda0");
assert!(c.uses_sage_attention());
c.sage_unsupported = true;
assert!(!c.uses_sage_attention(), "pre-Ampere card");
let saved: AppConfig = serde_json::from_str(&serde_json::to_string(&c).unwrap()).unwrap();
assert!(!saved.sage_unsupported, "detected per run, not read back");
c.sage_unsupported = false;
c.gpu_backend = GpuBackend::Vulkan;
assert_eq!(c.engine_dir(), c.sdcpp_dir.join("engine-vulkan"));
assert!(c.server_exe().starts_with(c.sdcpp_dir.join("engine-vulkan")));
assert_eq!(c.effective_device(), "vulkan0", "a CUDA device name maps to the first Vulkan GPU");
c.device = "Vulkan1".into();
assert_eq!(c.effective_device(), "vulkan1");
c.device = "vulkan".into();
assert_eq!(c.effective_device(), "vulkan0");
assert!(!c.uses_sage_attention(), "SageAttention is CUDA only");
assert_eq!(GpuBackend::for_vendor("nvidia"), GpuBackend::Cuda);
assert_eq!(GpuBackend::for_vendor("amd"), GpuBackend::Vulkan);
assert_eq!(GpuBackend::for_vendor("apple"), GpuBackend::Metal);
c.gpu_backend = GpuBackend::Metal;
c.device = "cuda0".into();
assert_eq!(c.effective_device(), "mtl0", "matches MTL0 in --list-devices");
assert_eq!(c.engine_dir(), c.sdcpp_dir.join("engine-metal"));
assert!(!c.uses_sage_attention());
// Configs written before the field existed keep this platform's engine.
let old: AppConfig = serde_json::from_str("{}").unwrap();
assert_eq!(old.gpu_backend, if cfg!(target_os = "macos") { GpuBackend::Metal } else { GpuBackend::Cuda });
let json = serde_json::to_string(&c).unwrap();
assert!(json.contains(r#""gpuBackend":"metal""#));
}
#[test]
fn official_profile_is_added_but_not_forced() {
let dir = tempfile::tempdir().unwrap();
let p = dir.path().join("config.json");
let old = r#"{"schemaVersion":4,"sdcppDir":"D:\\sd","activeProfile":"uc","profiles":[{"id":"uc","displayName":"UC","diffusionModel":"D:\\sd\\uc.gguf"}]}"#;
std::fs::write(&p, old).unwrap();
let c = AppConfig::load_from(&p);
assert_eq!(c.active_profile, "uc", "the user's choice stays active");
let off = c.profiles.iter().find(|p| p.id == OFFICIAL_PROFILE_ID).unwrap();
// Catalog paths are joined per component, so the separator is the platform's own.
let sd = |f: &str| crate::catalog::join_rel(Path::new(r"D:\sd"), &format!("models/qwen21/{f}"));
assert_eq!(off.diffusion_model, sd("qwen-image-2.1-turbo-Q4_K_M.gguf"));
// Saved again, nothing is added twice.
c.save_to(&p).unwrap();
assert_eq!(AppConfig::load_from(&p).profiles.len(), 2);
// A file without profiles uses its own folder and preset.
std::fs::write(&p, r#"{"sdcppDir":"D:\\sd","hardwarePreset":"24gb"}"#).unwrap();
let c = AppConfig::load_from(&p);
assert_eq!(c.profile().diffusion_model, sd("qwen-image-2.1-turbo-Q4_K_M.gguf"));
}
#[test]
fn old_folders_move_to_the_new_name() {
let base = tempfile::tempdir().unwrap();
std::fs::create_dir_all(base.path().join("QwenLocalStudio").join("inputs")).unwrap();
std::fs::write(base.path().join("QwenLocalStudio").join("gallery.db"), b"db").unwrap();
let d = migrate_dir(base.path(), "QwenLocalStudio", "KokonData");
assert_eq!(d, base.path().join("KokonData"));
assert!(d.join("gallery.db").is_file() && !base.path().join("QwenLocalStudio").exists());
// Once moved, nothing happens again; a fresh install just gets the new name.
assert_eq!(migrate_dir(base.path(), "QwenLocalStudio", "KokonData"), d);
assert_eq!(migrate_dir(base.path(), "Missing", "New"), base.path().join("New"));
// Model paths inside the moved folder follow it; others stay.
let (old, new) = (base.path().join("QwenLocalStudio"), d.clone());
let mut c = AppConfig::default();
c.sdcpp_dir = old.join("sdcpp");
c.apply_preset(crate::catalog::preset("16gb").unwrap());
c.profiles.push(ModelProfile { id: "mine".into(), diffusion_model: PathBuf::from(r"C:\AI\sdcpp\x.gguf"), ..ModelProfile::default() });
c.relocate_paths(&old, &new);
assert_eq!(c.sdcpp_dir, new.join("sdcpp"));
assert!(c.profile().diffusion_model.starts_with(new.join("sdcpp")));
assert_eq!(c.profiles[1].diffusion_model, PathBuf::from(r"C:\AI\sdcpp\x.gguf"));
}
#[test]
fn presets_switch_weights_and_keep_tuning() {
let dir = tempfile::tempdir().unwrap();
let mut c = AppConfig { sdcpp_dir: dir.path().to_path_buf(), ..AppConfig::default() };
c.profiles[0].recommended_settings.area_fast = 768 * 768;
c.apply_preset(crate::catalog::preset("32gb").unwrap());
let p = c.profile();
assert!(p.diffusion_model.ends_with("qwen-image-2.1-turbo-Q4_K_M.gguf"), "4-bit Turbo on every preset");
assert!(p.text_encoder.ends_with("Qwen3VL-8B-Instruct-Q8_0.gguf"));
assert_eq!(p.display_name, "Qwen-Image 2.1 Turbo Q4_K_M (official)");
assert_eq!(p.recommended_settings.area_fast, 768 * 768);
assert_eq!((c.hardware_preset.as_str(), c.profiles.len()), ("32gb", 1));
c.vram_override_mib = 12_288;
assert_eq!(c.planning_vram_mib(Some(16303)), Some(12_288));
assert!(c.validate().is_ok());
c.vram_override_mib = 100;
assert!(c.validate().is_err());
}
#[test]
fn schema_8_migration() {
let dir = tempfile::tempdir().unwrap();
let p = dir.path().join("config.json");
let old = r#"{"schemaVersion":7,"sdcppDir":"D:\\sd","upscalersDir":"E:\\esrgan","upscalerModel":"4x_NMKD-Superscale-SP_178000_G","upscaleTileSize":256}"#;
std::fs::write(&p, old).unwrap();
let c = AppConfig::load_from(&p);
assert_eq!(c.schema_version, SCHEMA_VERSION);
assert_eq!(c.upscale_tile_size, 0, "ESRGAN tile sizes reset to automatic");
assert_eq!(c.upscalers_dir(), crate::catalog::join_rel(Path::new(r"D:\sd"), "models/upscalers"), "the custom folder is no longer used");
assert_eq!(c.upscaler_model, "4x_NMKD-Superscale-SP_178000_G", "the model choice is kept");
assert!(!serde_json::to_string(&c).unwrap().contains("upscalersDir"), "the folder key is dropped on save");
std::fs::write(&p, r#"{"schemaVersion":7,"upscalerModel":"4x-UltraSharp"}"#).unwrap();
assert_eq!(AppConfig::load_from(&p).upscaler_model, DEFAULT_UPSCALER, "0.9.0's default moves to the new one");
// A tile size chosen after the change is kept.
std::fs::write(&p, r#"{"schemaVersion":8,"upscaleTileSize":512}"#).unwrap();
assert_eq!(AppConfig::load_from(&p).upscale_tile_size, 512);
}
#[test]
fn base_model_installs_move_to_turbo() {
let dir = tempfile::tempdir().unwrap();
let p = dir.path().join("config.json");
let old = r#"{"schemaVersion":6,"sdcppDir":"D:\\sd","hardwarePreset":"24gb","activeProfile":"qwen-image-2.1","profiles":[
{"id":"qwen-image-2.1","displayName":"Qwen-Image 2.1 Q8_0 (official)","diffusionModel":"D:\\sd\\models\\qwen21\\qwen-image-2.1-Q8_0.gguf","backendArgs":["--x"],
"recommendedSettings":{"steps_fast":20,"steps_ultra":40,"cfg":1.0,"area_ultra":4194304,"area_fast":1048576}},
{"id":"mine","diffusionModel":"D:\\sd\\mine.gguf","recommendedSettings":{"area_quality":1000000}}]}"#;
std::fs::write(&p, old).unwrap();
let c = AppConfig::load_from(&p);
let off = c.profile();
assert_eq!(off.diffusion_model, crate::catalog::join_rel(Path::new(r"D:\sd"), "models/qwen21/qwen-image-2.1-turbo-Q4_K_M.gguf"));
assert_eq!(off.display_name, "Qwen-Image 2.1 Turbo Q4_K_M (official)");
assert_eq!(off.backend_args, vec!["--x".to_string()], "launch flags stay");
assert_eq!(off.recommended_settings, RecommendedSettings::default());
let mine = c.profiles.iter().find(|p| p.id == "mine").unwrap();
assert_eq!(mine.diffusion_model, PathBuf::from(r"D:\sd\mine.gguf"), "other profiles keep their model");
assert_eq!(mine.recommended_settings, RecommendedSettings::default());
assert_eq!(c.schema_version, SCHEMA_VERSION);
}
#[test]
fn upscaler_file_lookup() {
let dir = tempfile::tempdir().unwrap();
let mut c = AppConfig::default();
c.sdcpp_dir = dir.path().to_path_buf();
c.upscaler_model = UPSCALER_CHOICES[0].0.into(); // the PC default (Macs: Lanczos)
assert!(c.upscaler_file().is_none());
std::fs::create_dir_all(c.upscalers_dir()).unwrap();
let f = c.upscalers_dir().join("4xNomos2_hq_mosr.pth");
std::fs::write(&f, b"partial").unwrap();
assert!(c.upscaler_file().is_none(), "a partial file is not installed");
std::fs::File::create(&f).unwrap().set_len(crate::catalog::UPSCALER.size).unwrap();
assert_eq!(c.upscaler().unwrap(), ("4xNomos2_hq_mosr".to_string(), f.clone()), "the chosen model is missing: the bundled MoSR runs");
let ss = c.upscalers_dir().join("4x_NMKD-Superscale-SP_178000_G.pth");
std::fs::write(&ss, b"x").unwrap();
assert_eq!(c.upscaler().unwrap(), ("4x_NMKD-Superscale-SP_178000_G".to_string(), ss));
c.upscaler_model = "4xNomos2_hq_mosr".into();
assert_eq!(c.upscaler_file().unwrap(), f);
c.upscaler_model = LANCZOS.into();
assert_eq!(c.upscaler(), None, "a plain resize, even with models installed");
c.upscale_blend = 1.5;
assert!(c.validate().is_err());
// Older config files without the new fields keep loading with defaults.
let old: AppConfig = serde_json::from_str(r#"{"serverPort": 41000, "vaeTileSize": 512}"#).unwrap();
assert_eq!(old.profile().recommended_settings.area_quality, 2048 * 2048);
}
#[test]
fn eight_gb_preset_reserves_more_vram() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("config.json");
let load = |json: &str| {
std::fs::write(&path, json).unwrap();
AppConfig::load_from(&path).vram_reserve_gib
};
assert_eq!(load(r#"{"schemaVersion": 9, "hardwarePreset": "8gb", "vramReserveGib": 1.0}"#), 1.5);
assert_eq!(load(r#"{"schemaVersion": 9, "hardwarePreset": "8gb", "vramReserveGib": 2.0}"#), 2.0, "set by hand");
assert_eq!(load(r#"{"schemaVersion": 9, "hardwarePreset": "16gb", "vramReserveGib": 1.0}"#), 1.0);
assert_eq!(load(r#"{"schemaVersion": 10, "hardwarePreset": "8gb", "vramReserveGib": 1.0}"#), 1.0, "chosen after the migration");
let mut c = AppConfig::default();
c.apply_preset(crate::catalog::preset("8gb").unwrap());
assert_eq!(c.vram_reserve_gib, 1.5);
c.apply_preset(crate::catalog::preset("12gb").unwrap());
assert_eq!(c.vram_reserve_gib, 1.0);
}
#[test]
fn roundtrip_and_partial_files() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("config.json");
let mut c = AppConfig::default();
c.server_port = 40000;
c.ui = serde_json::json!({"quality": "fast"});
c.save_to(&path).unwrap();
assert_eq!(AppConfig::load_from(&path), c);
std::fs::write(&path, r#"{"serverPort": 41000}"#).unwrap();
let p = AppConfig::load_from(&path);
assert_eq!(p.server_port, 41000);
assert_eq!(p.profiles.len(), 1);
std::fs::write(&path, "\u{feff}{\"serverPort\": 42000}").unwrap();
assert_eq!(AppConfig::load_from(&path).server_port, 42000, "UTF-8 BOM accepted");
std::fs::write(&path, "{ broken").unwrap();
assert_eq!(AppConfig::load_from(&path), AppConfig::default());
assert!(path.with_extension("json.invalid").exists());
}
#[test]
fn validation() {
let mut c = AppConfig::default();
c.service_port = c.server_port;
assert!(c.validate().is_err());
let mut c = AppConfig::default();
c.remote_port = c.service_port;
assert!(c.validate().is_err());
let mut c = AppConfig::default();
c.device = "cuda0; rm".into();
assert!(c.validate().is_err());
}
/// A 0.10.2 config file (no network fields) loads with access from other devices off.
#[test]
fn config_from_0_10_2_keeps_network_access_off() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("config.json");
let old = r#"{"schemaVersion": 10, "serverPort": 39150, "servicePort": 39151, "setupComplete": true,
"hardwarePreset": "16gb", "outputDir": "/home/me/Pictures/Kokon", "ui": {"quality": "balanced"}}"#;
std::fs::write(&path, old).unwrap();
let c = AppConfig::load_from(&path);
assert!(!c.remote_access);
assert_eq!(c.remote_port, DEFAULT_REMOTE_PORT);
assert!(c.setup_complete);
assert_eq!(c.output_dir, PathBuf::from("/home/me/Pictures/Kokon"));
assert_eq!(c.ui["quality"], "balanced");
assert!(c.validate().is_ok());
}
#[test]
fn browser_saves_keep_the_computers_settings() {
let current = AppConfig { remote_access: true, extra_server_args: vec!["--x".into()], ..AppConfig::default() };
let mut sent = current.clone();
sent.sdcpp_dir = PathBuf::from("/tmp/evil");
sent.output_dir = PathBuf::from("/etc");
sent.extra_server_args = vec!["--rpc".into()];
sent.profiles[0].diffusion_model = PathBuf::from("/etc/passwd");
sent.service_port = 40000;
sent.remote_access = false;
sent.remote_port = 40001;
sent.flash_attention = !current.flash_attention;
sent.keep_computer_settings(¤t);
let mut expected = current.clone();
expected.flash_attention = sent.flash_attention;
assert_eq!(sent, expected, "only the app setting changed");
}
}