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.

Upscalers: Superscale-SP by default, MoSR (experimental, bundled), strength slider, comparison; engine kokon-mosr-1

Gabriele Lozuponeac77872afa43
diff --git a/.gitignore b/.gitignore
index da65a2c..b2a8eff 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,8 @@ node_modules
/mcp/build
/src-tauri/target
/src-tauri/binaries/*.exe
+# Model files bundled with the app, fetched at build time (scripts/release/fetch-bundled.mjs)
+/src-tauri/resources/*.pth
*.log
/.test-data
/dist-release
diff --git a/NOTICE b/NOTICE
index a391417..222eae1 100644
--- a/NOTICE
+++ b/NOTICE
@@ -5,8 +5,9 @@ This product is licensed under the GNU Affero General Public License, version 3
(AGPL-3.0-only, see LICENSE). Commercial licenses for uses the AGPL does not allow are
available from the copyright holder (see the README).
-Model weights and the upscaler that Kokon downloads at setup are not part of this product;
-they come from their authors under their own licenses (see the README).
+Model weights that Kokon downloads at setup are not part of this product; they come from
+their authors under their own licenses (see the README). The upscaler model included in the
+installer keeps its own license too (CC BY 4.0, see below).
Third-party software included in the Kokon installer
@@ -24,6 +25,12 @@ Third-party software included in the Kokon installer
and Zod (https://zod.dev), MIT, bundled in kokon-mcp.
- Other Rust crates and npm packages, each under its own license as listed in Cargo.lock,
package-lock.json and mcp/package-lock.json.
+- 4xNomos2_hq_mosr upscaler model by Philip Hofmann (Phhofm), from
+ https://github.com/Phhofm/models/releases/tag/4xNomos2_hq_mosr, licensed under the
+ Creative Commons Attribution 4.0 International License (CC BY 4.0,
+ https://creativecommons.org/licenses/by/4.0/). Included unmodified; Setup downloads the same
+ file from a mirror (https://github.com/GabrieleLozupone/kokon/releases/tag/models-1) if the
+ installed copy is missing.
Downloaded by the setup screen (not part of this product)
@@ -31,8 +38,10 @@ Downloaded by the setup screen (not part of this product)
Every file is pinned by URL, size and SHA-256 in crates/qls-core/src/catalog.rs.
-- stable-diffusion.cpp by leejet (https://github.com/leejet/stable-diffusion.cpp), MIT,
- release master-929-3f8527a: CUDA 12, Vulkan or Metal build.
+- stable-diffusion.cpp by leejet (https://github.com/leejet/stable-diffusion.cpp), MIT:
+ CUDA 12, Vulkan or Metal build of commit 3f8527a with MoSR upscaler support added, from the
+ fork release https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/kokon-mosr-1
+ (proposed upstream as https://github.com/leejet/stable-diffusion.cpp/pull/2128).
- ggml by the ggml authors (https://github.com/ggml-org/ggml), MIT, included in the
stable-diffusion.cpp builds.
- NVIDIA CUDA 12 runtime and cuBLAS DLLs (NVIDIA cards only), redistributed in the
@@ -46,8 +55,7 @@ Every file is pinned by URL, size and SHA-256 in crates/qls-core/src/catalog.rs.
https://huggingface.co/Qwen/Qwen-Image-2.1 for the terms.
- Qwen3-VL 8B Instruct text encoder and vision projector by the Qwen team, from
https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct-GGUF; see that page for the terms.
-- 4x-UltraSharp upscaler by Kim2091 (optional), CC BY-NC-SA 4.0 (non-commercial), from
+- 4x_NMKD-Superscale-SP_178000_G upscaler by Nmkd (the default), WTFPL, from
https://huggingface.co/uwg/upscaler.
-
-Selectable in Settings but not downloaded by Kokon: 4x_NMKD-Superscale-SP_178000_G by NMKD,
-placed by hand from https://huggingface.co/uwg/upscaler; see that page for the terms.
+- 4x-UltraSharp upscaler by Kim2091 (optional, downloaded from Settings), CC BY-NC-SA 4.0
+ (non-commercial), from https://huggingface.co/uwg/upscaler.
diff --git a/README.md b/README.md
index 9df1af6..5acd497 100644
--- a/README.md
+++ b/README.md
@@ -186,8 +186,8 @@ preset later from Settings → Models → **Set up models…**
| 24 GB | Qwen-Image 2.1 Turbo Q4_K | Qwen3-VL 8B Q4_K_M | ~12 GB | not yet |
| 32 GB+ | Qwen-Image 2.1 Turbo Q4_K | Qwen3-VL 8B Q8_0 (8.7 GB) | ~16 GB | not yet |
-Every preset also gets stable-diffusion.cpp (the CUDA 12 build on NVIDIA, the Vulkan build on AMD and Intel, the Metal build on a Mac), the Qwen-Image 2.1 VAE, the
-Qwen3-VL vision projector and, optionally, the 4x-UltraSharp upscaler. The image model is Qwen's
+Every preset also gets stable-diffusion.cpp (the CUDA 12 build on NVIDIA, the Vulkan build on AMD and Intel, the Metal build on a Mac), the Qwen-Image 2.1 VAE and the
+Qwen3-VL vision projector and the Superscale-SP upscaler (67 MB). The image model is Qwen's
official 8-step [Qwen-Image 2.1 Turbo](https://huggingface.co/Qwen/Qwen-Image-2.1-Turbo) through
[DogukanUrker/Qwen-Image-2.1-Turbo-GGUF](https://huggingface.co/DogukanUrker/Qwen-Image-2.1-Turbo-GGUF);
the other sources are
@@ -233,14 +233,14 @@ opened in Explorer or Finder. A few things make that loop fast:
flowchart LR
A["📷 Your photo<br>+ a sentence"] --> B["Planner<br><sub>mode · size · memory budget</sub>"]
B --> C["Qwen-Image 2.1<br><sub>stable-diffusion.cpp<br>on your GPU</sub>"]
- C --> D["AI upscaler<br><sub>ESRGAN, back to<br>full size</sub>"]
+ C --> D["AI upscaler<br><sub>Superscale-SP, back to<br>full size</sub>"]
D --> E["🖼️ Result<br><sub>gallery + recipe</sub>"]
M["🤖 Claude · Cursor · scripts"] -. "MCP / local API" .-> B
```
The planner decides what kind of job your request is, picks a working size that fits your GPU
and runs a single diffusion pass. When the result has to be larger than what the model rendered,
-it is enlarged with ESRGAN instead of a plain resize. For brushed edits, Kokon marks the area on
+it is enlarged with an AI upscaler instead of a plain resize. For brushed edits, Kokon marks the area on
a second reference image so the model knows exactly where to work. Without that, Qwen-Image 2.1
cannot see the mask.
@@ -353,8 +353,8 @@ Full requests (`/jobs`) also accept `"mode": "upscale"` with `"upscale": {"scale
Kokon makes only two kinds of network request:
-- **Setup:** `github.com` for the stable-diffusion.cpp release and `huggingface.co` for the
- models.
+- **Setup:** `github.com` for the stable-diffusion.cpp release (and the MoSR upscaler, if the copy
+ that comes with the app is missing) and `huggingface.co` for the models and the other upscalers.
- **Update check:** at most once a day, the app fetches `latest.json` from this repository's
latest GitHub release, a small file with the newest version number. Nothing about you or your
images is sent. Turn it off on the welcome screen or in Settings → General. Updates are
@@ -468,8 +468,9 @@ image model has its own license: Qwen-Image 2.1 and its Turbo model are released
use**. That includes selling or using commercially the images you make with it. For commercial
use, ask the Qwen team for a license ([email protected]).
-The Qwen3-VL text encoder is Apache-2.0. The optional 4x-UltraSharp upscaler is CC BY-NC-SA
-4.0, also non-commercial only.
+The Qwen3-VL text encoder is Apache-2.0. The default upscaler, Superscale-SP by Nmkd, is WTFPL,
+and the experimental MoSR by Philip Hofmann is CC BY 4.0: both allow commercial use. The optional
+UltraSharp upscaler is CC BY-NC-SA 4.0, non-commercial only.
</details>
@@ -491,12 +492,24 @@ recent Apple systems show them in HDR, and every other viewer shows a normal JPE
<summary><b>Which upscaler is used, and can I change it?</b></summary>
<br>
-Settings → Models offers two ESRGAN models: **UltraSharp** (default, downloaded by the setup
-screen) and **Superscale-SP**. To use Superscale-SP, put
-`4x_NMKD-Superscale-SP_178000_G.pth` from
-[uwg/upscaler](https://huggingface.co/uwg/upscaler/tree/main/ESRGAN) into
-`<stable-diffusion.cpp folder>/models/upscalers/`. Without an upscaler everything still works,
-with a plain resize instead.
+By default **Superscale-SP** by Nmkd (ESRGAN), downloaded by the setup screen. Pick another one
+in the Advanced menu next to the prompt, or in Settings → Models; **Compare upscalers** there
+shows each one on the same crops (a face, a JPEG photo, a night street, text, a landscape, a 4×
+upscale):
+
+- **Superscale-SP** (default): sharp and natural on most images; on JPEG photos and dark areas it
+ can draw a faint grid.
+- **MoSR** (experimental, 17 MB, comes with the app): the fastest, good for 4× upscales, but on
+ clean images enlarged less than about 3× it draws a fine grid. It needs Kokon's build of
+ [stable-diffusion.cpp](https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/kokon-mosr-1)
+ ([pull request](https://github.com/leejet/stable-diffusion.cpp/pull/2128) to the original project).
+- **UltraSharp** (optional download): very clean, but smooths skin into an artificial look and can
+ invent lines. Non-commercial license.
+- **Lanczos**: a plain resize, never invents anything.
+
+**Upscaler strength** (0–100 %) mixes the upscaler's result with a plain resize, to tone down
+texture it invents. Settings → Models also has **Shrink the image before upscaling**, which
+gives the upscaler a smaller image, like the ones it was trained on.
</details>
@@ -638,7 +651,8 @@ Model weights and the upscaler are downloaded from their authors and keep their
Kokon builds on [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) by
leejet, [Qwen-Image 2.1](https://huggingface.co/Qwen/Qwen-Image-2.1) and its Turbo model by the
Qwen team, DogukanUrker's Turbo GGUF conversions, [Tauri](https://tauri.app) and
-4x-UltraSharp by Kim2091. Thank you.
+the upscalers by Nmkd (Superscale-SP), Philip Hofmann (4xNomos2 MoSR) and Kim2091 (UltraSharp).
+Thank you.
<p align="center">
<br>
diff --git a/crates/qls-core/src/catalog.rs b/crates/qls-core/src/catalog.rs
index c3c6ef2..055f3c8 100644
--- a/crates/qls-core/src/catalog.rs
+++ b/crates/qls-core/src/catalog.rs
@@ -2,8 +2,8 @@
//! 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). 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`].
+//! 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};
@@ -23,16 +23,22 @@ pub enum FileKind {
/// stable-diffusion.cpp binaries (a zip extracted into the folder).
Engine,
Model,
- /// Not needed to run (the ESRGAN upscaler; Lanczos is used without it).
- Optional,
}
+/// 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.
+pub const ENGINE_TAG: &str = "kokon-mosr-1";
+/// 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,
@@ -43,6 +49,8 @@ pub struct Download {
/// 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.
@@ -59,57 +67,87 @@ impl Download {
join_rel(sdcpp_dir, self.dest)
}
- /// Installed: a zip's files exist, 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.
+ /// 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() {
- return self.provides.iter().all(|f| join_rel(sdcpp_dir, f).is_file());
+ 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(()),
+ }
+ }
}
-const SDCPP_RELEASE: &str = "https://github.com/leejet/stable-diffusion.cpp/releases/tag/master-929-3f8527a";
+/// Upstream release the CUDA runtime comes from (the fork's build links the same one).
+const SDCPP_UPSTREAM_RELEASE: &str = "https://github.com/leejet/stable-diffusion.cpp/releases/tag/master-929-3f8527a";
+const SDCPP_RELEASE: &str = "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/kokon-mosr-1";
-/// stable-diffusion.cpp commit 3f8527a (2026-09-27): the build every backend fact in the
-/// README was verified on. CUDA 12 build; it runs on RTX 20xx to RTX 50xx.
+/// stable-diffusion.cpp commit 3f8527a (2026-09-27, the build every backend fact in the
+/// README was verified on) plus the MoSR upscaler (fork commit 2e3312d, upstream PR #2128).
+/// Qwen output is bit-identical to 3f8527a. CUDA 12 build; it runs on RTX 20xx to RTX 50xx.
pub const ENGINE_CUDA: Download = Download {
id: "engine_cuda",
label: "stable-diffusion.cpp (CUDA 12)",
kind: FileKind::Engine,
- url: "https://github.com/leejet/stable-diffusion.cpp/releases/download/master-929-3f8527a/sd-master-3f8527a-bin-win-cuda12-x64.zip",
+ url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-mosr-1/sd-mosr-upscaler-2e3312d-bin-win-cuda12-x64.zip",
+ fallback_urls: &[],
page: SDCPP_RELEASE,
- size: 337_915_440,
- sha256: "217d6dead9abd3f827fc338268555cc179234e7e6330ef21ecb1c985e19d2dc7",
- dest: "sd-master-3f8527a-bin-win-cuda12-x64.zip",
+ size: 337_895_587,
+ sha256: "1922fcb034c8f246dbe2c3e4fe5dae6407c0c27df3629558cc8af9dac5adead1",
+ dest: "sd-mosr-upscaler-2e3312d-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.
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",
- page: SDCPP_RELEASE,
+ 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. SHA-256 from GitHub's asset digest, checked against a download 2026-10-09.
+/// CUDA build. SHA-256 from GitHub's asset digest, checked against a download 2026-10-12.
pub const ENGINE_VULKAN: Download = Download {
id: "engine_vulkan",
label: "stable-diffusion.cpp (Vulkan)",
kind: FileKind::Engine,
- url: "https://github.com/leejet/stable-diffusion.cpp/releases/download/master-929-3f8527a/sd-master-3f8527a-bin-win-vulkan-x64.zip",
+ url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-mosr-1/sd-mosr-upscaler-2e3312d-bin-win-vulkan-x64.zip",
+ fallback_urls: &[],
page: SDCPP_RELEASE,
- size: 30_067_605,
- sha256: "60e6850d650417409f18c2170ab5e27335db96da70cd3d1ad1e930bcffc2fd35",
- dest: "engine-vulkan/sd-master-3f8527a-bin-win-vulkan-x64.zip",
+ size: 30_081_934,
+ sha256: "fe6ac9f9b93f3ab081c0d4f7031e4c8dfb6f9d413c748345c6aa8c02c2e3f74b",
+ dest: "engine-vulkan/sd-mosr-upscaler-2e3312d-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),
};
/// Same commit, macOS build: universal binary with the Metal shaders embedded, needs
@@ -118,12 +156,14 @@ pub const ENGINE_METAL: Download = Download {
id: "engine_metal",
label: "stable-diffusion.cpp (Metal)",
kind: FileKind::Engine,
- url: "https://github.com/leejet/stable-diffusion.cpp/releases/download/master-929-3f8527a/sd-master-3f8527a-bin-Darwin-macOS-26.6.2-arm64.zip",
+ url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-mosr-1/sd-mosr-upscaler-2e3312d-bin-Darwin-macOS-26.6.2-arm64.zip",
+ fallback_urls: &[],
page: SDCPP_RELEASE,
- size: 35_049_086,
- sha256: "1c8ee6c8e413e3335b1223bbc657ea5d86dae1819f8426a98b84c265587eb192",
- dest: "engine-metal/sd-master-3f8527a-bin-Darwin-macOS-26.6.2-arm64.zip",
+ size: 35_071_182,
+ sha256: "6a89473230e0f3623c2dcd7815d9578e87b2a0d1871567bd941240fe3662c25e",
+ dest: "engine-metal/sd-mosr-upscaler-2e3312d-bin-Darwin-macOS-26.6.2-arm64.zip",
provides: &["engine-metal/sd-server", "engine-metal/libstable-diffusion.dylib"],
+ engine_tag: Some(ENGINE_TAG),
};
/// The engine files of a backend, in download order.
@@ -150,11 +190,13 @@ pub const TURBO_Q4_K: Download = Download {
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: TURBO_GGUF,
size: 4_050_916_384,
sha256: "f8d5611b495848b632f8ae14dc7da6525fe2796eb80998f8dee5e04d0a2f69eb",
dest: "models/qwen21/qwen-image-2.1-turbo-Q4_K.gguf",
provides: &[],
+ engine_tag: None,
};
pub const VAE: Download = Download {
@@ -162,11 +204,13 @@ pub const VAE: Download = Download {
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,
};
/// Text encoder from Qwen's own GGUF repository (the one sd.cpp's docs point to).
@@ -175,11 +219,13 @@ pub const TEXT_ENCODER_Q4_K_M: Download = Download {
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 {
@@ -187,11 +233,13 @@ pub const TEXT_ENCODER_Q8_0: Download = Download {
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).
@@ -200,26 +248,87 @@ pub const VISION_PROJECTOR: Download = Download {
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,
};
-/// Default ESRGAN model (CC BY-NC-SA 4.0). Must match `config::UPSCALER_CHOICES[0]`.
+/// 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: "4x-UltraSharp upscaler",
- kind: FileKind::Optional,
+ 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,
+};
+
+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",
- page: "https://huggingface.co/uwg/upscaler/tree/main/ESRGAN",
+ 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 {
@@ -309,12 +418,9 @@ pub fn recommended_preset(vram_mib: Option<u64>) -> &'static Preset {
}
/// Everything a preset needs on `backend`, in download order (small, essential files first).
-pub fn downloads_for(p: &Preset, backend: GpuBackend, with_upscaler: bool) -> Vec<Download> {
+pub fn downloads_for(p: &Preset, backend: GpuBackend) -> Vec<Download> {
let mut v = engine_downloads(backend);
- v.extend([VAE, VISION_PROJECTOR, p.text_encoder, p.diffusion]);
- if with_upscaler {
- v.push(UPSCALER);
- }
+ v.extend([UPSCALER, SUPERSCALE, VAE, VISION_PROJECTOR, p.text_encoder, p.diffusion]);
v
}
@@ -350,25 +456,64 @@ mod tests {
#[test]
fn catalog_is_well_formed() {
- let all = [ENGINE_CUDA, CUDA_RUNTIME, ENGINE_VULKAN, ENGINE_METAL, TURBO_Q4_K, VAE, TEXT_ENCODER_Q4_K_M, TEXT_ENCODER_Q8_0, VISION_PROJECTOR, UPSCALER];
+ let all = [ENGINE_CUDA, CUDA_RUNTIME, ENGINE_VULKAN, ENGINE_METAL, TURBO_Q4_K, VAE, TEXT_ENCODER_Q4_K_M, TEXT_ENCODER_Q8_0, VISION_PROJECTOR, UPSCALER, SUPERSCALE, ULTRASHARP];
for d in all {
- assert!(d.url.starts_with("https://"), "{}", d.id);
+ 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);
}
- // The default upscaler matches the one Settings offers first.
- assert!(UPSCALER.dest.ends_with(&format!("{}.pth", crate::config::DEFAULT_UPSCALER)));
+ // 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);
+ assert!(d.url.contains(&format!("/{ENGINE_TAG}/")), "{}", 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::DEFAULT_UPSCALER).unwrap().id, "upscaler_superscale");
for p in PRESETS {
- assert_eq!(downloads_for(p, GpuBackend::Cuda, true).len(), 7);
- let vk = downloads_for(p, GpuBackend::Vulkan, false);
- assert_eq!(vk.len(), 5);
+ let cuda = downloads_for(p, GpuBackend::Cuda);
+ assert_eq!(cuda.len(), 8);
+ 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);
+ assert_eq!(vk.len(), 7);
assert!(vk.iter().all(|d| d.id != "engine_cuda" && d.id != "cuda_runtime"));
}
}
+ #[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 presence_checks() {
let dir = tempfile::tempdir().unwrap();
@@ -379,6 +524,7 @@ mod tests {
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));
@@ -388,6 +534,7 @@ mod tests {
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();
diff --git a/crates/qls-core/src/config.rs b/crates/qls-core/src/config.rs
index 2a5b63b..4e4a7b2 100644
--- a/crates/qls-core/src/config.rs
+++ b/crates/qls-core/src/config.rs
@@ -17,25 +17,25 @@ const LEGACY_DATA_DIR: &str = "QwenLocalStudio";
pub const DATA_DIR_NAME: &str = "KokonData";
pub const DEFAULT_SERVER_PORT: u16 = 39150;
pub const DEFAULT_SERVICE_PORT: u16 = 39151;
-/// ESRGAN models offered in Settings: (file stem, label, download URL). Chosen by visual A/B on
-/// a Qwen edit (2026-10-06): both keep fine texture that RealESRGAN_x4plus smooths away.
-pub const UPSCALER_CHOICES: &[(&str, &str, &str)] = &[
- ("4x-UltraSharp", "UltraSharp", "https://huggingface.co/uwg/upscaler/resolve/main/ESRGAN/4x-UltraSharp.pth"),
- ("4x_NMKD-Superscale-SP_178000_G", "Superscale-SP", "https://huggingface.co/uwg/upscaler/resolve/main/ESRGAN/4x_NMKD-Superscale-SP_178000_G.pth"),
+/// Schema 8 (2026-10-12): the upscalers folder setting is gone (always `<sdcpp>/models/upscalers`)
+/// and ESRGAN tile sizes reset to automatic.
+const SCHEMA_VERSION: u32 = 8;
+/// `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).
pub const DEFAULT_UPSCALER: &str = UPSCALER_CHOICES[0].0;
-/// Default before schema 2; configs still on it are moved to [`DEFAULT_UPSCALER`].
-const OLD_DEFAULT_UPSCALER: &str = "RealESRGAN_x4plus";
-const SCHEMA_VERSION: u32 = 7;
-/// 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";
-
-/// Where to download `name`, if it is one of [`UPSCALER_CHOICES`].
-pub fn upscaler_download_url(name: &str) -> Option<&'static str> {
- UPSCALER_CHOICES.iter().find(|(n, _, _)| *n == name).map(|(_, _, u)| *u)
-}
/// 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";
/// 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×).
@@ -255,12 +255,18 @@ pub struct AppConfig {
/// 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,
- /// Folder with ESRGAN models (`--hires-upscalers-dir`); None = `<sdcpp>\models\upscalers`.
- pub upscalers_dir: Option<PathBuf>,
- /// ESRGAN model name (file stem) used to enlarge results and for upscales.
+ /// Upscaler model (file stem in the upscalers folder); the bundled MoSR runs when its file
+ /// is missing.
pub upscaler_model: String,
- /// ESRGAN tile size in pixels; 0 = backend default (128).
+ /// 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>,
pub output_dir: PathBuf,
pub keep_server_running: bool,
@@ -296,9 +302,10 @@ impl Default for AppConfig {
vae_tile_size: 768,
prefix_cache_type: "q8_0".into(),
eager_load: true,
- upscalers_dir: None,
upscaler_model: DEFAULT_UPSCALER.into(),
upscale_tile_size: 0,
+ upscale_blend: 1.0,
+ upscale_prescale: false,
extra_server_args: vec![],
output_dir: default_output_dir(),
keep_server_running: false,
@@ -404,8 +411,14 @@ impl AppConfig {
if c.profiles.len() == 1 && c.profiles[0] == ModelProfile::default() {
c.profiles[0] = ModelProfile::official(&c.sdcpp_dir, c.preset());
}
- if c.schema_version < 2 && c.upscaler_model.trim() == OLD_DEFAULT_UPSCALER {
- c.upscaler_model = DEFAULT_UPSCALER.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
@@ -466,9 +479,6 @@ impl AppConfig {
pub fn relocate_paths(&mut self, old: &Path, new: &Path) {
relocate(&mut self.sdcpp_dir, old, new);
- if let Some(d) = self.upscalers_dir.as_mut() {
- relocate(d, 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);
@@ -532,22 +542,31 @@ impl AppConfig {
self.sage_attention && self.gpu_backend == GpuBackend::Cuda
}
+ /// Folder of the upscaler (`--hires-upscalers-dir`).
pub fn upscalers_dir(&self) -> PathBuf {
- match &self.upscalers_dir {
- Some(d) if !d.as_os_str().is_empty() => d.clone(),
- _ => self.sdcpp_dir.join("models").join("upscalers"),
- }
+ crate::catalog::join_rel(&self.sdcpp_dir, crate::catalog::UPSCALERS_SUBDIR)
}
- /// The configured ESRGAN model file, if present. sd-server resolves names the same
- /// way: `<dir>/<name>.<ext>`, top level only.
- pub fn upscaler_file(&self) -> Option<PathBuf> {
+ /// 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.is_empty() {
+ if name == LANCZOS {
return None;
}
let dir = self.upscalers_dir();
- UPSCALER_EXTENSIONS.iter().map(|e| dir.join(format!("{name}.{e}"))).find(|p| p.is_file())
+ 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)
}
pub fn validate(&self) -> Result<(), AppError> {
@@ -569,6 +588,9 @@ impl AppConfig {
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)."));
}
@@ -596,7 +618,8 @@ mod tests {
assert!(!c.keep_server_running);
assert!(c.validate().is_ok());
assert_eq!(p.files().len(), 4);
- assert_eq!(c.upscaler_model, "4x-UltraSharp");
+ assert_eq!(c.upscale_tile_size, 0, "automatic");
+ assert_eq!((c.upscaler_model.as_str(), c.upscale_blend, c.upscale_prescale), ("4x_NMKD-Superscale-SP_178000_G", 1.0, false));
assert_eq!(c.upscalers_dir(), default_sdcpp_dir().join("models").join("upscalers"));
}
@@ -694,18 +717,22 @@ mod tests {
}
#[test]
- fn old_default_upscaler_is_migrated() {
+ fn schema_8_migration() {
let dir = tempfile::tempdir().unwrap();
let p = dir.path().join("config.json");
- std::fs::write(&p, r#"{"schemaVersion":1,"upscalerModel":"RealESRGAN_x4plus"}"#).unwrap();
+ 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.upscaler_model, DEFAULT_UPSCALER);
assert_eq!(c.schema_version, SCHEMA_VERSION);
- // A choice made after the change is kept.
- std::fs::write(&p, r#"{"schemaVersion":2,"upscalerModel":"RealESRGAN_x4plus"}"#).unwrap();
- assert_eq!(AppConfig::load_from(&p).upscaler_model, "RealESRGAN_x4plus");
- std::fs::write(&p, r#"{"schemaVersion":1,"upscalerModel":"4x_NMKD-Superscale-SP_178000_G"}"#).unwrap();
- assert_eq!(AppConfig::load_from(&p).upscaler_model, "4x_NMKD-Superscale-SP_178000_G");
+ 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]
@@ -733,12 +760,23 @@ mod tests {
fn upscaler_file_lookup() {
let dir = tempfile::tempdir().unwrap();
let mut c = AppConfig::default();
- c.upscalers_dir = Some(dir.path().to_path_buf());
- assert!(c.upscaler_file().is_none());
- std::fs::write(dir.path().join("4x-UltraSharp.pth"), b"x").unwrap();
- assert_eq!(c.upscaler_file().unwrap(), dir.path().join("4x-UltraSharp.pth"));
- c.upscaler_model = " ".into();
+ c.sdcpp_dir = dir.path().to_path_buf();
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);
diff --git a/crates/qls-core/src/diagnostics.rs b/crates/qls-core/src/diagnostics.rs
index be22e49..cd45923 100644
--- a/crates/qls-core/src/diagnostics.rs
+++ b/crates/qls-core/src/diagnostics.rs
@@ -220,32 +220,47 @@ pub fn setup_checks(cfg: &AppConfig, server_ok: Option<bool>) -> SetupReport {
});
}
checks.push(upscaler_check(cfg));
+ if exe_ok {
+ checks.push(engine_release_check(cfg));
+ }
let backend_version = if exe_ok { backend_version(&exe) } else { None };
- // The server and the ESRGAN model are optional: neither blocks starting.
- let ready = checks.iter().filter(|c| c.id != "server" && c.id != "upscaler").all(|c| c.ok);
+ // Informational: the server starts on demand; an engine of an older release still
+ // generates (enlargements fall back to Lanczos), and Setup offers the update.
+ let ready = checks.iter().filter(|c| c.id != "server" && c.id != "engine_release").all(|c| c.ok);
SetupReport { ready, checks, devices, backend_version }
}
-/// ESRGAN model for sharper enlargements. Optional: without it Lanczos is used. The app
-/// never downloads models, so the check explains where to get it.
+/// The upscaler model (MoSR): enlarges results and runs Upscale. Shipped with the app and
+/// otherwise downloaded by Setup.
pub fn upscaler_check(cfg: &AppConfig) -> Check {
- let dir = cfg.upscalers_dir();
- match cfg.upscaler_file() {
- Some(p) => {
+ let label = "Upscaler".to_string();
+ let chosen = cfg.upscaler_model.trim();
+ if chosen == crate::config::LANCZOS {
+ return Check { id: "upscaler", label, ok: true, detail: "Lanczos (plain resize, no model)".into() };
+ }
+ match cfg.upscaler() {
+ Some((name, p)) => {
let size = std::fs::metadata(&p).map(|m| fmt_size(m.len())).unwrap_or_default();
- Check { id: "upscaler", label: "ESRGAN upscaler (optional)".into(), ok: true, detail: format!("{} ({size})", p.display()) }
+ let fallback = if name != chosen { format!("{chosen} not found in {}; using ", cfg.upscalers_dir().display()) } else { String::new() };
+ Check { id: "upscaler", label, ok: true, detail: format!("{fallback}{} ({size})", p.display()) }
}
- None => Check {
- id: "upscaler",
- label: "ESRGAN upscaler (optional)".into(),
- ok: false,
- detail: {
- let name = cfg.upscaler_model.trim();
- let get = crate::config::upscaler_download_url(name)
- .map(|u| format!(" Download {u} (64 MB) into that folder for sharper results."))
- .unwrap_or_default();
- format!("Not found: {}\\{name}.pth — enlargements use Lanczos.{get}", dir.display())
- },
+ None => Check { id: "upscaler", label, ok: false, detail: format!("Missing: {} — install it from Setup.", crate::catalog::UPSCALER.path(&cfg.sdcpp_dir).display()) },
+ }
+}
+
+/// Whether the installed engine is the catalog's release (needed for the upscaler).
+pub fn engine_release_check(cfg: &AppConfig) -> Check {
+ let engines: Vec<_> = crate::catalog::engine_downloads(cfg.gpu_backend).into_iter().filter(|d| d.engine_tag.is_some()).collect();
+ let tags: Vec<Option<String>> = engines.iter().map(|d| d.installed_tag(&cfg.sdcpp_dir)).collect();
+ let ok = tags.iter().all(|t| t.as_deref() == Some(crate::catalog::ENGINE_TAG));
+ Check {
+ id: "engine_release",
+ label: "Engine release".into(),
+ ok,
+ detail: if ok {
+ crate::catalog::ENGINE_TAG.into()
+ } else {
+ format!("An older engine is installed; Setup updates it to {} (needed for the upscaler).", crate::catalog::ENGINE_TAG)
},
}
}
@@ -288,17 +303,25 @@ mod tests {
assert!(r.checks.iter().any(|c| c.id == "server_exe" && !c.ok));
assert_eq!(r.checks.iter().filter(|c| c.id == "model_file").count(), 4);
let up = r.checks.iter().find(|c| c.id == "upscaler").unwrap();
- assert!(!up.ok && up.detail.contains("4x-UltraSharp.pth") && up.detail.contains("huggingface.co/uwg/upscaler"));
+ assert!(!up.ok && up.detail.contains("4xNomos2_hq_mosr.pth"));
+ assert!(!r.checks.iter().any(|c| c.id == "engine_release"), "no engine, nothing to compare");
}
#[test]
- fn upscaler_check_is_optional() {
+ fn upscaler_and_engine_release_checks() {
let dir = tempfile::tempdir().unwrap();
let mut cfg = AppConfig::default();
- cfg.upscalers_dir = Some(dir.path().to_path_buf());
- assert!(!upscaler_check(&cfg).ok);
- std::fs::write(dir.path().join("4x-UltraSharp.pth"), vec![0u8; 2048]).unwrap();
+ cfg.sdcpp_dir = dir.path().to_path_buf();
+ cfg.gpu_backend = crate::config::GpuBackend::Cuda;
+ assert!(!upscaler_check(&cfg).ok, "required");
+ let up = crate::catalog::UPSCALER;
+ std::fs::create_dir_all(up.path(dir.path()).parent().unwrap()).unwrap();
+ std::fs::File::create(up.path(dir.path())).unwrap().set_len(up.size).unwrap();
let c = upscaler_check(&cfg);
- assert!(c.ok && c.detail.contains("4x-UltraSharp.pth"));
+ assert!(c.ok && c.detail.contains("4xNomos2_hq_mosr.pth"));
+ let e = engine_release_check(&cfg);
+ assert!(!e.ok && e.detail.contains(crate::catalog::ENGINE_TAG));
+ crate::catalog::ENGINE_CUDA.write_tag(dir.path()).unwrap();
+ assert!(engine_release_check(&cfg).ok);
}
}
diff --git a/crates/qls-core/src/engine.rs b/crates/qls-core/src/engine.rs
index 2861ab8..271b4dc 100644
--- a/crates/qls-core/src/engine.rs
+++ b/crates/qls-core/src/engine.rs
@@ -117,13 +117,26 @@ async fn blocking<T: Send + 'static>(f: impl FnOnce() -> AppResult<T> + Send + '
tokio::task::spawn_blocking(f).await.map_err(AppError::internal)?
}
+/// How results are enlarged (from the plan and the settings).
+#[derive(Debug, Clone, Copy)]
+struct EnlargeOptions {
+ /// Upscaler tile size in px (0 = server default).
+ tile: u32,
+ /// Share of the upscaler's result kept over Lanczos (`AppConfig::upscale_blend`).
+ blend: f32,
+ /// Shrink the input first (`AppConfig::upscale_prescale`).
+ prescale: bool,
+}
+
/// Planner inputs from the configuration and measured facts.
pub fn plan_inputs(cfg: &AppConfig, image_sizes: Vec<Size>, mask: Option<(Size, Option<crate::geometry::Rect>, f64)>, vram_total_mib: Option<u64>) -> PlanInputs {
PlanInputs {
image_sizes,
mask,
vram_total_mib,
- upscaler: cfg.upscaler_file().map(|_| cfg.upscaler_model.trim().to_string()),
+ upscale_tile: crate::planner::upscale_tile(cfg.upscale_tile_size, vram_total_mib, &cfg.upscaler().map(|u| u.0).unwrap_or_default()),
+ upscaler: cfg.upscaler().map(|u| u.0),
+ metal: cfg.gpu_backend == crate::config::GpuBackend::Metal,
server_vae_tiling: cfg.vae_tile_size > 0,
sage_attention: cfg.uses_sage_attention(),
speed_factor: None,
@@ -176,9 +189,32 @@ impl Engine {
|| g.gpu_backend != new.gpu_backend;
*g = new;
*self.backend_version.lock().unwrap() = None;
+ drop(g);
+ self.place_bundled_upscaler();
Ok(restart)
}
+ /// Copies the upscaler shipped with the app into the configured folder when it is missing
+ /// there (new install, another folder chosen). Failures leave it to the setup download.
+ pub fn place_bundled_upscaler(&self) {
+ let Some(bundle) = crate::installer::bundle_dir() else { return };
+ let dir = self.config().sdcpp_dir;
+ match crate::installer::install_bundled(&crate::catalog::UPSCALER, &dir, &bundle) {
+ Ok(true) => tracing::info!("bundled upscaler copied into {}", dir.display()),
+ Ok(false) => {}
+ Err(e) => tracing::warn!("could not copy the bundled upscaler into {}: {e}", dir.display()),
+ }
+ }
+
+ /// The installed engine is from an older release than the catalog's and the running
+ /// server (if any) cannot run the upscaler: Setup offers the update.
+ pub fn engine_update_needed(&self) -> bool {
+ let cfg = self.config();
+ let current = crate::catalog::engine_downloads(cfg.gpu_backend).iter().all(|d| d.is_present(&cfg.sdcpp_dir));
+ // An engine built by hand or an external server may lack the marker yet run MoSR.
+ !current && !self.server.capabilities().is_some_and(|c| c.has_upscaler(crate::catalog::UPSCALER_NAME, true))
+ }
+
/// The store holding generation `id`: the gallery, or the private-mode store.
pub fn gen_store(&self, id: &str) -> &Arc<Store> {
if self.store.get_generation(id).is_err() && self.private_store.get_generation(id).is_ok() { &self.private_store } else { &self.store }
@@ -545,20 +581,17 @@ impl Engine {
self.check_cancel(id)?;
self.update(id, |j| j.view.status = JobStatus::Preparing);
- // Which upscalers the running server really has (an external server may lack
- // --hires-upscalers-dir): enlargements fall back to Lanczos.
- // Fresh, because the server rescans the upscalers folder on every request.
+ // Whether the running server can use the upscaler (an engine older than MoSR lists the
+ // file but cannot run it; an external server may lack --hires-upscalers-dir):
+ // enlargements fall back to Lanczos. Fresh, because the server rescans the folder.
let client = SdcppClient::new(cfg.server_port);
let caps = client.capabilities(Duration::from_secs(5)).await.ok().or_else(|| self.server.capabilities()).unwrap_or_default();
let esrgan = plan.upscaler.clone().filter(|n| caps.has_upscaler(n, true));
let needs_esrgan = plan.upscale.is_some() || plan.output.area() as f64 > plan.content.area() as f64 * 1.21;
if needs_esrgan && plan.upscaler.is_some() && esrgan.is_none() {
- let name = plan.upscaler.clone().unwrap_or_default();
- self.update(id, |j| j.view.notes.push(format!("The inference server did not list the upscaler model {name}; Lanczos was used instead.")));
- } else if plan.upscaler.is_none() && plan.upscale.is_some() {
- self.update(id, |j| {
- j.view.notes.push(format!("Upscaler model {} not found; enlarged with Lanczos. Put {}.pth in the upscalers folder for sharper results.", cfg.upscaler_model, cfg.upscaler_model))
- });
+ self.update(id, |j| j.view.notes.push("The inference engine cannot run the upscaler (update it in Setup); enlarged with Lanczos.".into()));
+ } else if plan.upscaler.is_none() && needs_esrgan && cfg.upscaler_model.trim() != crate::config::LANCZOS {
+ self.update(id, |j| j.view.notes.push("The upscaler model is missing (install it in Setup); enlarged with Lanczos.".into()));
}
let quick_upscale = plan.upscale.is_some();
let icc = images.first().and_then(|i| i.icc_profile.clone());
@@ -697,7 +730,8 @@ impl Engine {
let target = pipeline::enlarge_target(&post);
// Kept when the upscaler enlarges it, so the user can still see and save it.
let original = target.map(|_| content.clone());
- let (content, enlarged_with) = self.enlarge(id, &client, content, target, esrgan.as_deref()).await?;
+ let how = EnlargeOptions { tile: plan.upscale_tile, blend: cfg.upscale_blend, prescale: cfg.upscale_prescale };
+ let (content, enlarged_with) = self.enlarge(id, &client, content, target, esrgan.as_deref(), how).await?;
let original = original.filter(|_| enlarged_with.is_some());
self.update(id, |j| {
j.view.status = JobStatus::Saving;
@@ -751,10 +785,10 @@ impl Engine {
}
}
- /// Enlarges `content` with ESRGAN when [`pipeline::finish`] would resize it up to
- /// `target` by more than ~1.1x. Returns the (possibly larger) content and how the
- /// enlargement is done; ESRGAN failures fall back to Lanczos with a note.
- async fn enlarge(&self, id: &str, client: &SdcppClient, content: image::RgbaImage, target: Option<Size>, esrgan: Option<&str>) -> AppResult<(image::RgbaImage, Option<String>)> {
+ /// Enlarges `content` with the upscaler model when [`pipeline::finish`] would resize it
+ /// up to `target` by more than ~1.1x. Returns the (possibly larger) content and how the
+ /// enlargement is done; upscaler failures fall back to Lanczos with a note.
+ async fn enlarge(&self, id: &str, client: &SdcppClient, content: image::RgbaImage, target: Option<Size>, esrgan: Option<&str>, how: EnlargeOptions) -> AppResult<(image::RgbaImage, Option<String>)> {
let Some(target) = target else { return Ok((content, None)) };
let size = Size::new(content.width(), content.height());
let factor = (target.width as f64 / size.width as f64).max(target.height as f64 / size.height as f64);
@@ -768,23 +802,33 @@ impl Engine {
j.view.step = None;
});
let content = Arc::new(content);
- let r = self.esrgan_enlarge(id, client, content.clone(), target, name).await;
+ let r = self.esrgan_enlarge(id, client, content.clone(), target, name, how).await;
+ let r = match r {
+ Ok(Some(img)) if how.blend < 1.0 => {
+ let src = content.clone();
+ blocking(move || Ok(pipeline::blend_with_lanczos(img, &src, how.blend))).await.map(Some)
+ }
+ r => r,
+ };
let content = Arc::try_unwrap(content).unwrap_or_else(|a| (*a).clone());
match r {
Ok(Some(img)) => Ok((img, Some(name.to_string()))),
Ok(None) => Ok((content, None)),
Err(e) if e.code == ErrorCode::Cancelled => Err(e),
Err(e) => {
- tracing::warn!("ESRGAN upscale failed, using Lanczos: {} {:?}", e.message, e.detail);
+ tracing::warn!("upscaler failed, using Lanczos: {} {:?}", e.message, e.detail);
self.update(id, |j| j.view.notes.push(format!("Upscaler model failed ({}); enlarged with Lanczos.", e.message)));
Ok((content, Some("Lanczos".into())))
}
}
}
- async fn esrgan_enlarge(&self, id: &str, client: &SdcppClient, content: Arc<image::RgbaImage>, target: Size, upscaler: &str) -> AppResult<Option<image::RgbaImage>> {
- // Tiles are sized for an x4 model, the common case (an x2 model just gets smaller results).
- let Some(ep) = pipeline::esrgan_plan(Size::new(content.width(), content.height()), target, 4) else { return Ok(None) };
+ async fn esrgan_enlarge(&self, id: &str, client: &SdcppClient, content: Arc<image::RgbaImage>, target: Size, upscaler: &str, how: EnlargeOptions) -> AppResult<Option<image::RgbaImage>> {
+ // Requests are sized for the x4 model; the server tiles each one at `how.tile` px.
+ let size = Size::new(content.width(), content.height());
+ let input = if how.prescale { pipeline::prescale_size(size, target, 4) } else { size };
+ let Some(ep) = pipeline::esrgan_plan(input, target, 4) else { return Ok(None) };
+ let tile_px = how.tile;
let c = content.clone();
let input = Arc::new(blocking(move || Ok(imaging::resize(&c, ep.input.width, ep.input.height))).await?);
let mut stitcher = pipeline::Stitcher::new(ep.input);
@@ -792,7 +836,7 @@ impl Engine {
self.check_cancel(id)?;
let (inp, t) = (input.clone(), *tile);
let png = blocking(move || pipeline::tile_png_b64(&inp, &t)).await?;
- let resp = client.upscale(&UpscaleRequest { image: png, upscaler: Some(upscaler.to_string()), tile_size: None, output_format: "png".into() }).await?;
+ let resp = client.upscale(&UpscaleRequest { image: png, upscaler: Some(upscaler.to_string()), tile_size: (tile_px > 0).then_some(tile_px), output_format: "png".into() }).await?;
let up = blocking(move || Ok(imaging::decode_image(&crate::sdcpp::b64_decode(&resp.images[0].b64_json)?)?.pixels)).await?;
stitcher.add(tile, &up)?;
}
@@ -1194,15 +1238,19 @@ mod tests {
let dir = tempfile::tempdir().unwrap();
let mut cfg = AppConfig::default();
cfg.gpu_backend = crate::config::GpuBackend::Cuda; // SageAttention is CUDA only
- cfg.upscalers_dir = Some(dir.path().to_path_buf());
+ cfg.sdcpp_dir = dir.path().to_path_buf();
let i = plan_inputs(&cfg, vec![], None, Some(16303));
assert_eq!(i.upscaler, None, "no model file -> Lanczos");
- assert!(i.server_vae_tiling && i.sage_attention);
- std::fs::write(dir.path().join("4x-UltraSharp.pth"), b"x").unwrap();
+ assert!(i.server_vae_tiling && i.sage_attention && !i.metal);
+ assert_eq!(i.upscale_tile, 128, "the ESRGAN default's tile");
+ std::fs::create_dir_all(cfg.upscalers_dir()).unwrap();
+ std::fs::File::create(crate::catalog::UPSCALER.path(dir.path())).unwrap().set_len(crate::catalog::UPSCALER.size).unwrap();
cfg.vae_tile_size = 0;
- let i = plan_inputs(&cfg, vec![], None, None);
- assert_eq!(i.upscaler.as_deref(), Some("4x-UltraSharp"));
- assert!(!i.server_vae_tiling);
+ cfg.gpu_backend = crate::config::GpuBackend::Metal;
+ let i = plan_inputs(&cfg, vec![], None, Some(12_000));
+ assert_eq!(i.upscaler.as_deref(), Some("4xNomos2_hq_mosr"));
+ assert_eq!(i.upscale_tile, 256, "smaller tiles under 14 GB");
+ assert!(!i.server_vae_tiling && i.metal);
}
#[test]
diff --git a/crates/qls-core/src/installer.rs b/crates/qls-core/src/installer.rs
index dd22e37..0024382 100644
--- a/crates/qls-core/src/installer.rs
+++ b/crates/qls-core/src/installer.rs
@@ -303,10 +303,8 @@ impl Installer {
i.error = Some(e);
i.hint = Some(hint);
});
- // Optional files never block; keep going so other files still install.
- if d.kind != FileKind::Optional {
- all_ok = false;
- }
+ // Keep going so the other files still install.
+ all_ok = false;
}
}
}
@@ -319,6 +317,52 @@ impl Installer {
std::fs::create_dir_all(parent).map_err(|e| Failure::Permanent(format!("Cannot create {}: {e}", parent.display())))?;
}
let part = part_path(&target);
+ // A link that still fails after its retries moves on to the next one (mirror, then
+ // the original); the first link's error is the one reported.
+ let mut first_error = None;
+ for url in d.urls() {
+ let from = Download { url, ..*d };
+ match self.fetch_verified(client, &from, &part).await {
+ Ok(()) => {
+ first_error = None;
+ break;
+ }
+ Err(Failure::Cancelled) => return Err(Failure::Cancelled),
+ Err(f) => {
+ let e = f.message();
+ tracing::warn!("{}: {url} failed ({e})", d.id);
+ first_error.get_or_insert(e);
+ if d.fallback_urls.is_empty() {
+ // Kept, so the next try resumes it.
+ break;
+ }
+ // Another server's partial file must not be resumed.
+ remove_part(&part);
+ }
+ }
+ }
+ if let Some(e) = first_error {
+ return Err(Failure::Permanent(e));
+ }
+ if d.is_zip() {
+ self.set(d.id, |i| i.state = ItemState::Extracting);
+ let (p, out) = (part.clone(), crate::catalog::zip_dir(d, dir));
+ tokio::task::spawn_blocking(move || extract_zip(&p, &out))
+ .await
+ .map_err(|e| Failure::Transient(e.to_string()))?
+ .map_err(Failure::Permanent)?;
+ let _ = std::fs::remove_file(&part);
+ d.write_tag(dir).map_err(|e| Failure::Permanent(format!("Cannot mark the engine as installed: {e}")))?;
+ } else {
+ std::fs::rename(&part, &target).map_err(|e| Failure::Permanent(format!("Cannot save {}: {e}", target.display())))?;
+ }
+ Ok(())
+ }
+
+ /// Downloads `d` from `d.url` into `part` and checks its hash (retrying interruptions and
+ /// one checksum mismatch).
+ async fn fetch_verified(&self, client: &reqwest::Client, d: &Download, part: &Path) -> Result<(), Failure> {
+ let part = part.to_path_buf();
let mut mismatches = 0;
let mut attempt = 0;
loop {
@@ -347,17 +391,6 @@ impl Installer {
tracing::warn!("{}: checksum mismatch, downloading again", d.id);
attempt = 0;
}
- if d.is_zip() {
- self.set(d.id, |i| i.state = ItemState::Extracting);
- let (p, out) = (part.clone(), crate::catalog::zip_dir(d, dir));
- tokio::task::spawn_blocking(move || extract_zip(&p, &out))
- .await
- .map_err(|e| Failure::Transient(e.to_string()))?
- .map_err(Failure::Permanent)?;
- let _ = std::fs::remove_file(&part);
- } else {
- std::fs::rename(&part, &target).map_err(|e| Failure::Permanent(format!("Cannot save {}: {e}", target.display())))?;
- }
Ok(())
}
@@ -645,6 +678,60 @@ pub fn space_needed(dir: &Path, downloads: &[Download]) -> (u64, u64) {
(download, disk)
}
+/// Folder of the model files shipped inside the app (Tauri resources): next to the
+/// executables on Windows, `Contents/Resources` on a Mac. `QLS_BUNDLE_DIR` overrides it.
+pub fn bundle_dir() -> Option<PathBuf> {
+ if let Ok(p) = std::env::var("QLS_BUNDLE_DIR") {
+ return Some(PathBuf::from(p));
+ }
+ let exe = std::env::current_exe().ok()?;
+ let dir = exe.parent()?;
+ [dir.join("bundled"), dir.join("..").join("Resources").join("bundled")].into_iter().find(|p| p.is_dir())
+}
+
+/// Copies `d` from the app's bundle into the stable-diffusion.cpp folder when it is missing
+/// there, checking its hash. Ok(true) when it was copied.
+pub fn install_bundled(d: &Download, dir: &Path, bundle: &Path) -> std::io::Result<bool> {
+ let name = d.dest.rsplit('/').next().unwrap_or(d.dest);
+ let src = bundle.join(name);
+ if d.is_zip() || d.is_present(dir) || !std::fs::metadata(&src).is_ok_and(|m| m.len() == d.size) {
+ return Ok(false);
+ }
+ let target = d.path(dir);
+ if let Some(p) = target.parent() {
+ std::fs::create_dir_all(p)?;
+ }
+ let tmp = part_path(&target);
+ std::fs::copy(&src, &tmp)?;
+ if sha256_file(&tmp)? != d.sha256 {
+ remove_part(&tmp);
+ return Err(std::io::Error::other(format!("the bundled {name} is damaged")));
+ }
+ std::fs::rename(&tmp, &target)?;
+ Ok(true)
+}
+
+/// ESRGAN models in the app's own upscalers folder other than those named in `keep` (the
+/// selected model), with their sizes.
+pub fn legacy_upscalers(dir: &Path, keep: &[&str]) -> Vec<(PathBuf, u64)> {
+ crate::catalog::LEGACY_UPSCALERS
+ .iter()
+ .map(|f| crate::catalog::join_rel(dir, f))
+ .filter(|p| p.file_stem().and_then(|s| s.to_str()).is_none_or(|s| !keep.contains(&s)))
+ .filter_map(|p| std::fs::metadata(&p).ok().filter(|m| m.is_file()).map(|m| (p, m.len())))
+ .collect()
+}
+
+/// Deletes [`legacy_upscalers`]; returns the bytes freed.
+pub fn remove_legacy_upscalers(dir: &Path, keep: &[&str]) -> AppResult<u64> {
+ let mut freed = 0;
+ for (p, size) in legacy_upscalers(dir, keep) {
+ std::fs::remove_file(&p).map_err(|e| AppError::io("delete the old upscaler", &p, e))?;
+ freed += size;
+ }
+ Ok(freed)
+}
+
/// Free space on the drive that holds `dir` (or its nearest existing parent).
pub fn free_space(dir: &Path) -> Option<u64> {
let mut p = dir.to_path_buf();
@@ -858,7 +945,7 @@ mod tests {
std::fs::write(&f, b"abc").unwrap();
assert_eq!(sha256_file(&f).unwrap(), "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
let p = crate::catalog::preset("16gb").unwrap();
- let all = crate::catalog::downloads_for(p, crate::config::GpuBackend::Cuda, false);
+ let all = crate::catalog::downloads_for(p, crate::config::GpuBackend::Cuda);
let (dl, disk) = space_needed(dir.path(), &all);
assert_eq!(dl, all.iter().map(|d| d.size).sum::<u64>());
assert!(disk > dl, "zips need room to extract");
@@ -896,7 +983,39 @@ mod tests {
assert_eq!(content_range_total(&h), Some(337_915_440));
}
- /// Real download of the smallest catalog file (QLS_TEST_DOWNLOAD=1; ~67 MB).
+ #[test]
+ fn bundled_upscaler_is_copied_once_and_checked() {
+ let (dir, bundle) = (tempfile::tempdir().unwrap(), tempfile::tempdir().unwrap());
+ let d = Download { size: 3, sha256: "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad", ..crate::catalog::UPSCALER };
+ assert!(!install_bundled(&d, dir.path(), bundle.path()).unwrap(), "nothing bundled (dev build)");
+ std::fs::write(bundle.path().join("4xNomos2_hq_mosr.pth"), b"abd").unwrap();
+ assert!(install_bundled(&d, dir.path(), bundle.path()).is_err(), "a damaged copy is refused");
+ assert!(!d.is_present(dir.path()) && !part_path(&d.path(dir.path())).exists());
+ std::fs::write(bundle.path().join("4xNomos2_hq_mosr.pth"), b"abc").unwrap();
+ assert!(install_bundled(&d, dir.path(), bundle.path()).unwrap());
+ assert!(d.is_present(dir.path()));
+ assert!(!install_bundled(&d, dir.path(), bundle.path()).unwrap(), "already in place");
+ }
+
+ #[test]
+ fn legacy_upscalers_only_in_the_app_folder() {
+ let dir = tempfile::tempdir().unwrap();
+ assert!(legacy_upscalers(dir.path(), &[]).is_empty());
+ let up = dir.path().join("models").join("upscalers");
+ std::fs::create_dir_all(&up).unwrap();
+ std::fs::write(up.join("4x-UltraSharp.pth"), vec![0u8; 100]).unwrap();
+ std::fs::write(up.join("4xNomos2_hq_mosr.pth"), b"keep").unwrap();
+ std::fs::write(up.join("my-own.pth"), b"keep").unwrap();
+ std::fs::write(up.join("4x_NMKD-Superscale-SP_178000_G.pth"), b"in use").unwrap();
+ let ss = &["4x_NMKD-Superscale-SP_178000_G"][..];
+ assert_eq!(legacy_upscalers(dir.path(), ss), vec![(up.join("4x-UltraSharp.pth"), 100)], "the selected model is never offered");
+ assert_eq!(remove_legacy_upscalers(dir.path(), ss).unwrap(), 100);
+ assert!(!up.join("4x-UltraSharp.pth").exists() && up.join("4xNomos2_hq_mosr.pth").exists() && up.join("my-own.pth").exists());
+ assert!(up.join("4x_NMKD-Superscale-SP_178000_G.pth").exists());
+ assert_eq!(remove_legacy_upscalers(dir.path(), ss).unwrap(), 0);
+ }
+
+ /// Real download of the smallest catalog file (QLS_TEST_DOWNLOAD=1; ~17 MB).
#[tokio::test]
async fn real_download_with_resume() {
if std::env::var("QLS_TEST_DOWNLOAD").is_err() {
@@ -911,7 +1030,7 @@ mod tests {
let client = reqwest::Client::new();
{
let resp = client.get(d.url).header(reqwest::header::RANGE, "bytes=0-1048575").send().await.unwrap();
- assert_eq!(resp.status().as_u16(), 206, "Hugging Face supports ranges");
+ assert_eq!(resp.status().as_u16(), 206, "GitHub's release CDN supports ranges");
std::fs::write(part_path(&target), resp.bytes().await.unwrap()).unwrap();
}
let (tx, rx) = std::sync::mpsc::channel();
diff --git a/crates/qls-core/src/pipeline.rs b/crates/qls-core/src/pipeline.rs
index 1ea3baf..a1679d4 100644
--- a/crates/qls-core/src/pipeline.rs
+++ b/crates/qls-core/src/pipeline.rs
@@ -462,6 +462,37 @@ impl Stitcher {
}
}
+/// Factor of the model's x4 output over the target that [`prescale_size`] aims for: the output
+/// is then shrunk ~1.41x, like the downscaled photos these models are trained on.
+pub const PRESCALE_OVERSHOOT: f64 = std::f64::consts::SQRT_2;
+
+/// Input size for an `scale`x upscaler so its output is about [`PRESCALE_OVERSHOOT`] times
+/// `target`: smaller than `content` for factors below ~2.8 (x4 model), else unchanged.
+pub fn prescale_size(content: Size, target: Size, scale: u32) -> Size {
+ let factor = (target.width as f64 / content.width as f64).max(target.height as f64 / content.height as f64);
+ let s = (factor * PRESCALE_OVERSHOOT / scale as f64).min(1.0);
+ if s >= 1.0 {
+ return content;
+ }
+ Size::new(((content.width as f64 * s).round() as u32).max(16), ((content.height as f64 * s).round() as u32).max(16))
+}
+
+/// Keeps `amount` (0..1) of the upscaler's result `up` and the rest of a Lanczos enlargement of
+/// `src` to the same size; alpha comes from `up`.
+pub fn blend_with_lanczos(mut up: RgbaImage, src: &RgbaImage, amount: f32) -> RgbaImage {
+ if amount >= 1.0 {
+ return up;
+ }
+ let base = imaging::resize(src, up.width(), up.height());
+ let a = amount.clamp(0.0, 1.0);
+ for (o, b) in up.pixels_mut().zip(base.pixels()) {
+ for c in 0..3 {
+ o[c] = (o[c] as f32 * a + b[c] as f32 * (1.0 - a)).round() as u8;
+ }
+ }
+ up
+}
+
/// PNG (base64) of one tile for the upscale endpoint (alpha is dropped by the server).
pub fn tile_png_b64(input: &RgbaImage, tile: &Tile) -> AppResult<String> {
png_b64(&imaging::crop(input, tile.rect))
@@ -470,13 +501,29 @@ pub fn tile_png_b64(input: &RgbaImage, tile: &Tile) -> AppResult<String> {
#[cfg(test)]
mod tests {
use super::*;
+
+ #[test]
+ fn prescale_and_blend() {
+ let c = Size::new(1448, 1448);
+ // x1.41 (1.5K render to 2K): half the input, so x4 lands at 1.41x the target.
+ let p = prescale_size(c, Size::new(2048, 2048), 4);
+ assert_eq!(p, Size::new(724, 724));
+ assert_eq!(prescale_size(c, Size::new(2896, 2896), 4).width, 1024, "x2: ~0.71x");
+ assert_eq!(prescale_size(c, Size::new(5792, 5792), 4), c, "x4: the full input");
+ // Blend: 0 = Lanczos, 1 = the upscaler, alpha from the upscaler.
+ let src = RgbaImage::from_pixel(2, 2, image::Rgba([100, 100, 100, 255]));
+ let up = RgbaImage::from_pixel(8, 8, image::Rgba([200, 0, 50, 255]));
+ assert_eq!(blend_with_lanczos(up.clone(), &src, 1.0), up);
+ assert_eq!(blend_with_lanczos(up.clone(), &src, 0.0).get_pixel(3, 3).0, [100, 100, 100, 255]);
+ assert_eq!(blend_with_lanczos(up, &src, 0.5).get_pixel(3, 3).0, [150, 50, 75, 255]);
+ }
use crate::config::RecommendedSettings;
use crate::geometry::ExpansionUnits;
use crate::planner::{GenerationRequest, Mode, OutpaintSpec, PlanInputs, Quality, ResolutionMode, UpscaleSpec, plan};
use crate::sdcpp::b64_decode;
fn env(sizes: Vec<Size>) -> PlanInputs {
- PlanInputs { image_sizes: sizes, vram_total_mib: Some(16303), upscaler: Some("RealESRGAN_x4plus".into()), ..Default::default() }
+ PlanInputs { image_sizes: sizes, vram_total_mib: Some(16303), upscaler: Some("4xNomos2_hq_mosr".into()), ..Default::default() }
}
fn esrgan_opts() -> BackendOptions {
BackendOptions { server_vae_tile_size: 768 }
diff --git a/crates/qls-core/src/planner.rs b/crates/qls-core/src/planner.rs
index 7c18159..7e9f907 100644
--- a/crates/qls-core/src/planner.rs
+++ b/crates/qls-core/src/planner.rs
@@ -307,9 +307,12 @@ pub struct Plan {
pub notes: Vec<String>,
pub optimized_for_vram: bool,
pub estimated_seconds: f32,
- /// ESRGAN model used to enlarge the result; None = Lanczos.
+ /// Upscaler model used to enlarge the result; None = Lanczos.
#[serde(default)]
pub upscaler: Option<String>,
+ /// Tile size the upscaler runs with ([`upscale_tile`]); 0 in records of older versions.
+ #[serde(default)]
+ pub upscale_tile: u32,
#[serde(default)]
pub upscale: Option<UpscalePlan>,
/// Exact noise schedule (Turbo's); empty when no diffusion runs.
@@ -324,8 +327,12 @@ pub struct PlanInputs {
/// (mask size, bounding box of painted area, coverage 0..1)
pub mask: Option<(Size, Option<Rect>, f64)>,
pub vram_total_mib: Option<u64>,
- /// ESRGAN model available to the server (`AppConfig::upscaler_file`).
+ /// Upscaler model available to the server (`AppConfig::upscaler_file`).
pub upscaler: Option<String>,
+ /// Upscaler tile size ([`upscale_tile`]); 0 = the large-memory default.
+ pub upscale_tile: u32,
+ /// The Metal engine (Apple Silicon): much slower upscaler.
+ pub metal: bool,
/// The server was launched with `--vae-tiling` (tiles every decode by default).
pub server_vae_tiling: bool,
/// SageAttention is enabled (faster steps; used for estimates only).
@@ -558,9 +565,46 @@ pub fn uses_guidance(cfg: f32) -> bool {
(cfg - 1.0).abs() > 1e-4
}
-/// One ESRGAN x4 pass over `input` pixels (~10 s per MP incl. model load, measured).
-pub fn esrgan_seconds(input: u64) -> f32 {
- 1.0 + 9.0 * input as f32 / 1_048_576.0
+/// Upscaler tile size with at least this much GPU memory (MiB): the 16 GB presets and up.
+pub const LARGE_UPSCALE_TILE_MIB: u64 = 14 * 1024;
+pub const LARGE_UPSCALE_TILE: u32 = 768;
+pub const SMALL_UPSCALE_TILE: u32 = 256;
+/// ESRGAN tiles: with direct convolutions 128 px is as fast as 256–512 px on an RTX 5070 Ti
+/// (13.2–13.7 s for 1472², 2026-10-12) at a fraction of the memory (+455 MB vs +3.4 GB).
+pub const ESRGAN_UPSCALE_TILE: u32 = 128;
+
+/// Whether `model` is the MoSR upscaler (anything else is an ESRGAN model).
+pub fn is_mosr(model: &str) -> bool {
+ model == crate::catalog::UPSCALER_NAME
+}
+
+/// Tile size of the upscaler: `override_px` when set; ESRGAN 128 px; MoSR 768 px on 16 GB
+/// cards and Macs with 32 GB+ (about +1.55 GB on CUDA with direct convolutions), 256 px below
+/// (12 GB cards, 16–24 GB Macs: about +0.5 GB). Unknown GPU: the 16 GB default preset's.
+pub fn upscale_tile(override_px: u32, vram_mib: Option<u64>, model: &str) -> u32 {
+ match (override_px, vram_mib) {
+ (t, _) if t > 0 => t,
+ _ if !is_mosr(model) => ESRGAN_UPSCALE_TILE,
+ (_, Some(v)) if v < LARGE_UPSCALE_TILE_MIB => SMALL_UPSCALE_TILE,
+ _ => LARGE_UPSCALE_TILE,
+ }
+}
+
+/// One x4 pass over `input` pixels, model load included. Measured on a 1472² edit
+/// (2026-10-12), RTX 5070 Ti, CUDA with direct convolutions: MoSR 3.1 s at 768 px tiles and
+/// ~5 s at 128–256 px (Vulkan within 10%), Superscale-SP (ESRGAN) 13.2 s at 128 px. M2 Pro,
+/// Metal: MoSR 54.6 s at 768 px and 78 s at 128 px; ESRGAN not measured (estimated ~3x MoSR).
+pub fn esrgan_seconds(input: u64, tile: u32, metal: bool, mosr: bool) -> f32 {
+ let large = tile == 0 || tile >= 512;
+ let per_mp = match (mosr, metal, large) {
+ (true, false, true) => 1.4,
+ (true, false, false) => 2.3,
+ (true, true, true) => 25.0,
+ (true, true, false) => 32.0,
+ (false, false, _) => 6.1,
+ (false, true, _) => 90.0,
+ };
+ 0.5 + per_mp * input as f32 / 1_048_576.0
}
/// VAE decode with 768 px tiles: ~1.3 s at 1 MP, ~3.9 s at 2048x1152.
@@ -912,7 +956,8 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetti
let mut estimated_seconds =
if quick_upscale { 2.0 } else { estimate_seconds(working.canvas, &references, steps, batch_count, inputs.sage_attention, cfg) };
if inputs.upscaler.is_some() && (enlarge || quick_upscale) {
- estimated_seconds += esrgan_seconds(working.content.area()) * batch_count as f32;
+ let mosr = inputs.upscaler.as_deref().is_some_and(is_mosr);
+ estimated_seconds += esrgan_seconds(working.content.area(), inputs.upscale_tile, inputs.metal, mosr) * batch_count as f32;
}
estimated_seconds = match inputs.speed_factor {
Some(f) => estimated_seconds * f,
@@ -949,6 +994,7 @@ pub fn plan(req: &GenerationRequest, inputs: &PlanInputs, rec: &RecommendedSetti
optimized_for_vram: optimized,
estimated_seconds,
upscaler: inputs.upscaler.clone(),
+ upscale_tile: if inputs.upscale_tile > 0 { inputs.upscale_tile } else { LARGE_UPSCALE_TILE },
upscale,
custom_sigmas: if quick_upscale { Vec::new() } else { TURBO_SIGMAS.to_vec() },
})
@@ -1037,7 +1083,7 @@ mod tests {
#[test]
fn mac_fast_renders_the_full_size() {
- let mac = |sizes: &[(u32, u32)]| PlanInputs { unified_memory: true, vram_total_mib: Some(4600), upscaler: Some("4x-UltraSharp".into()), ..inputs(sizes) };
+ let mac = |sizes: &[(u32, u32)]| PlanInputs { unified_memory: true, vram_total_mib: Some(4600), upscaler: Some("4xNomos2_hq_mosr".into()), ..inputs(sizes) };
let mut r = req("a lighthouse at dusk");
r.quality = Quality::Fast;
let p = plan(&r, &mac(&[]), &rec()).unwrap();
@@ -1139,7 +1185,7 @@ mod tests {
}
fn env(upscaler: bool) -> PlanInputs {
- PlanInputs { upscaler: upscaler.then(|| "RealESRGAN_x4plus".to_string()), sage_attention: true, ..inputs(&[]) }
+ PlanInputs { upscaler: upscaler.then(|| "4xNomos2_hq_mosr".to_string()), sage_attention: true, ..inputs(&[]) }
}
#[test]
@@ -1178,7 +1224,7 @@ mod tests {
assert_eq!(p.output, Size::new(3840, 2160), "exact requested size is delivered");
assert!(p.working.area() as f64 <= (token_budget(Some(16303)) * 256) as f64 * 1.02, "alignment padding only");
assert!((p.content.width as f64 / p.content.height as f64 / (3840.0 / 2160.0) - 1.0).abs() < 0.01);
- assert!(p.notes.iter().any(|n| n.contains("enlarged to 3840×2160 with RealESRGAN_x4plus")), "{:?}", p.notes);
+ assert!(p.notes.iter().any(|n| n.contains("enlarged to 3840×2160 with 4xNomos2_hq_mosr")), "{:?}", p.notes);
}
#[test]
@@ -1283,6 +1329,36 @@ mod tests {
assert!(t(UpscaleSpec { scale: Some(-1.0), ..Default::default() }).is_err());
}
+ #[test]
+ fn upscaler_tile_follows_memory() {
+ let m = "4xNomos2_hq_mosr";
+ assert_eq!(upscale_tile(0, Some(16_303), m), 768, "16 GB card");
+ assert_eq!(upscale_tile(0, Some(12_282), m), 256, "12 GB card");
+ assert_eq!(upscale_tile(0, Some(8_192), m), 256);
+ assert_eq!(upscale_tile(0, None, m), 768, "unknown GPU: the default preset's");
+ assert_eq!(upscale_tile(0, Some(LARGE_UPSCALE_TILE_MIB), m), 768);
+ assert_eq!(upscale_tile(512, Some(8_192), m), 512, "the setting wins");
+ assert_eq!(upscale_tile(0, Some(16_303), "4x_NMKD-Superscale-SP_178000_G"), 128, "ESRGAN");
+ // Planned with the job, so the engine and the estimate agree.
+ let p = plan(&req("a lighthouse"), &PlanInputs { upscale_tile: 256, ..env(true) }, &rec()).unwrap();
+ assert_eq!(p.upscale_tile, 256);
+ }
+
+ #[test]
+ fn upscaler_estimates() {
+ let mp = 1472 * 1472;
+ // Measured 2026-10-12 (1472² edit): 3.1 s CUDA tile 768, ~5 s tile 256, 54.6 s M2 Pro.
+ assert!((esrgan_seconds(mp, 768, false, true) - 3.1).abs() < 0.6);
+ assert!((esrgan_seconds(mp, 256, false, true) - 5.0).abs() < 0.6);
+ assert!((esrgan_seconds(mp, 768, true, true) - 54.6).abs() < 3.0);
+ assert!(esrgan_seconds(mp, 256, true, true) > esrgan_seconds(mp, 768, true, true));
+ assert!((esrgan_seconds(mp, 128, false, false) - 13.2).abs() < 1.0, "Superscale-SP");
+ let r = GenerationRequest { mode: Mode::Upscale, upscale: Some(UpscaleSpec { scale: Some(2.0), ..Default::default() }), ..Default::default() };
+ let i = PlanInputs { image_sizes: vec![Size::new(1472, 1472)], upscale_tile: 768, upscaler: Some("4xNomos2_hq_mosr".into()), ..env(true) };
+ let (pc, mac) = (plan(&r, &i, &rec()).unwrap(), plan(&r, &PlanInputs { metal: true, ..i.clone() }, &rec()).unwrap());
+ assert!(mac.estimated_seconds > pc.estimated_seconds * 5.0, "{} vs {}", mac.estimated_seconds, pc.estimated_seconds);
+ }
+
#[test]
fn upscale_plans() {
let mut r = GenerationRequest { mode: Mode::Upscale, upscale: Some(UpscaleSpec { scale: Some(2.0), ..Default::default() }), ..Default::default() };
diff --git a/crates/qls-core/src/process.rs b/crates/qls-core/src/process.rs
index e1c44b5..c137a57 100644
--- a/crates/qls-core/src/process.rs
+++ b/crates/qls-core/src/process.rs
@@ -92,16 +92,18 @@ pub fn build_server_args(cfg: &AppConfig, profile: &ModelProfile) -> Vec<String>
if cfg.eager_load && placement != TextEncoderPlacement::Disk {
a.push("--eager-load".into());
}
- // ESRGAN models for the hires refine and `/sdcpp/v1/upscale`; the server scans the
+ // The upscaler for `/sdcpp/v1/upscale` (tile size sent per request); the server scans the
// folder lazily, so a model added later is picked up without a restart.
let up_dir = cfg.upscalers_dir();
if up_dir.is_dir() {
a.push("--hires-upscalers-dir".into());
a.push(p(&up_dir));
}
- if cfg.upscale_tile_size > 0 {
- let t = cfg.upscale_tile_size.to_string();
- a.extend(["--upscale-tile-size".into(), t.clone(), "--hires-upscale-tile-size".into(), t]);
+ if cfg.gpu_backend != crate::config::GpuBackend::Metal {
+ // Direct convolutions in the upscaler (it only affects UNet/ControlNet models besides,
+ // never Qwen). MoSR at 1472², 768 px tiles on an RTX 5070 Ti: CUDA 3.8 s / +2.4 GB →
+ // 3.1 s / +1.55 GB; Vulkan +4.2 GB → +1.25 GB. On Metal it is ~4x slower (M2 Pro).
+ a.push("--diffusion-conv-direct".into());
}
if cfg.vram_reserve_gib > 0.0 {
// A negative --max-vram reserves that much free VRAM (sd-server --help).
@@ -730,9 +732,9 @@ mod tests {
fn default_launch_args() {
let mut cfg = AppConfig::default();
cfg.gpu_backend = crate::config::GpuBackend::Cuda; // the default is Metal on a Mac
- cfg.sdcpp_dir = std::path::PathBuf::from(r"C:\AI\sdcpp");
+ // A folder without an upscalers subfolder.
+ cfg.sdcpp_dir = std::env::temp_dir().join("qls-no-sdcpp-here");
cfg.apply_preset(crate::catalog::preset("16gb").unwrap());
- cfg.upscalers_dir = Some(std::env::temp_dir().join("qls-no-upscalers-here"));
let a = build_server_args(&cfg, cfg.profile());
let s = a.join(" ");
let m = |f: &str| crate::catalog::join_rel(&cfg.sdcpp_dir, &format!("models/qwen21/{f}")).display().to_string();
@@ -744,22 +746,28 @@ mod tests {
assert!(s.contains("--backend cuda0 --params-backend te=cpu"));
assert!(s.contains("--fa --sage-attn --vae-tiling --vae-tile-size 768 --vae-tile-overlap 0.125"));
assert!(s.contains("--model-args qwen_image_2_1_prefix_cache_type=q8_0 --eager-load"));
- assert!(s.ends_with("--max-vram -1"));
+ assert!(s.ends_with("--diffusion-conv-direct --max-vram -1"));
assert!(!s.contains("0.0.0.0"));
assert!(!s.contains("--hires-upscalers-dir"), "missing folder is not passed");
- assert!(!s.contains("upscale-tile-size"));
+ assert!(!s.contains("upscale-tile-size"), "the tile size is sent with each request");
+ assert!(!s.contains("--vae-conv-direct"), "slower for Qwen's VAE");
}
#[test]
fn upscaler_args() {
let dir = tempfile::tempdir().unwrap();
let mut cfg = AppConfig::default();
- cfg.upscalers_dir = Some(dir.path().to_path_buf());
+ cfg.sdcpp_dir = dir.path().to_path_buf();
+ std::fs::create_dir_all(cfg.upscalers_dir()).unwrap();
cfg.upscale_tile_size = 256;
- let a = build_server_args(&cfg, cfg.profile());
- let i = a.iter().position(|x| x == "--hires-upscalers-dir").unwrap();
- assert_eq!(a[i + 1], dir.path().to_string_lossy());
- assert!(a.join(" ").contains("--upscale-tile-size 256 --hires-upscale-tile-size 256"));
+ for (backend, direct) in [(crate::config::GpuBackend::Cuda, true), (crate::config::GpuBackend::Vulkan, true), (crate::config::GpuBackend::Metal, false)] {
+ cfg.gpu_backend = backend;
+ let a = build_server_args(&cfg, cfg.profile());
+ let i = a.iter().position(|x| x == "--hires-upscalers-dir").unwrap();
+ assert_eq!(a[i + 1], cfg.upscalers_dir().to_string_lossy());
+ assert_eq!(a.iter().any(|x| x == "--diffusion-conv-direct"), direct, "{backend:?}: direct convolutions are ~4x slower on Metal");
+ assert!(!a.join(" ").contains("upscale-tile-size"));
+ }
}
/// Captured from sd-cli 3f8527a (bench hires_fast: 1376x768 -> ESRGAN -> 2048x1152,
diff --git a/crates/qls-service/src/api.rs b/crates/qls-service/src/api.rs
index c59a3fb..45d7c3e 100644
--- a/crates/qls-service/src/api.rs
+++ b/crates/qls-service/src/api.rs
@@ -61,6 +61,9 @@ pub fn router(state: Arc<AppState>) -> Router {
.route("/setup/hardware", get(setup_hardware))
.route("/setup/install", get(install_status).post(install_start))
.route("/setup/install/cancel", post(install_cancel))
+ .route("/setup/legacy-upscalers", get(legacy_upscalers).delete(remove_legacy_upscalers))
+ .route("/upscalers", get(list_upscalers))
+ .route("/upscalers/{name}/download", post(download_upscaler))
.route("/config", get(get_config).put(put_config))
.route("/backend/start", post(backend_start))
.route("/backend/stop", post(backend_stop))
@@ -180,6 +183,8 @@ async fn status(State(s): St) -> Json<Value> {
let jobs = s.engine.jobs();
let queued = jobs.iter().filter(|j| j.status == qls_core::engine::JobStatus::Queued).count();
let cfg = s.engine.config();
+ let e = s.engine.clone();
+ let engine_update = tokio::task::spawn_blocking(move || e.engine_update_needed()).await.unwrap_or(false);
Json(json!({
"service": { "version": APP_VERSION, "pid": std::process::id(), "uptime_s": s.started.elapsed().as_secs() },
"server": {
@@ -191,7 +196,8 @@ async fn status(State(s): St) -> Json<Value> {
"schedulers": srv.capabilities.as_ref().map(|c| c.schedulers.clone()).unwrap_or_default(),
"upscale": srv.capabilities.as_ref().map(|c| c.upscale),
},
- "upscaler": { "model": cfg.upscaler_model, "available": cfg.upscaler_file().is_some() },
+ "upscaler": { "model": cfg.upscaler().map(|u| u.0).unwrap_or_else(|| cfg.upscaler_model.clone()), "available": cfg.upscaler_file().is_some() },
+ "engine": { "release": catalog::ENGINE_TAG, "update_needed": engine_update },
"profile": { "id": cfg.profile().id, "display_name": cfg.profile().display_name },
"gpu": gpu,
"active_job": s.engine.active_job(),
@@ -201,6 +207,8 @@ async fn status(State(s): St) -> Json<Value> {
}
async fn setup(State(s): St) -> ApiResult<Json<Value>> {
+ let e = s.engine.clone();
+ let _ = tokio::task::spawn_blocking(move || e.place_bundled_upscaler()).await;
let cfg = s.engine.config();
let srv_ok = s.engine.server.status().state == qls_core::process::ServerState::Ready;
let report = tokio::task::spawn_blocking(move || diagnostics::setup_checks(&cfg, Some(srv_ok))).await.map_err(AppError::internal)?;
@@ -232,7 +240,7 @@ async fn setup_hardware(State(s): St, Query(q): Query<HardwareQ>) -> ApiResult<J
let presets: Vec<Value> = catalog::PRESETS
.iter()
.map(|p| {
- let files = catalog::downloads_for(p, backend, true);
+ let files = catalog::downloads_for(p, backend);
let (download, disk) = installer::space_needed(&dir, &files);
json!({
"id": p.id, "label": if unified { p.unified_label } else { p.label }, "summary": if unified { p.unified_summary } else { p.summary }, "verified": p.verified, "min_vram_mib": p.min_vram_mib,
@@ -269,8 +277,9 @@ struct InstallBody {
preset: String,
/// Engine to install; default: the configured one.
backend: Option<GpuBackend>,
+ /// Make the preset active when done (false: an engine update keeps the current settings).
#[serde(default = "yes")]
- upscaler: bool,
+ apply: bool,
}
fn yes() -> bool {
@@ -295,8 +304,9 @@ async fn install_start(State(s): St, Json(b): Json<InstallBody>) -> ApiResult<Js
let engine = s.engine.clone();
// Below ~8 GiB of planning memory (a 16 GB Mac) only streaming weights from disk fits.
let small_unified = s.engine.gpu().is_some_and(|g| g.unified && g.planning_mib() < 8 * 1024);
+ let apply = b.apply;
let on_finish = Box::new(move |complete: bool| {
- if !complete {
+ if !complete || !apply {
return;
}
let mut c = engine.config();
@@ -309,10 +319,58 @@ async fn install_start(State(s): St, Json(b): Json<InstallBody>) -> ApiResult<Js
tracing::error!("could not save the installed preset: {}", e.message);
}
});
- s.engine.installer.start(cfg.sdcpp_dir.clone(), preset.id, catalog::downloads_for(preset, backend, b.upscaler), on_finish)?;
+ // The bundled upscaler first, so it is not downloaded again.
+ let e = s.engine.clone();
+ let _ = tokio::task::spawn_blocking(move || e.place_bundled_upscaler()).await;
+ s.engine.installer.start(cfg.sdcpp_dir.clone(), preset.id, catalog::downloads_for(preset, backend), on_finish)?;
Ok(Json(serde_json::to_value(s.engine.installer.status()).unwrap()))
}
+/// The upscalers Settings offers, with whether each is installed and what it takes to get it.
+async fn list_upscalers(State(s): St) -> Json<Value> {
+ let cfg = s.engine.config();
+ let active = cfg.upscaler().map(|u| u.0);
+ let items: Vec<Value> = qls_core::config::UPSCALER_CHOICES
+ .iter()
+ .map(|(name, label)| {
+ let d = catalog::upscaler_download(name);
+ let installed = d.is_none_or(|d| d.is_present(&cfg.sdcpp_dir));
+ json!({ "name": name, "label": label, "installed": installed, "size": d.map(|d| d.size), "page": d.map(|d| d.page) })
+ })
+ .collect();
+ Json(json!({ "selected": cfg.upscaler_model, "active": active, "items": items }))
+}
+
+/// Downloads one upscaler model (progress in `/setup/install`).
+async fn download_upscaler(State(s): St, AxPath(name): AxPath<String>) -> ApiResult<Json<Value>> {
+ let d = catalog::upscaler_download(&name).ok_or_else(|| AppError::invalid(format!("Unknown upscaler {name}.")))?;
+ let dir = s.engine.config().sdcpp_dir;
+ s.engine.installer.start(dir, &format!("upscaler:{name}"), vec![d], Box::new(|_| {}))?;
+ Ok(Json(serde_json::to_value(s.engine.installer.status()).unwrap()))
+}
+
+/// Upscaler models of earlier versions in the app's own folder (Settings offers to delete
+/// them; files elsewhere are never touched).
+#[derive(Deserialize)]
+struct KeepQ {
+ /// Another model to keep besides the saved one (an unsaved choice in Settings).
+ keep: Option<String>,
+}
+
+async fn legacy_upscalers(State(s): St, Query(q): Query<KeepQ>) -> Json<Value> {
+ let cfg = s.engine.config();
+ let files = installer::legacy_upscalers(&cfg.sdcpp_dir, &[cfg.upscaler_model.trim(), q.keep.as_deref().unwrap_or("")]);
+ let bytes: u64 = files.iter().map(|(_, n)| n).sum();
+ Json(json!({ "files": files.iter().map(|(p, _)| p).collect::<Vec<_>>(), "bytes": bytes }))
+}
+
+async fn remove_legacy_upscalers(State(s): St, Query(q): Query<KeepQ>) -> ApiResult<Json<Value>> {
+ let cfg = s.engine.config();
+ let keep = q.keep.unwrap_or_default();
+ let freed = tokio::task::spawn_blocking(move || installer::remove_legacy_upscalers(&cfg.sdcpp_dir, &[cfg.upscaler_model.trim(), keep.as_str()])).await.map_err(AppError::internal)??;
+ Ok(Json(json!({ "freed_bytes": freed })))
+}
+
async fn install_status(State(s): St) -> Json<Value> {
Json(serde_json::to_value(s.engine.installer.status()).unwrap())
}
@@ -386,6 +444,12 @@ async fn diagnostics_json(State(s): St) -> ApiResult<Json<Value>> {
let _ = writeln!(text, "CUDA backend: {}", if cuda { "available" } else { "NOT available" });
let _ = writeln!(text, "\n[Inference server]");
let _ = writeln!(text, "stable-diffusion.cpp: {}", version.clone().unwrap_or_else(|| "unknown".into()));
+ let tags: Vec<String> = catalog::engine_downloads(cfg.gpu_backend)
+ .iter()
+ .filter(|d| d.engine_tag.is_some())
+ .map(|d| d.installed_tag(&cfg.sdcpp_dir).unwrap_or_else(|| "none".into()))
+ .collect();
+ let _ = writeln!(text, "Engine release: {} (expected {})", tags.join(", "), catalog::ENGINE_TAG);
let _ = writeln!(text, "State: {:?}, owned: {}, pid: {:?}, port: {}", srv.state, srv.owned, srv.pid, cfg.server_port);
if let Some(e) = &srv.error {
let _ = writeln!(text, "Last error: {} {}", e.message, e.detail.clone().unwrap_or_default());
@@ -409,7 +473,9 @@ async fn diagnostics_json(State(s): St) -> ApiResult<Json<Value>> {
let _ = writeln!(text, "Device: {}, text encoder: {:?}, VRAM reserve: {} GiB, flash attention: {}, sage attention: {}", cfg.device, cfg.text_encoder_placement, cfg.vram_reserve_gib, cfg.flash_attention, cfg.sage_attention);
let _ = writeln!(text, "VAE tile size: {}, upscale tile size: {}", cfg.vae_tile_size, cfg.upscale_tile_size);
let up = diagnostics::upscaler_check(&cfg);
- let _ = writeln!(text, "ESRGAN upscaler: {}", up.detail);
+ let model = cfg.upscaler().map(|u| u.0).unwrap_or_default();
+ let tile = qls_core::planner::upscale_tile(cfg.upscale_tile_size, cfg.planning_vram_mib(gpus.as_ref().and_then(|g| g.first()).map(|g| g.planning_mib())), &model);
+ let _ = writeln!(text, "Upscaler: {} (tile {tile} px, blend {:.0} %, pre-shrink {})", up.detail, cfg.upscale_blend * 100.0, cfg.upscale_prescale);
let _ = writeln!(text, "Ports: server {}, service {}", cfg.server_port, cfg.service_port);
let _ = writeln!(text, "Output: {}", cfg.output_dir.display());
let _ = writeln!(text, "Data: {}", qls_core::config::data_dir().display());
diff --git a/crates/qls-service/src/main.rs b/crates/qls-service/src/main.rs
index 510b0a0..a93965c 100644
--- a/crates/qls-service/src/main.rs
+++ b/crates/qls-service/src/main.rs
@@ -132,6 +132,9 @@ async fn main() {
return;
}
};
+ // The upscaler ships with the app: put it where sd-server looks (no download needed).
+ let e = engine.clone();
+ let _ = tokio::task::spawn_blocking(move || e.place_bundled_upscaler()).await;
let token = load_or_create_token(&dir);
let info = ServiceInfo { port, token: token.clone(), pid: std::process::id(), version: APP_VERSION.into() };
let _ = std::fs::write(service_info_path(), serde_json::to_string_pretty(&info).unwrap());
diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md
index 764a072..0806107 100644
--- a/docs/engineering-notes.md
+++ b/docs/engineering-notes.md
@@ -22,7 +22,7 @@ Kokon.exe (Tauri 2 + React) kokon-mcp.exe (MCP, stdio) scripts
| `crates/qls-core/src/geometry.rs` | Pure dimension math: 32-alignment, working canvas, outpaint/inpaint geometry |
| `imaging.rs` | EXIF orientation, alpha-safe resize, padding, masks, compositing, PNG metadata/ICC |
| `planner.rs` | Mode detection, resolution policy, upscale targets, memory budget (incl. Apple unified memory) |
-| `pipeline.rs` | Builds backend requests, post-processes results (crop back, ESRGAN tiling, composite) |
+| `pipeline.rs` | Builds backend requests, post-processes results (crop back, upscaler tiling, composite) |
| `sdcpp.rs` | Inference adapter — the only code that knows sd-server's schema |
| `process.rs` | sd-server launch/reuse/stop, log capture, truthful progress parsing |
| `engine.rs` | Async job queue, cancellation, OOM retry, saving |
@@ -100,7 +100,7 @@ Details and the reasoning are in [platforms.md](platforms.md); the short version
model from `--hires-upscalers-dir`, then re-sample at `denoising_strength`); reference
latents and inpaint masks are carried into that pass. `cache_mode`/`cache_option`
(e.g. `easycache`, `threshold=0.2`) work per request. `POST /sdcpp/v1/upscale`
- (`{image, upscaler}`) runs ESRGAN synchronously, up to 8192 px per side.
+ (`{image, upscaler, tile_size}`) runs the upscaler model synchronously, up to 8192 px per side.
- Qwen-Image 2.1 always decodes an alpha channel (≈1 % of pixels at alpha 247–254 on opaque
images); outputs are made opaque unless transparency is requested.
@@ -113,12 +113,45 @@ ESRGAN → low-denoise refine at 2K) was removed on 2026-10-06: in A/B tests the
edits look worse than a single pass.
Whenever a result is larger than what the model rendered (edits restored to the source size,
-outpaint, sizes above the VRAM budget) it is enlarged with ESRGAN ×4 and then resized down to
-the exact size; Lanczos is only used for shrinking or factors below 1.1×.
+outpaint, sizes above the VRAM budget) it is enlarged with the upscaler model (×4) and then
+resized down to the exact size; Lanczos is only used for shrinking or factors below 1.1×.
+
+### Upscalers (2026-10-12)
+
+Default: Superscale-SP (ESRGAN, WTFPL, setup download), 128 px tiles with direct convolutions
+(13.2 s / +455 MB for 1472² on an RTX 5070 Ti, vs 24.7 s / +747 MB without). Also offered:
+MoSR (experimental, bundled), UltraSharp (optional download, non-commercial), Lanczos.
+`upscaleBlend` mixes the result with Lanczos; `upscalePrescale` shrinks the input so x4 lands
+~1.41x the target. Why MoSR is not the default: on clean full-size renders enlarged < ~2.8x it
+invents a fine crosshatch that the final downscale turns into a visible grid (the port matches
+PyTorch; the model does it). Superscale shows the same on JPEG blocks and dark areas; UltraSharp
+over-smooths skin and invents lines. A/B crops: `bench/out/upscale_ab-20261012-141057` (sdcpp
+workspace); the in-app comparison uses crops from it (`src/assets/upscalers`).
+
+#### MoSR in sd.cpp
+
+MoSR by Philip Hofmann (CC BY 4.0), 17 MB. Upstream sd.cpp has no MoSR, so the
+engine is the fork release `kokon-mosr-1` (3f8527a + `src/model/upscaler/mosr.hpp`, upstream
+PR #2128; Qwen output bit-identical to 3f8527a). Port vs PyTorch: mean error 0.04–0.16/255.
+
+- Launch: `--diffusion-conv-direct` on CUDA and Vulkan only (in sd.cpp it affects UNet/ControlNet
+ and this upscaler, never Qwen). On Metal it is ~4× slower. `--vae-conv-direct` makes Qwen's
+ decode ~1 s slower: not used.
+- Tile size per request (`planner::upscale_tile`): 768 px with ≥ 14 GiB of planning memory, 256 px
+ below (12 GB cards, 16–24 GB Macs); `upscaleTileSize` overrides it.
+- 1472² edit, ×4 (2026-10-12): RTX 5070 Ti CUDA 3.1 s / +1.55 GB at 768 px (3.8 s / +2.4 GB
+ without direct), ~5 s / +0.5 GB at 256 px; UltraSharp at 128 px took 24.5 s. Vulkan 3.3–3.55 s
+ / +1.25 GB (+4.2 GB without direct). M2 Pro Metal 54.6 s at 768 px, 78 s at 128 px.
+- The model ships inside the app (Tauri resource `bundled/`, fetched at build time by
+ `scripts/release/fetch-bundled.mjs`) and is copied into `<sdcpp>/models/upscalers/` at start;
+ Setup downloads it (mirror on this repo's `models-1` release, then the author's) only if that
+ fails.
+- Engine folders carry `kokon-engine.txt` with the release tag; without it (or with another
+ tag) Setup offers the engine download, and the app opens Setup once per release.
Apple Silicon renders Fast at its full ~1 MP like a PC. Rendering 768² and enlarging it was
removed on 2026-10-10: on the M2 Pro 16 GB it took 5 min 25 s against 4 min 20 s for a direct
-1376×768 render (the ESRGAN pass on Metal costs more than the smaller render saves).
+1376×768 render (the upscaler pass on Metal costs more than the smaller render saves).
### Turbo (the only image model since 2026-10-09)
@@ -153,7 +186,7 @@ old base file stays on disk until the user deletes it).
- Open: Turbo Q6_K / Q8_0 vs Q4_K (the comparison script has `official8_q6_k`,
`official8_q8_0`); Turbo at 1.5K and 2K on real prompts.
-The **Upscale** action runs the upscaler model (ESRGAN) straight on the image. The Detailed
+The **Upscale** action runs the upscaler model straight on the image. The Detailed
method (a low-denoise img2img pass at about 2K first) was removed on 2026-10-09: Turbo's
schedule leaves only 1–2 steps at strength 0.3. Requests with `"method": "detailed"` run as
the upscaler model only.
@@ -179,8 +212,8 @@ path so it can be fetched by hand.
In `%APPDATA%\Kokon\config.json`: `hardwarePreset` (`12gb|16gb|24gb|32gb`, written by the
setup screen), `vramOverrideMib` (plan sizes as if the GPU had this much VRAM; 0 = detect;
-for testing), `upscalersDir` (null = default folder), `upscalerModel` (`4x-UltraSharp`; configs on the old
-`RealESRGAN_x4plus` default move to it), `upscaleTileSize` (0 = backend default 128),
+for testing), `upscaleTileSize` (0 = automatic, see the upscaler section; schema 8 reset it),
+`ui.engineUpdateSkipped` (engine release whose update was skipped in Setup),
`prefixCacheType`, `eagerLoad`, `sageAttention`.
## Testing smaller cards on a bigger one
diff --git a/mcp/src/index.ts b/mcp/src/index.ts
index 92b37df..eca20ce 100644
--- a/mcp/src/index.ts
+++ b/mcp/src/index.ts
@@ -38,7 +38,7 @@ const DESCRIPTIONS: Record<keyof typeof schemas, { title: string; description: s
upscale_image: {
title: "Upscale image",
description:
- "Enlarge an image (default 2x, or to a width/height up to 8192 px). Runs the configured ESRGAN upscaler model on the image (UltraSharp by default; seconds, adds no new content). Saves a new file; the input is never overwritten.",
+ "Enlarge an image (default 2x, or to a width/height up to 8192 px). Runs the upscaler model chosen in Kokon (Superscale-SP by default; seconds on a PC GPU, longer on a Mac; adds no new content). Saves a new file; the input is never overwritten.",
},
get_image_info: {
title: "Image info",
diff --git a/package.json b/package.json
index a904891..d3aa218 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
"scripts": {
"dev": "vite",
"build": "tsc --noEmit && vite build",
+ "bundled": "node scripts/release/fetch-bundled.mjs",
"test": "vitest run",
"tauri": "tauri"
},
diff --git a/scripts/release/fetch-bundled.mjs b/scripts/release/fetch-bundled.mjs
new file mode 100644
index 0000000..780e369
--- /dev/null
+++ b/scripts/release/fetch-bundled.mjs
@@ -0,0 +1,55 @@
+// Model files shipped inside the app (Tauri resources, see "bundle.resources" in
+// src-tauri/tauri.conf.json): fetched at build time, never committed.
+//
+// node scripts/release/fetch-bundled.mjs
+//
+// Downloads the upscaler of crates/qls-core/src/catalog.rs (`UPSCALER`: our mirror first, then
+// the author's release) into src-tauri/resources/ unless it is already there, and checks its
+// size and SHA-256 against the catalog. Runs before every `tauri dev` / `tauri build`.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const catalog = fs.readFileSync(path.join(root, "crates", "qls-core", "src", "catalog.rs"), "utf8");
+
+/** URL, mirrors, size and hash of a `Download` constant, read from the catalog. */
+function entry(name) {
+ const block = catalog.match(new RegExp(`pub const ${name}: Download = Download \\{([\\s\\S]*?)\\n\\};`))?.[1];
+ if (!block) throw new Error(`${name} not found in catalog.rs`);
+ const field = (f) => block.match(new RegExp(`\\n\\s*${f}: ([^\\n]*),`))?.[1];
+ const fallbacks = [...(field("fallback_urls") ?? "").matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+ return {
+ urls: [JSON.parse(field("url")), ...fallbacks],
+ size: Number(field("size").replaceAll("_", "")),
+ sha256: JSON.parse(field("sha256")),
+ file: path.basename(JSON.parse(field("dest"))),
+ };
+}
+
+const sha256 = (buf) => crypto.createHash("sha256").update(buf).digest("hex");
+
+async function fetchBundled(name) {
+ const d = entry(name);
+ const dest = path.join(root, "src-tauri", "resources", d.file);
+ if (fs.existsSync(dest) && fs.statSync(dest).size === d.size && sha256(fs.readFileSync(dest)) === d.sha256) return;
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
+ for (const url of d.urls) {
+ try {
+ const res = await fetch(url);
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
+ const buf = Buffer.from(await res.arrayBuffer());
+ if (buf.length !== d.size || sha256(buf) !== d.sha256) throw new Error(`size/checksum mismatch (${buf.length} bytes)`);
+ fs.writeFileSync(`${dest}.part`, buf);
+ fs.renameSync(`${dest}.part`, dest);
+ console.log(`bundled ${d.file} from ${url}`);
+ return;
+ } catch (e) {
+ console.warn(`${url}: ${e.message}`);
+ }
+ }
+ throw new Error(`could not fetch ${d.file}; put it in ${path.dirname(dest)} by hand (sha256 ${d.sha256})`);
+}
+
+await fetchBundled("UPSCALER");
diff --git a/src-tauri/build.rs b/src-tauri/build.rs
index 2846c57..474df78 100644
--- a/src-tauri/build.rs
+++ b/src-tauri/build.rs
@@ -1 +1,10 @@
-fn main() { tauri_build::build() }
+fn main() {
+ // Bundled model files are fetched before `tauri dev` / `tauri build` (beforeDevCommand /
+ // beforeBuildCommand); a plain `cargo build` needs them fetched first.
+ let upscaler = std::path::Path::new("resources").join("4xNomos2_hq_mosr.pth");
+ println!("cargo:rerun-if-changed={}", upscaler.display());
+ if !upscaler.is_file() {
+ panic!("{} is missing: run `npm run bundled` (scripts/release/fetch-bundled.mjs) first", upscaler.display());
+ }
+ tauri_build::build()
+}
diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json
index 7f520f9..a40b139 100644
--- a/src-tauri/tauri.conf.json
+++ b/src-tauri/tauri.conf.json
@@ -5,9 +5,9 @@
"version": "0.9.0",
"identifier": "app.kokon.desktop",
"build": {
- "beforeDevCommand": "npm run dev",
+ "beforeDevCommand": "npm run bundled && cargo build -p qls-service && npm run dev",
"devUrl": "http://localhost:1420",
- "beforeBuildCommand": "npm run build",
+ "beforeBuildCommand": "npm run bundled && npm run build",
"frontendDist": "../dist"
},
"app": {
@@ -48,6 +48,9 @@
"binaries/kokon-service",
"binaries/kokon-mcp"
],
+ "resources": {
+ "resources/4xNomos2_hq_mosr.pth": "bundled/4xNomos2_hq_mosr.pth"
+ },
"windows": {
"nsis": {
"installerIcon": "icons/icon.ico",
diff --git a/src/App.tsx b/src/App.tsx
index 0b279b0..89c5da5 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -17,6 +17,8 @@ import { Stage } from "./components/Stage";
import { Tour } from "./components/Tour";
import { IconButton } from "./components/ui";
import { shortcut } from "./lib/platform";
+import { WhatsNew, whatsNewDue } from "./components/WhatsNew";
+import { UpscalerCompare } from "./components/Upscalers";
import { KokonMark, Welcome } from "./components/Welcome";
import { autoCheckForUpdate, installUpdate } from "./lib/updates";
@@ -175,6 +177,7 @@ async function uploadBlobs(files: File[]) {
export default function App() {
const overlay = useStore((s) => s.overlay);
const needsSetup = useStore((s) => s.needsSetup);
+ const compareUpscalers = useStore((s) => s.compareUpscalers);
const sidebar = useStore((s) => s.sidebar);
const editing = useStore((s) => s.composer.refs.length > 0 && s.session.length > 0);
const [boot, setBoot] = useState<"connecting" | "ok" | string>("connecting");
@@ -207,11 +210,15 @@ export default function App() {
tourPending.current = true;
addExampleProjects().catch(() => {});
}
- setState({ needsSetup: !cfg.setupComplete, ...(welcomeSeen ? {} : { overlay: "welcome" }) });
+ // After an app update: what's new, with the engine download when the release needs a
+ // newer one (it can be postponed there; offered again only for another release).
+ const whatsNew = cfg.setupComplete && whatsNewDue(ui, st?.engine);
+ const engineUpdate = whatsNew && !!st?.engine?.update_needed;
+ setState({ needsSetup: !cfg.setupComplete, ...(!welcomeSeen ? { overlay: "welcome" } : whatsNew ? { overlay: "whats-new" } : {}) });
setBoot("ok");
autoCheckForUpdate();
- // Preload the model so the first generation starts immediately.
- if (cfg.setupComplete && st && st.server.state === "stopped") api.startBackend().then(refreshStatus, () => refreshStatus());
+ // Preload the model so the first generation starts immediately (not an engine about to be replaced).
+ if (cfg.setupComplete && !engineUpdate && st && st.server.state === "stopped") api.startBackend().then(refreshStatus, () => refreshStatus());
} catch (e) {
setBoot(String(e));
}
@@ -355,6 +362,8 @@ export default function App() {
</div>
{overlay === "settings" && <SettingsDialog />}
{overlay === "welcome" && <Welcome />}
+ {overlay === "whats-new" && <WhatsNew />}
+ {compareUpscalers && <UpscalerCompare />}
<Tour />
<Toasts />
</div>
diff --git a/src/assets/upscalers/face-lanczos.png b/src/assets/upscalers/face-lanczos.png
new file mode 100644
index 0000000..36b50f7
Binary files /dev/null and b/src/assets/upscalers/face-lanczos.png differ
diff --git a/src/assets/upscalers/face-mosr.png b/src/assets/upscalers/face-mosr.png
new file mode 100644
index 0000000..ed2e028
Binary files /dev/null and b/src/assets/upscalers/face-mosr.png differ
diff --git a/src/assets/upscalers/face-superscale.png b/src/assets/upscalers/face-superscale.png
new file mode 100644
index 0000000..5112040
Binary files /dev/null and b/src/assets/upscalers/face-superscale.png differ
diff --git a/src/assets/upscalers/face-ultrasharp.png b/src/assets/upscalers/face-ultrasharp.png
new file mode 100644
index 0000000..8fc524d
Binary files /dev/null and b/src/assets/upscalers/face-ultrasharp.png differ
diff --git a/src/assets/upscalers/jpeg-lanczos.png b/src/assets/upscalers/jpeg-lanczos.png
new file mode 100644
index 0000000..ee7cca2
Binary files /dev/null and b/src/assets/upscalers/jpeg-lanczos.png differ
diff --git a/src/assets/upscalers/jpeg-mosr.png b/src/assets/upscalers/jpeg-mosr.png
new file mode 100644
index 0000000..cc918e6
Binary files /dev/null and b/src/assets/upscalers/jpeg-mosr.png differ
diff --git a/src/assets/upscalers/jpeg-superscale.png b/src/assets/upscalers/jpeg-superscale.png
new file mode 100644
index 0000000..b451ea6
Binary files /dev/null and b/src/assets/upscalers/jpeg-superscale.png differ
diff --git a/src/assets/upscalers/jpeg-ultrasharp.png b/src/assets/upscalers/jpeg-ultrasharp.png
new file mode 100644
index 0000000..91a063f
Binary files /dev/null and b/src/assets/upscalers/jpeg-ultrasharp.png differ
diff --git a/src/assets/upscalers/landscape-lanczos.png b/src/assets/upscalers/landscape-lanczos.png
new file mode 100644
index 0000000..a000d67
Binary files /dev/null and b/src/assets/upscalers/landscape-lanczos.png differ
diff --git a/src/assets/upscalers/landscape-mosr.png b/src/assets/upscalers/landscape-mosr.png
new file mode 100644
index 0000000..f26d938
Binary files /dev/null and b/src/assets/upscalers/landscape-mosr.png differ
diff --git a/src/assets/upscalers/landscape-superscale.png b/src/assets/upscalers/landscape-superscale.png
new file mode 100644
index 0000000..a18d1c3
Binary files /dev/null and b/src/assets/upscalers/landscape-superscale.png differ
diff --git a/src/assets/upscalers/landscape-ultrasharp.png b/src/assets/upscalers/landscape-ultrasharp.png
new file mode 100644
index 0000000..67c3633
Binary files /dev/null and b/src/assets/upscalers/landscape-ultrasharp.png differ
diff --git a/src/assets/upscalers/night-lanczos.png b/src/assets/upscalers/night-lanczos.png
new file mode 100644
index 0000000..12877ef
Binary files /dev/null and b/src/assets/upscalers/night-lanczos.png differ
diff --git a/src/assets/upscalers/night-mosr.png b/src/assets/upscalers/night-mosr.png
new file mode 100644
index 0000000..b48c97f
Binary files /dev/null and b/src/assets/upscalers/night-mosr.png differ
diff --git a/src/assets/upscalers/night-superscale.png b/src/assets/upscalers/night-superscale.png
new file mode 100644
index 0000000..3c79c2a
Binary files /dev/null and b/src/assets/upscalers/night-superscale.png differ
diff --git a/src/assets/upscalers/night-ultrasharp.png b/src/assets/upscalers/night-ultrasharp.png
new file mode 100644
index 0000000..747fddf
Binary files /dev/null and b/src/assets/upscalers/night-ultrasharp.png differ
diff --git a/src/assets/upscalers/text-lanczos.png b/src/assets/upscalers/text-lanczos.png
new file mode 100644
index 0000000..4e2f39c
Binary files /dev/null and b/src/assets/upscalers/text-lanczos.png differ
diff --git a/src/assets/upscalers/text-mosr.png b/src/assets/upscalers/text-mosr.png
new file mode 100644
index 0000000..0c1c0c3
Binary files /dev/null and b/src/assets/upscalers/text-mosr.png differ
diff --git a/src/assets/upscalers/text-superscale.png b/src/assets/upscalers/text-superscale.png
new file mode 100644
index 0000000..347f709
Binary files /dev/null and b/src/assets/upscalers/text-superscale.png differ
diff --git a/src/assets/upscalers/text-ultrasharp.png b/src/assets/upscalers/text-ultrasharp.png
new file mode 100644
index 0000000..34bc876
Binary files /dev/null and b/src/assets/upscalers/text-ultrasharp.png differ
diff --git a/src/assets/upscalers/x4-lanczos.png b/src/assets/upscalers/x4-lanczos.png
new file mode 100644
index 0000000..018c926
Binary files /dev/null and b/src/assets/upscalers/x4-lanczos.png differ
diff --git a/src/assets/upscalers/x4-mosr.png b/src/assets/upscalers/x4-mosr.png
new file mode 100644
index 0000000..b8d1a07
Binary files /dev/null and b/src/assets/upscalers/x4-mosr.png differ
diff --git a/src/assets/upscalers/x4-superscale.png b/src/assets/upscalers/x4-superscale.png
new file mode 100644
index 0000000..f005dc2
Binary files /dev/null and b/src/assets/upscalers/x4-superscale.png differ
diff --git a/src/assets/upscalers/x4-ultrasharp.png b/src/assets/upscalers/x4-ultrasharp.png
new file mode 100644
index 0000000..1fcdb89
Binary files /dev/null and b/src/assets/upscalers/x4-ultrasharp.png differ
diff --git a/src/components/Advanced.tsx b/src/components/Advanced.tsx
index 61228b9..1f75852 100644
--- a/src/components/Advanced.tsx
+++ b/src/components/Advanced.tsx
@@ -2,6 +2,7 @@ import { Dices, RotateCcw } from "lucide-react";
import { updateComposer, useStore } from "../lib/store";
import type { Advanced, OutputFormat, Plan } from "../lib/types";
import { Seg, Switch } from "./ui";
+import { UpscalerSettings } from "./Upscalers";
// Verified against sd-server 3f8527a capabilities; replaced by the live list when loaded.
// Steps, CFG and scheduler are fixed by the Turbo model's 8-step schedule (no CFG).
@@ -110,6 +111,9 @@ export function AdvancedPanel({ plan }: { plan: Plan | null }) {
<button className="btn" onClick={() => updateComposer({ advanced: {}, seed: null })}>
<RotateCcw size={14} /> Reset to automatic
</button>
+
+ <hr className="menu-sep" />
+ <UpscalerSettings />
</>
);
}
diff --git a/src/components/Settings.tsx b/src/components/Settings.tsx
index 16fba0e..22fa9ec 100644
--- a/src/components/Settings.tsx
+++ b/src/components/Settings.tsx
@@ -1,10 +1,12 @@
-import { Activity, Copy, Cpu, Download, FolderOpen, HardDrive, RefreshCw, RotateCcw, Settings2, X } from "lucide-react";
+import { Activity, Copy, Cpu, Download, FolderOpen, HardDrive, RefreshCw, RotateCcw, Settings2, Trash2, X } from "lucide-react";
import { useEffect, useState } from "react";
import { writeText } from "@tauri-apps/plugin-clipboard-manager";
import { api } from "../lib/api";
import { native } from "../lib/native";
import { getState, refreshStatus, setState, startTour, toastError, toastInfo } from "../lib/store";
-import { UPSCALERS } from "../lib/logic";
+import { formatBytes } from "../lib/logic";
+import { UpscalerControls } from "./Upscalers";
+import { WHATS_NEW_VERSION } from "./WhatsNew";
import type { AppConfig, Check, ModelProfile, SetupReport, TextEncoderPlacement } from "../lib/types";
import { IconButton, Seg, Switch } from "./ui";
import { autoCheckEnabled, checkForUpdate } from "../lib/updates";
@@ -88,6 +90,7 @@ export function Settings() {
const [cfg, setCfg] = useState<AppConfig | null>(null);
const [devices, setDevices] = useState<[string, string][]>([]);
const [upscaler, setUpscaler] = useState<Check | null>(null);
+ const [legacy, setLegacy] = useState<{ files: string[]; bytes: number } | null>(null);
const [dirty, setDirty] = useState(false);
useEffect(() => {
@@ -100,6 +103,22 @@ export function Settings() {
() => {},
);
}, []);
+ // Upscaler files not in use, keeping the model chosen here even before Save.
+ const draftModel = cfg?.upscalerModel;
+ useEffect(() => {
+ if (draftModel !== undefined) api.legacyUpscalers(draftModel).then(setLegacy, () => {});
+ }, [draftModel]);
+
+ const removeLegacy = async () => {
+ if (!cfg || !legacy || !window.confirm(`Delete the upscaler files not in use (${formatBytes(legacy.bytes)})?\n\n${legacy.files.join("\n")}`)) return;
+ try {
+ const r = await api.removeLegacyUpscalers(cfg.upscalerModel);
+ toastInfo(`Deleted (${formatBytes(r.freed_bytes)} freed)`);
+ api.legacyUpscalers(cfg.upscalerModel).then(setLegacy, () => {});
+ } catch (e) {
+ toastError(e);
+ }
+ };
const close = () => setState({ overlay: null });
useEffect(() => {
@@ -118,6 +137,19 @@ export function Settings() {
setDirty(true);
};
const setProfile = (patch: Partial<ModelProfile>) => set({ profiles: cfg.profiles.map((p) => (p.id === profile.id ? { ...p, ...patch } : p)) });
+ // Upscaler options apply at once, like in the Advanced menu: saved on top of the stored
+ // settings (other unsaved fields stay a draft) and mirrored in the draft, so Save keeps them.
+ const applyNow = async (patch: Partial<AppConfig>) => {
+ setCfg((c) => (c ? { ...c, ...patch } : c));
+ try {
+ const saved = await api.config();
+ await api.saveConfig({ ...saved, ...patch });
+ api.setup().then((s: SetupReport) => setUpscaler(s.checks.find((c) => c.id === "upscaler") ?? null), () => {});
+ refreshStatus();
+ } catch (e) {
+ toastError(e);
+ }
+ };
const save = async () => {
try {
@@ -188,6 +220,12 @@ export function Settings() {
Check now
</button>
</div>
+ <div className="field-row">
+ <span>What's new in Kokon {WHATS_NEW_VERSION}</span>
+ <button className="btn" onClick={() => setState({ overlay: "whats-new" })}>
+ Show
+ </button>
+ </div>
<div className="field-row">
<span>Welcome screen: what Kokon is and how it keeps your work private</span>
<button className="btn" onClick={() => setState({ overlay: "welcome" })}>
@@ -239,21 +277,32 @@ export function Settings() {
<PathField label="VAE" value={profile.vae} onChange={(v) => setProfile({ vae: v })} />
<PathField label="Text encoder (Qwen3-VL)" value={profile.textEncoder} onChange={(v) => setProfile({ textEncoder: v })} />
<PathField label="Vision projector (mmproj)" value={profile.visionProjector ?? ""} onChange={(v) => setProfile({ visionProjector: v || null })} />
- <PathField label="Upscalers folder (ESRGAN)" value={cfg.upscalersDir ?? `${cfg.sdcppDir.replace(/[\\/]+$/, "")}\\models\\upscalers`} folder onChange={(v) => set({ upscalersDir: v || null })} />
- <label className="field-row">
- <span>Upscaler model (ESRGAN)</span>
- <select className="select" value={cfg.upscalerModel} onChange={(e) => set({ upscalerModel: e.target.value })}>
- {UPSCALERS.map(([name, label], i) => (
- <option key={name} value={name}>
- {label}
- {i === 0 ? " (default)" : ""}
- </option>
- ))}
- {!UPSCALERS.some(([n]) => n === cfg.upscalerModel) && <option value={cfg.upscalerModel}>{cfg.upscalerModel}</option>}
- </select>
- </label>
- <span className="muted">Enlarges every result from the model's output to its final size, and runs the Upscale button.</span>
- {upscaler && <span className="muted">{upscaler.ok ? `Found: ${upscaler.detail}` : upscaler.detail}</span>}
+ <UpscalerControls
+ model={cfg.upscalerModel}
+ blend={cfg.upscaleBlend}
+ onModel={(m) => applyNow({ upscalerModel: m })}
+ onBlend={(b) => setCfg({ ...cfg, upscaleBlend: b })}
+ onBlendDone={() => applyNow({ upscaleBlend: cfg.upscaleBlend })}
+ />
+ {upscaler && !upscaler.ok && <span className="muted">{upscaler.detail}</span>}
+ <div className="field-row">
+ <span>Shrink the image before upscaling</span>
+ <Switch on={cfg.upscalePrescale} onChange={(v) => applyNow({ upscalePrescale: v })} />
+ </div>
+ <span className="muted" style={{ marginTop: -10 }}>
+ Gives the upscaler a smaller image, like the ones it was trained on: fewer invented patterns on clean renders and faster, slightly less fine detail. Only for enlargements under 2.8×.
+ </span>
+ {legacy && legacy.files.length > 0 && (
+ <div className="setting-card">
+ <div className="setting-card-text">
+ <strong>Upscaler files not in use</strong>
+ <span className="muted">{legacy.files.map((f) => f.split(/[\\/]/).pop()).join(", ")}: not the selected model. Only Kokon's own folder is checked.</span>
+ </div>
+ <button className="btn" onClick={removeLegacy}>
+ <Trash2 size={15} /> Delete ({formatBytes(legacy.bytes)})
+ </button>
+ </div>
+ )}
</>
)}
@@ -364,9 +413,10 @@ export function Settings() {
</div>
)}
<label className="field-row">
- <span>ESRGAN tile size (px, 0 = default 128)</span>
+ <span>Upscaler tile size (px, 0 = automatic)</span>
<input className="input" type="number" min={0} max={1024} step={64} style={{ width: 90 }} value={cfg.upscaleTileSize} onChange={(e) => set({ upscaleTileSize: Math.max(0, Math.round(Number(e.target.value) || 0)) })} />
</label>
+ <span className="muted" style={{ marginTop: -10 }}>Automatic: 768 px with 16 GB of GPU memory or more (fastest), 256 px below (about 1 GB less).</span>
{!mac && (
<>
<label className="field-row">
diff --git a/src/components/Setup.tsx b/src/components/Setup.tsx
index 896a3e1..46ef14e 100644
--- a/src/components/Setup.tsx
+++ b/src/components/Setup.tsx
@@ -1,11 +1,11 @@
-import { Bug, Check, ChevronDown, CircleAlert, Download, ExternalLink, FolderOpen, Info, Loader2, Pause, Play, RefreshCw, Settings2 } from "lucide-react";
+import { Bug, Check, ChevronDown, CircleAlert, Download, ExternalLink, FolderOpen, Loader2, Pause, Play, RefreshCw, Settings2 } from "lucide-react";
import { useEffect, useRef, useState } from "react";
import { api } from "../lib/api";
import { formatBytes, installItemShort, installProgress, installStep, installTimeLeft } from "../lib/logic";
import { native } from "../lib/native";
import { refreshStatus, setState, toastError, useStore } from "../lib/store";
import type { GpuBackend, HardwareReport, InstallItem, InstallStatus, SetupReport } from "../lib/types";
-import { Seg, Switch } from "./ui";
+import { Seg } from "./ui";
import { ReadyTips, Showcase } from "./Welcome";
const gb = (mib: number) => `${Math.round(mib / 1024)} GB`;
@@ -30,7 +30,7 @@ function ItemIcon({ it }: { it: InstallItem }) {
case "done":
return <Check size={16} />;
case "failed":
- return it.kind === "optional" ? <Info size={16} /> : <CircleAlert size={16} />;
+ return <CircleAlert size={16} />;
case "downloading":
case "verifying":
case "extracting":
@@ -69,10 +69,7 @@ function FileList({ items }: { items: InstallItem[] }) {
{items.map((it) => (
<div className={`setup-file ${it.state}`} key={it.id}>
<ItemIcon it={it} />
- <span className="name">
- {it.label}
- {it.kind === "optional" ? <span className="muted"> · optional</span> : null}
- </span>
+ <span className="name">{it.label}</span>
<span className="state">{installItemShort(it)}</span>
</div>
))}
@@ -88,11 +85,11 @@ export function Setup() {
const [inst, setInst] = useState<InstallStatus | null>(null);
const [preset, setPreset] = useState<string | null>(null);
const [backend, setBackend] = useState<GpuBackend | null>(null);
- const [upscaler, setUpscaler] = useState(true);
const [showFiles, setShowFiles] = useState(false);
const [checking, setChecking] = useState(false);
const wasRunning = useRef(false);
const setupDone = useStore((s) => s.status?.setup_complete ?? false);
+ const engineUpdate = useStore((s) => s.status?.engine);
const refresh = async (engine: GpuBackend | null = backend) => {
setChecking(true);
@@ -142,7 +139,7 @@ export function Setup() {
const install = async () => {
if (!preset) return;
try {
- setInst(await api.install(preset, upscaler, backend ?? hw?.backend ?? "cuda"));
+ setInst(await api.install(preset, backend ?? hw?.backend ?? "cuda"));
} catch (e) {
toastError(e);
}
@@ -150,8 +147,11 @@ export function Setup() {
const start = async () => {
try {
- const cfg = await api.config();
- await api.saveConfig({ ...cfg, setupComplete: true });
+ const [cfg, st] = await Promise.all([api.config(), refreshStatus()]);
+ // An engine update the user chose not to install now: don't open Setup for it again.
+ const ui = { ...((cfg.ui ?? {}) as Record<string, unknown>) };
+ if (st?.engine?.update_needed) ui.engineUpdateSkipped = st.engine.release;
+ await api.saveConfig({ ...cfg, setupComplete: true, ui });
setState({ needsSetup: false });
// Load the model in the background; the status indicator shows progress.
api.startBackend().then(refreshStatus, toastError);
@@ -165,20 +165,18 @@ export function Setup() {
const running = inst?.running ?? false;
// While (or after) installing this preset, show the live list; otherwise what is on disk.
const live = !!inst && inst.preset === preset && inst.items.length > 0 && (running || inst.items.some((i) => i.state !== "pending" && i.state !== "present"));
- const items = (live ? inst!.items : chosen?.files ?? []).filter((i) => i.kind !== "optional" || live || upscaler);
+ const items = live ? inst!.items : chosen?.files ?? [];
const missing = items.filter((i) => i.state !== "present" && i.state !== "done");
const failed = items.filter((i) => i.state === "failed");
const paused = !running && items.some((i) => i.state === "cancelled" || (i.state === "pending" && i.received > 0));
const toDownload = missing.reduce((a, i) => a + Math.max(0, i.size - i.received), 0);
const prog = installProgress(items);
const lowSpace = hw?.free_bytes != null && chosen != null && hw.free_bytes < chosen.disk_bytes;
- const presetInstalled = missing.filter((i) => i.kind !== "optional").length === 0;
+ const presetInstalled = missing.length === 0;
const ready = !!report?.ready && !running;
const rate = inst?.bytes_per_sec ?? 0;
const vram = hw?.vram_mib ?? null;
- const optionalMissing = chosen?.files.some((f) => f.kind === "optional" && f.state !== "present");
- // Wanted extras not on disk yet (e.g. the upscaler added after the first setup).
- const extrasMissing = missing.some((i) => i.kind === "optional");
+ const engineMissing = missing.filter((i) => i.kind === "engine");
return (
<div className="setup">
@@ -191,6 +189,13 @@ export function Setup() {
</p>
</div>
+ {setupDone && engineUpdate?.update_needed && engineMissing.length > 0 && !running && (
+ <div className="setup-note">
+ This version of Kokon enlarges images with Superscale-SP by default, adds an upscaler strength slider and the experimental MoSR model. It needs the updated engine:
+ press Install to download it ({formatBytes(engineMissing.reduce((a, i) => a + Math.max(0, i.size - i.received), 0))}). Until then, images are enlarged with Lanczos.
+ </div>
+ )}
+
{!hw ? (
<div className="setup-card">
<Loader2 className="spin" size={18} /> Checking this PC…
@@ -338,18 +343,12 @@ export function Setup() {
{items.length} files · {missing.length ? `${formatBytes(toDownload)} to download` : "all installed"}
</button>
{(showFiles || running) && <FileList items={items} />}
- {optionalMissing && !running && !paused && (
- <div className="field-row" style={{ paddingTop: 4 }}>
- <span>Include the 4x-UltraSharp upscaler for sharper enlargements (67 MB, CC BY-NC-SA 4.0, non-commercial)</span>
- <Switch on={upscaler} onChange={setUpscaler} label="Include the upscaler" />
- </div>
- )}
</div>
</>
)}
<div className="setup-actions">
- {hw && !running && !paused && (!presetInstalled || extrasMissing) && (
+ {hw && !running && !paused && !presetInstalled && (
<button className="btn primary big" disabled={!chosen || lowSpace} onClick={install}>
<Download size={16} /> {failed.length ? "Try again" : `Install · ${formatBytes(toDownload)}`}
</button>
@@ -377,7 +376,7 @@ export function Setup() {
{report && !report.ready && !running && !paused && missing.length === 0 && (
<div className="setup-note">
{report.checks
- .filter((c) => !c.ok && c.id !== "upscaler")
+ .filter((c) => !c.ok)
.map((c, i) => (
<div key={i}>
<strong>{c.label}</strong>: {c.detail}
@@ -386,8 +385,8 @@ export function Setup() {
</div>
)}
<p className="muted setup-foot">
- Qwen-Image 2.1 Turbo is released by Alibaba's Qwen team under the Qwen Research License: research and evaluation only, no commercial use. By downloading it you accept that license. Downloads come only from GitHub
- (stable-diffusion.cpp) and Hugging Face, and every file is verified with its SHA-256 checksum.
+ Qwen-Image 2.1 Turbo is released by Alibaba's Qwen team under the Qwen Research License: research and evaluation only, no commercial use. By downloading it you accept that license. The upscalers are Superscale-SP by Nmkd
+ (WTFPL) and the experimental 4xNomos2_hq_mosr by Philip Hofmann (CC BY 4.0). Downloads come only from GitHub (stable-diffusion.cpp, upscaler) and Hugging Face, and every file is verified with its SHA-256 checksum.
</p>
</div>
</div>
diff --git a/src/components/Stage.tsx b/src/components/Stage.tsx
index af7310b..a9ae671 100644
--- a/src/components/Stage.tsx
+++ b/src/components/Stage.tsx
@@ -162,7 +162,8 @@ function InfoPanel({ g }: { g: GenerationRecord }) {
function UpscaleMenu(props: { source: string; size: Size; original?: Size | null; parentId?: string | null; close: () => void }) {
const { width: w, height: h } = props.size;
const up = useStore((s) => s.status?.upscaler);
- const via = up?.available ? upscalerLabel(up.model) : "Lanczos";
+ const oldEngine = useStore((s) => !!s.status?.engine?.update_needed);
+ const via = up?.available && !oldEngine ? upscalerLabel(up.model) : "Lanczos";
const [customW, setCustomW] = useState(Math.min(MAX_UPSCALE_SIDE, w * 2));
const targets = upscaleTargets(w, h, props.original);
const custom = sizeForWidth(w, h, customW);
diff --git a/src/components/Upscalers.tsx b/src/components/Upscalers.tsx
new file mode 100644
index 0000000..6a00056
--- /dev/null
+++ b/src/components/Upscalers.tsx
@@ -0,0 +1,223 @@
+import { Download, Images, Loader2, X } from "lucide-react";
+import { useEffect, useState } from "react";
+import { api } from "../lib/api";
+import { formatBytes, installProgress } from "../lib/logic";
+import { refreshStatus, setState, toastError, useStore } from "../lib/store";
+import type { InstallStatus, UpscalerItem } from "../lib/types";
+import { Seg } from "./ui";
+
+const img = import.meta.glob("../assets/upscalers/*.png", { eager: true, import: "default" }) as Record<string, string>;
+const crop = (scenario: string, method: string) => img[`../assets/upscalers/${scenario}-${method}.png`];
+
+/** What each upscaler is good and bad at, from an A/B on 8 images at x1.4, x2 and x4 (2026-10-12). */
+export const UPSCALER_NOTES: Record<string, { key: string; label: string; text: string }> = {
+ "4x_NMKD-Superscale-SP_178000_G": {
+ key: "superscale",
+ label: "Superscale-SP",
+ text: "The default. Sharp and natural on most photos and renders. On JPEG photos and dark areas it can draw a faint grid: lower the strength if you see one.",
+ },
+ "4xNomos2_hq_mosr": {
+ key: "mosr",
+ label: "MoSR (experimental)",
+ text: "Included with Kokon and the fastest. Good for big enlargements (4×), but on clean images enlarged less than about 3× it draws a fine grid pattern.",
+ },
+ "4x-UltraSharp": {
+ key: "ultrasharp",
+ label: "UltraSharp",
+ text: "Very clean, never a grid. But it smooths skin and textures into an artificial look and can invent lines and shapes, especially at night. Non-commercial license.",
+ },
+ lanczos: {
+ key: "lanczos",
+ label: "Lanczos",
+ text: "A plain resize: never invents anything, but enlargements look soft.",
+ },
+};
+
+const SCENARIOS = [
+ { key: "face", label: "Face, 1.4×", hint: "A 1.5K render enlarged to 2K. Look at the wrinkles and skin pores." },
+ { key: "jpeg", label: "JPEG photo, 2×", hint: "A JPEG portrait. Look at the forehead: some models turn JPEG blocks into a grid." },
+ { key: "night", label: "Night, 2×", hint: "Wet street with neon lights. Look for lines and squares that aren't in the scene." },
+ { key: "text", label: "Text, 2×", hint: "Gold letters on a shop sign: edges should stay clean." },
+ { key: "landscape", label: "Landscape, 1.4×", hint: "Rocks on a mountain, from a JPEG: fine detail without patterns." },
+ { key: "x4", label: "Upscale 4×", hint: "The Upscale button at 4×: every model has to invent detail here." },
+];
+const METHODS = ["4x_NMKD-Superscale-SP_178000_G", "4xNomos2_hq_mosr", "4x-UltraSharp", "lanczos"];
+
+/** Side-by-side crops of each upscaler in a few typical cases, with what each one is good at. */
+export function UpscalerCompare() {
+ const [scenario, setScenario] = useState(SCENARIOS[0].key);
+ const close = () => setState({ compareUpscalers: false });
+ useEffect(() => {
+ const onKey = (e: KeyboardEvent) => {
+ if (e.key !== "Escape") return;
+ e.stopPropagation();
+ close();
+ };
+ window.addEventListener("keydown", onKey, true);
+ return () => window.removeEventListener("keydown", onKey, true);
+ }, []);
+ const s = SCENARIOS.find((x) => x.key === scenario)!;
+ return (
+ <div className="modal-scrim" style={{ zIndex: 60 }} onMouseDown={(e) => e.target === e.currentTarget && close()}>
+ <div className="upscaler-compare" role="dialog" aria-label="Compare upscalers">
+ <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+ <h3 style={{ flex: 1, margin: 0 }}>Compare upscalers</h3>
+ <button className="icon-btn" title="Close" onClick={close}>
+ <X size={18} />
+ </button>
+ </div>
+ <span className="muted">
+ The upscaler enlarges results to their final size and runs the Upscale button. Same crops, enlarged by each one and shown at 2× zoom.
+ </span>
+ <Seg<string> value={scenario} options={SCENARIOS.map((x) => ({ value: x.key, label: x.label }))} onChange={setScenario} />
+ <span className="muted">{s.hint}</span>
+ <div className="upscaler-grid">
+ {METHODS.map((m) => (
+ <figure key={m}>
+ <img src={crop(scenario, UPSCALER_NOTES[m].key)} alt={`${UPSCALER_NOTES[m].label}: ${s.label}`} />
+ <figcaption>
+ <strong>{UPSCALER_NOTES[m].label}</strong>
+ <span>{UPSCALER_NOTES[m].text}</span>
+ </figcaption>
+ </figure>
+ ))}
+ </div>
+ </div>
+ </div>
+ );
+}
+
+/** Upscaler model, its download, and the strength slider. Controlled: Settings binds it to its
+ * draft, the Advanced menu to the saved settings. */
+export function UpscalerControls(props: { model: string; blend: number; onModel: (m: string) => void; onBlend: (b: number) => void; onBlendDone?: () => void }) {
+ const [items, setItems] = useState<UpscalerItem[] | null>(null);
+ const [inst, setInst] = useState<InstallStatus | null>(null);
+ const load = () => api.upscalers().then((r) => setItems(r.items), () => {});
+ useEffect(() => {
+ load();
+ api.installStatus().then((i) => i.running && i.preset?.startsWith("upscaler:") && setInst(i), () => {});
+ }, []);
+ const running = !!inst?.running;
+ useEffect(() => {
+ if (!running) return;
+ const t = window.setInterval(
+ () =>
+ api.installStatus().then((i) => {
+ setInst(i);
+ if (!i.running) {
+ load();
+ refreshStatus();
+ const failed = i.items.find((x) => x.state === "failed");
+ if (failed) toastError(new Error(`${failed.label}: ${failed.error ?? "download failed"}`));
+ }
+ }, () => {}),
+ 500,
+ );
+ return () => window.clearInterval(t);
+ }, [running]);
+
+ const sel = items?.find((i) => i.name === props.model);
+ const downloading = running && inst?.preset === `upscaler:${props.model}`;
+ const download = async () => {
+ try {
+ setInst(await api.downloadUpscaler(props.model));
+ } catch (e) {
+ toastError(e);
+ }
+ };
+ const note = UPSCALER_NOTES[props.model];
+ return (
+ <>
+ <label className="field-row">
+ <span>Upscaler</span>
+ <select className="select" value={props.model} onChange={(e) => props.onModel(e.target.value)}>
+ {(items ?? []).map((i) => (
+ <option key={i.name} value={i.name}>
+ {i.label}
+ {i.installed ? "" : ` (download ${formatBytes(i.size ?? 0)})`}
+ </option>
+ ))}
+ {items && !items.some((i) => i.name === props.model) && <option value={props.model}>{props.model}</option>}
+ </select>
+ </label>
+ {note && <span className="muted" style={{ marginTop: -8 }}>{note.text}</span>}
+ {sel && !sel.installed && (
+ <div className="field-row">
+ <span className="muted">{downloading ? `Downloading… ${Math.floor(installProgress(inst!.items).frac * 100)}%` : "Not installed yet: until then MoSR is used."}</span>
+ <button className="btn" disabled={running} onClick={download}>
+ {downloading ? <Loader2 className="spin" size={14} /> : <Download size={14} />} {formatBytes(sel.size ?? 0)}
+ </button>
+ </div>
+ )}
+ {props.model !== "lanczos" && (
+ <label className="field">
+ <span>Upscaler strength {Math.round(props.blend * 100)} %</span>
+ <input
+ type="range"
+ min={0}
+ max={1}
+ step={0.05}
+ value={props.blend}
+ onChange={(e) => props.onBlend(Number(e.target.value))}
+ onPointerUp={props.onBlendDone}
+ onKeyUp={props.onBlendDone}
+ />
+ </label>
+ )}
+ {props.model !== "lanczos" && (
+ <span className="muted" style={{ marginTop: -8 }}>
+ How much of the upscaler's result is kept; the rest is a plain resize. Lower it if it adds texture or patterns that aren't in the image.
+ </span>
+ )}
+ <div className="setting-card">
+ <div className="setting-card-text">
+ <strong>Not sure which one?</strong>
+ <span className="muted">See them side by side on a face, a JPEG photo, text and a night street.</span>
+ </div>
+ <button className="btn" onClick={() => setState({ compareUpscalers: true })}>
+ <Images size={15} /> Compare
+ </button>
+ </div>
+ </>
+ );
+}
+
+/** [`UpscalerControls`] bound to the saved settings (the Advanced menu: no Save button). */
+export function UpscalerSettings() {
+ const [model, setModel] = useState<string | null>(null);
+ const [blend, setBlend] = useState(1);
+ useEffect(() => {
+ api.config().then((c) => {
+ setModel(c.upscalerModel);
+ setBlend(c.upscaleBlend);
+ }, toastError);
+ }, []);
+ const save = async (patch: { upscalerModel?: string; upscaleBlend?: number }) => {
+ try {
+ const c = await api.config();
+ await api.saveConfig({ ...c, ...patch });
+ refreshStatus();
+ } catch (e) {
+ toastError(e);
+ }
+ };
+ const upscaling = useStore((s) => s.status?.upscaler?.model);
+ if (model === null) return null;
+ return (
+ <div className="field" style={{ gap: 10 }}>
+ <span className="muted" style={{ fontSize: 12 }}>
+ Enlarging (all images){upscaling && upscaling !== model ? ` · now using ${UPSCALER_NOTES[upscaling]?.label ?? upscaling}` : ""}
+ </span>
+ <UpscalerControls
+ model={model}
+ blend={blend}
+ onModel={(m) => {
+ setModel(m);
+ save({ upscalerModel: m });
+ }}
+ onBlend={setBlend}
+ onBlendDone={() => save({ upscaleBlend: blend })}
+ />
+ </div>
+ );
+}
diff --git a/src/components/Welcome.tsx b/src/components/Welcome.tsx
index 96a3020..e36a7c0 100644
--- a/src/components/Welcome.tsx
+++ b/src/components/Welcome.tsx
@@ -10,6 +10,7 @@ import replace from "../assets/showcase/replace.jpg";
import restyle from "../assets/showcase/restyle.jpg";
import text from "../assets/showcase/text.jpg";
import { api } from "../lib/api";
+import { WHATS_NEW_VERSION } from "./WhatsNew";
import { isMac } from "../lib/platform";
import { autoCheckEnabled } from "../lib/updates";
import { setState, toastError, useStore } from "../lib/store";
@@ -28,7 +29,8 @@ async function markSeen(updateCheck: boolean) {
try {
const cfg = await api.config();
const ui = (cfg.ui ?? {}) as Record<string, unknown>;
- if (!ui.welcomeSeen || autoCheckEnabled(ui) !== updateCheck) await api.saveConfig({ ...cfg, ui: { ...ui, welcomeSeen: true, updateCheck } });
+ // A new install starts on this release: its "what's new" notes are not shown.
+ if (!ui.welcomeSeen || autoCheckEnabled(ui) !== updateCheck) await api.saveConfig({ ...cfg, ui: { whatsNewSeen: WHATS_NEW_VERSION, ...ui, welcomeSeen: true, updateCheck } });
} catch (e) {
toastError(e);
}
diff --git a/src/components/WhatsNew.tsx b/src/components/WhatsNew.tsx
new file mode 100644
index 0000000..7a8d613
--- /dev/null
+++ b/src/components/WhatsNew.tsx
@@ -0,0 +1,170 @@
+import { CircleAlert, Images, LayoutGrid, Maximize, SlidersHorizontal, Sparkles } from "lucide-react";
+import { useEffect, useState } from "react";
+import { api } from "../lib/api";
+import { formatBytes, installProgress, installStep, installTimeLeft } from "../lib/logic";
+import { refreshStatus, setState, toastError, useStore } from "../lib/store";
+import type { GpuBackend, InstallItem, InstallStatus } from "../lib/types";
+import { KokonMark } from "./Welcome";
+
+/** The release these notes describe. Shown once to people updating from an earlier version. */
+export const WHATS_NEW_VERSION = "0.9.1";
+
+const NEWS = [
+ {
+ icon: Sparkles,
+ title: "Superscale-SP by default",
+ text: "Results are enlarged with a sharper, more natural upscaler. The previous one, UltraSharp, was great on some images but smoothed skin and textures into an artificial look on others. You can still download it.",
+ },
+ {
+ icon: SlidersHorizontal,
+ title: "Choose your upscaler",
+ text: "In the Advanced menu next to the prompt: Superscale-SP, the experimental MoSR (very fast, included), UltraSharp or a plain resize, a strength slider, and a side-by-side comparison.",
+ },
+ {
+ icon: LayoutGrid,
+ title: "Gallery preview",
+ text: "Click an image in the gallery for a large preview and browse with the arrow keys; F or a double-click for full screen. Enter opens it in its project.",
+ },
+ {
+ icon: Maximize,
+ title: "Full screen and renaming",
+ text: "Full screen follows the project's timeline: the arrow keys step through versions without leaving it. Renaming now starts from the current name.",
+ },
+];
+
+/** Remembers that these notes were read and, if the engine update was postponed, for which
+ * release, so neither is offered again at the next start. */
+async function markSeen(engineSkipped: string | null) {
+ try {
+ const cfg = await api.config();
+ const ui: Record<string, unknown> = { ...((cfg.ui ?? {}) as Record<string, unknown>), whatsNewSeen: WHATS_NEW_VERSION };
+ if (engineSkipped) ui.engineUpdateSkipped = engineSkipped;
+ await api.saveConfig({ ...cfg, ui });
+ } catch (e) {
+ toastError(e);
+ }
+}
+
+/** Whether to show the notes at start: once per release after an update (not on a new install,
+ * which gets the welcome screen), and again while a needed engine update was not postponed. */
+export function whatsNewDue(ui: Record<string, unknown>, engine: { release: string; update_needed: boolean } | undefined): boolean {
+ if (!ui.welcomeSeen) return false;
+ return ui.whatsNewSeen !== WHATS_NEW_VERSION || (!!engine?.update_needed && ui.engineUpdateSkipped !== engine.release);
+}
+
+/** What's new in this release, plus the engine download when the release needs a newer
+ * stable-diffusion.cpp (only the files that changed; models and settings stay as they are). */
+export function WhatsNew() {
+ const engine = useStore((s) => s.status?.engine);
+ const needsEngine = !!engine?.update_needed;
+ const [missing, setMissing] = useState<InstallItem[] | null>(null);
+ const [target, setTarget] = useState<{ preset: string; backend: GpuBackend } | null>(null);
+ const [inst, setInst] = useState<InstallStatus | null>(null);
+
+ useEffect(() => {
+ if (!needsEngine) return;
+ api.hardware().then((h) => {
+ const preset = h.presets.find((p) => p.id === h.current) ?? h.presets.find((p) => p.id === h.recommended);
+ setTarget(preset ? { preset: preset.id, backend: h.backend } : null);
+ setMissing((preset?.files ?? []).filter((f) => f.state !== "present"));
+ }, toastError);
+ api.installStatus().then((i) => i.running && setInst(i), () => {});
+ }, [needsEngine]);
+
+ const running = inst?.running ?? false;
+ useEffect(() => {
+ if (!running) return;
+ const t = window.setInterval(() => api.installStatus().then(setInst, () => {}), 500);
+ return () => window.clearInterval(t);
+ }, [running]);
+
+ const items = inst?.items ?? missing ?? [];
+ const failed = items.filter((i) => i.state === "failed");
+ const done = !!inst && !inst.running && inst.complete;
+ const size = (missing ?? []).reduce((a, i) => a + Math.max(0, i.size - i.received), 0);
+ const prog = installProgress(items);
+ const showEngine = needsEngine || !!inst;
+
+ const update = async () => {
+ if (!target) return;
+ try {
+ setInst(await api.install(target.preset, target.backend, false));
+ } catch (e) {
+ toastError(e);
+ }
+ };
+ const close = (postponed: boolean) => {
+ if (running) api.cancelInstall().catch(() => {});
+ setState({ overlay: null });
+ markSeen(postponed && engine ? engine.release : null);
+ refreshStatus();
+ api.startBackend().then(refreshStatus, () => refreshStatus());
+ };
+
+ return (
+ <div className="modal-scrim">
+ <div className="welcome" role="dialog" aria-label={`What's new in Kokon ${WHATS_NEW_VERSION}`}>
+ <KokonMark size={44} />
+ <h1>What's new in Kokon {WHATS_NEW_VERSION}</h1>
+ <div className="welcome-grid">
+ {NEWS.map(({ icon: Icon, title, text }) => (
+ <div className="welcome-item" key={title}>
+ <Icon size={20} />
+ <strong>{title}</strong>
+ <span>{text}</span>
+ </div>
+ ))}
+ </div>
+ <button className="btn" onClick={() => setState({ compareUpscalers: true })}>
+ <Images size={14} /> Compare the upscalers
+ </button>
+
+ {showEngine && !done && (
+ <p className="welcome-lead">
+ This version needs a newer stable-diffusion.cpp, the engine that runs the models on your graphics chip, and the Superscale-SP model. Your images, models and settings stay
+ as they are.
+ </p>
+ )}
+ {(running || (inst && !done && !failed.length)) && (
+ <div className="setup-card setup-progress" style={{ width: "100%", textAlign: "left" }}>
+ <div className="setup-progress-head">
+ <span className="pct">{Math.floor(prog.frac * 100)}%</span>
+ <span className="muted">
+ {formatBytes(prog.received)} of {formatBytes(prog.total)}
+ {installTimeLeft(prog.total - prog.received, inst?.bytes_per_sec ?? 0) ? ` · ${installTimeLeft(prog.total - prog.received, inst?.bytes_per_sec ?? 0)}` : ""}
+ </span>
+ </div>
+ <div className="progress thick">
+ <i style={{ width: `${prog.frac * 100}%` }} />
+ </div>
+ <span className="muted">{installStep(items) ?? "Starting…"}</span>
+ </div>
+ )}
+ {failed.length > 0 && !running && (
+ <div className="setup-note" style={{ width: "100%", textAlign: "left" }}>
+ <CircleAlert size={14} /> {failed.map((f) => `${f.label}: ${f.error}`).join(" · ")}
+ <div className="muted">Try again, or open Settings → Models → Set up models… to download it by hand.</div>
+ </div>
+ )}
+
+ {!showEngine || done ? (
+ <button className="btn primary big" onClick={() => close(false)}>
+ {done ? "Start creating" : "Got it"}
+ </button>
+ ) : (
+ <>
+ <div style={{ display: "flex", gap: 10 }}>
+ <button className="btn primary big" disabled={running || !target || missing === null} onClick={update}>
+ {failed.length ? "Try again" : running ? "Updating…" : `Update now${size ? ` · ${formatBytes(size)}` : ""}`}
+ </button>
+ <button className="btn big" onClick={() => close(true)}>
+ Later
+ </button>
+ </div>
+ <span className="muted welcome-foot">Until you update, enlargements use a plain resize. You can update later from Settings → Models → Set up models…</span>
+ </>
+ )}
+ </div>
+ </div>
+ );
+}
diff --git a/src/lib/api.ts b/src/lib/api.ts
index 3af9869..c11a1bd 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -4,6 +4,7 @@
import type {
GpuBackend,
AppConfig, AppErrorBody, GenerationRecord, GenerationRequest, HardwareReport, InputRecord, InstallStatus, JobView, Plan, ServiceEvent, SetupReport, StatusResponse,
+ UpscalerItem,
} from "./types";
export class ApiError extends Error {
@@ -54,7 +55,15 @@ export const api = {
status: () => call<StatusResponse>("/status"),
setup: () => call<SetupReport>("/setup"),
hardware: (backend?: GpuBackend) => call<HardwareReport>(backend ? `/setup/hardware?backend=${backend}` : "/setup/hardware"),
- install: (preset: string, upscaler: boolean, backend: GpuBackend) => call<InstallStatus>("/setup/install", { method: "POST", body: json({ preset, upscaler, backend }) }),
+ /** `apply = false`: only download (an engine update), keeping the configured preset and settings. */
+ install: (preset: string, backend: GpuBackend, apply = true) => call<InstallStatus>("/setup/install", { method: "POST", body: json({ preset, backend, apply }) }),
+ upscalers: () => call<{ selected: string; active: string | null; items: UpscalerItem[] }>("/upscalers"),
+ /** Progress in `installStatus` (preset "upscaler:<name>"). */
+ downloadUpscaler: (name: string) => call<InstallStatus>(`/upscalers/${encodeURIComponent(name)}/download`, { method: "POST" }),
+ /** ESRGAN models of earlier versions in the app's own folder. */
+ legacyUpscalers: (keep: string) => call<{ files: string[]; bytes: number }>(`/setup/legacy-upscalers?keep=${encodeURIComponent(keep)}`),
+ /** `keep`: the model chosen in Settings, even if not saved yet. */
+ removeLegacyUpscalers: (keep: string) => call<{ freed_bytes: number }>(`/setup/legacy-upscalers?keep=${encodeURIComponent(keep)}`, { method: "DELETE" }),
installStatus: () => call<InstallStatus>("/setup/install"),
cancelInstall: () => call<InstallStatus>("/setup/install/cancel", { method: "POST" }),
config: () => call<AppConfig>("/config"),
diff --git a/src/lib/logic.test.ts b/src/lib/logic.test.ts
index a152eb9..8e90d14 100644
--- a/src/lib/logic.test.ts
+++ b/src/lib/logic.test.ts
@@ -166,9 +166,9 @@ describe("upscaling", () => {
it("describes plans", () => {
const p = {
output: { width: 2752, height: 1536 }, working: { width: 2080, height: 1152 }, content: { x: 12, y: 2, width: 2056, height: 1148 },
- upscaler: "4x-UltraSharp", upscale: null,
+ upscaler: "4xNomos2_hq_mosr", upscale: null,
} as unknown as Plan;
- expect(planPipeline(p)).toBe("2080×1152 render → 2752×1536 output (UltraSharp)");
+ expect(planPipeline(p)).toBe("2080×1152 render → 2752×1536 output (MoSR)");
const quick = { ...p, upscaler: null, upscale: { method: "quick", source: { width: 1376, height: 768 } } } as Plan;
expect(planPipeline(quick)).toBe("1376×768 → 2752×1536 (Lanczos)");
});
diff --git a/src/lib/logic.ts b/src/lib/logic.ts
index 6142f28..cb43b6b 100644
--- a/src/lib/logic.ts
+++ b/src/lib/logic.ts
@@ -394,16 +394,19 @@ export function upscaleRequest(source: string, target: Size, parentId?: string |
}
const dims = (s: Size) => `${s.width}×${s.height}`;
-/** ESRGAN models offered for enlargement: [file stem, label]. Mirrors UPSCALER_CHOICES in config.rs. */
+/** Upscaler models offered in Settings: [file stem, label]. Mirrors UPSCALER_CHOICES in config.rs. */
export const UPSCALERS: [string, string][] = [
- ["4x-UltraSharp", "UltraSharp"],
["4x_NMKD-Superscale-SP_178000_G", "Superscale-SP"],
+ ["4xNomos2_hq_mosr", "MoSR"],
+ ["4x-UltraSharp", "UltraSharp"],
+ ["lanczos", "Lanczos"],
];
+const UPSCALER_LABELS: Record<string, string> = Object.fromEntries(UPSCALERS);
-/** Short name of the upscaler that ran or will run: "UltraSharp", "Superscale-SP", "Lanczos"... */
-export const upscalerLabel = (name: string | null | undefined) => (!name || name === "Lanczos" ? "Lanczos" : UPSCALERS.find(([n]) => n === name)?.[1] ?? name);
+/** Short name of the upscaler that ran or will run: "Superscale-SP", "MoSR", "Lanczos"... */
+export const upscalerLabel = (name: string | null | undefined) => (!name || name === "Lanczos" ? "Lanczos" : UPSCALER_LABELS[name] ?? name);
-/** "1376×768 → 5120×2880 (UltraSharp)" for the Details panel; two-pass records from
+/** "1376×768 → 5120×2880 (MoSR)" for the Details panel; two-pass records from
* older versions read "1376×768 → refined 2048×1152 (Fast, 6 steps, UltraSharp) → ...". */
export function pipelineSummary(g: GenerationRecord): string | null {
const p = g.pipeline;
diff --git a/src/lib/store.ts b/src/lib/store.ts
index d758bb3..953b004 100644
--- a/src/lib/store.ts
+++ b/src/lib/store.ts
@@ -10,7 +10,7 @@ import { api, ApiError, setPrivateInputs, subscribe } from "./api";
import { buildRequest, emptyComposer, needsPrompt, newKey, persistentAdvanced, refFromGen, refFromInput, timelineLinks, undoTarget, versionLabels, type CompareMode, type Composer, type Ref } from "./logic";
import type { AppErrorBody, GenerationRecord, GenerationRequest, InputRecord, JobView, ServerState, StatusResponse } from "./types";
-export type Overlay = null | "gallery" | "settings" | "inpaint" | "expand" | "welcome";
+export type Overlay = null | "gallery" | "settings" | "inpaint" | "expand" | "welcome" | "whats-new";
export interface SessionItem {
key: string;
@@ -68,6 +68,8 @@ export interface State {
/** Last submitted prompt (Up arrow in an empty prompt brings it back). */
lastPrompt: string;
overlay: Overlay;
+ /** The upscaler comparison, shown over any overlay (Settings, the Advanced menu). */
+ compareUpscalers: boolean;
toasts: Toast[];
galleryVersion: number;
needsSetup: boolean;
@@ -275,6 +277,7 @@ let state: State = {
composer: emptyComposer(loadPrefs()),
lastPrompt: "",
overlay: null,
+ compareUpscalers: false,
toasts: [],
galleryVersion: 0,
needsSetup: false,
diff --git a/src/lib/types.ts b/src/lib/types.ts
index eb55770..a5b4475 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -79,6 +79,8 @@ export interface Plan {
/** Calibrated to this machine after its first image; 0 = not measured yet. */
estimated_seconds: number;
upscaler: string | null;
+ /** Upscaler tile size in px (0 in plans of older versions). */
+ upscale_tile?: number;
upscale: { method: UpscaleMethod; source: Size } | null;
}
@@ -178,6 +180,8 @@ export interface StatusResponse {
active_job: JobView | null;
queue: { queued: number; jobs: JobView[] };
upscaler?: { model: string; available: boolean };
+ /** The installed engine predates `release` (needed for the upscaler): Setup updates it. */
+ engine?: { release: string; update_needed: boolean };
setup_complete: boolean;
}
@@ -217,9 +221,14 @@ export interface AppConfig {
vaeTileSize: number;
prefixCacheType: string;
eagerLoad: boolean;
- upscalersDir: string | null;
+ /** Upscaler model (file stem); the bundled MoSR runs when its file is missing. */
upscalerModel: string;
+ /** Upscaler tile size in px; 0 = automatic (ESRGAN 128; MoSR 768, or 256 under 14 GB). */
upscaleTileSize: number;
+ /** Share of the upscaler's result kept over a Lanczos enlargement (0..1). */
+ upscaleBlend: number;
+ /** Shrink the input before upscaling (enlargements under ~2.8x). */
+ upscalePrescale: boolean;
extraServerArgs: string[];
outputDir: string;
keepServerRunning: boolean;
@@ -237,7 +246,7 @@ export type InstallItemState = "present" | "pending" | "downloading" | "verifyin
export interface InstallItem {
id: string;
label: string;
- kind: "engine" | "model" | "optional";
+ kind: "engine" | "model";
size: number;
received: number;
state: InstallItemState;
@@ -248,6 +257,9 @@ export interface InstallItem {
path: string;
}
+/** An upscaler offered in Settings (`GET /upscalers`). */
+export interface UpscalerItem { name: string; label: string; installed: boolean; size: number | null; page: string | null }
+
export interface InstallStatus {
running: boolean;
complete: boolean;
diff --git a/src/styles.css b/src/styles.css
index 7bb29a9..af061e2 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -538,3 +538,13 @@ pre.diag { font-family: ui-monospace, "Cascadia Mono", Consolas, monospace; font
.tour-dots i { width: 6px; height: 6px; border-radius: 50%; background: var(--surface-3); }
.tour-dots i.on { background: var(--text); }
@media (prefers-reduced-motion: reduce) { .tour-hole, .tour-card { transition: none; } }
+
+/* Upscalers: separator in the Advanced menu and the comparison dialog. */
+.menu-sep { border: 0; border-top: 1px solid var(--border); margin: 4px 0; width: 100%; }
+.upscaler-compare { width: min(880px, 94vw); max-height: 92vh; overflow-y: auto; background: var(--bg); border-radius: 18px; box-shadow: var(--shadow); padding: 22px 24px; display: flex; flex-direction: column; gap: 12px; }
+.upscaler-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 10px; }
+.upscaler-grid figure { margin: 0; display: flex; flex-direction: column; gap: 6px; min-width: 0; }
+.upscaler-grid img { width: 100%; aspect-ratio: 1; image-rendering: pixelated; border-radius: 10px; background: var(--surface); }
+.upscaler-grid figcaption { display: flex; flex-direction: column; gap: 2px; font-size: 12px; line-height: 1.4; color: var(--text-2); }
+.upscaler-grid figcaption strong { color: var(--text); font-size: 13px; }
+@media (max-width: 760px) { .upscaler-grid { grid-template-columns: repeat(2, 1fr); } }