Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.
TypeScript ai-photo-editorcomfyui-alternativegenerative-fillimage-editingimage-generationinpaintinglinuxlocal-aimacosmcpmcp-servernano-banana-alternativeofflinephoto-editorprivacyqwen-imageqwen-image-2-1stable-diffusion-cppvulkanwindows
feat(mac): macOS 15 Sequoia support with Kokon's own Metal engine build (#24)
Gabriele Lozupone14ade1eb7d8e
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 602bbb0..49e179d 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -23,7 +23,7 @@ npx tauri dev # run the desktop app in developmentpowershell -ExecutionPolicy Bypass -File scripts\build-release.ps1 # installer```-**Mac (Apple Silicon, macOS 26+):** Xcode Command Line Tools, Rust and Node 22+.+**Mac (Apple Silicon, macOS 15+):** Xcode Command Line Tools, Rust and Node 22+.```bashbash scripts/dev/mac-dev.sh --check # check the prerequisitesdiff --git a/README.md b/README.mdindex 5fea5b0..663feb3 100644--- a/README.md+++ b/README.md@@ -611,7 +611,7 @@ npx tauri dev # run the desktop app in developmentpowershell -ExecutionPolicy Bypass -File scripts\build-release.ps1 # installer```-**Mac (Apple Silicon, macOS 26+):** Xcode Command Line Tools, Rust and Node 22+.+**Mac (Apple Silicon, macOS 15+):** Xcode Command Line Tools, Rust and Node 22+.```bashbash scripts/dev/mac-dev.sh --check # check the prerequisitesdiff --git a/crates/qls-core/src/catalog.rs b/crates/qls-core/src/catalog.rsindex 0120639..0dc78b8 100644--- a/crates/qls-core/src/catalog.rs+++ b/crates/qls-core/src/catalog.rs@@ -237,22 +237,30 @@ const LINUX_VULKAN_SIZE: u64 = 38_456_278;#[cfg(target_os = "linux")]const LINUX_VULKAN_SHA256: &str = "d998e8b831e9228571e7203020f503a3fea70b87f57ba5e0a106ae4e3afb7f60";-/// Same commit, macOS build: universal binary with the Metal shaders embedded, needs-/// macOS 26. Ad-hoc signed; downloaded by the app (not a browser) it gets no quarantine flag.+/// Kokon's macOS build of the same commit (fork `kokon-linux`, workflow kokon-macos.yml): upstream's+/// Mac zip declares macOS 26 as its minimum (built with the 26 SDK, no deployment target); this one+/// is built for macOS 15 (#24), upstream's flags otherwise. Universal binary with the Metal shaders+/// embedded. Ad-hoc signed; downloaded by the app (not a browser) it gets no quarantine flag.+const KOKON_MACOS_RELEASE: &str = "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/kokon-macos-1d0a58a";+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-964-1d0a58a/sd-master-1d0a58a-bin-Darwin-macOS-26.6.2-arm64.zip",+ url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-macos-1d0a58a/sd-master-1d0a58a-bin-Darwin-macOS-15.0-arm64.zip",fallback_urls: &[],- page: SDCPP_RELEASE,- size: 35_213_648,- sha256: "45001839e925f98ecd18ef5251725f74cff874eeac4599f1136acba65b26911e",- dest: "engine-metal/sd-master-1d0a58a-bin-Darwin-macOS-26.6.2-arm64.zip",+ page: KOKON_MACOS_RELEASE,+ size: MACOS_METAL_SIZE,+ sha256: MACOS_METAL_SHA256,+ dest: "engine-metal/sd-master-1d0a58a-bin-Darwin-macOS-15.0-arm64.zip",provides: &["engine-metal/sd-server", "engine-metal/libstable-diffusion.dylib"],engine_tag: Some(ENGINE_TAG),};+// From the kokon-macos-1d0a58a release (run 38907832092, 2026-10-16: minos 15.0, Metal initialised on a macOS 15.7 runner).+const MACOS_METAL_SIZE: u64 = 35_215_022;+const MACOS_METAL_SHA256: &str = "d9b2d6885e0b0cdbdb5a1acd629cf0191e748c2806d3e529d4a6ae1a60bd207e";+/// The engine files of a backend, in download order: the engine manifest's release when one/// newer than the built-in pins was applied ([`apply_engine_release`]), else the pins.pub fn engine_downloads(backend: GpuBackend) -> Vec<Download> {@@ -302,7 +310,12 @@ pub struct EngineManifest {pub min_app: String,pub cuda: ManifestAsset,pub vulkan: ManifestAsset,+ /// Upstream's Mac build (macOS 26+), for apps up to 0.9.3.pub metal: ManifestAsset,+ /// Kokon's macOS 15 build of the same commit (`kokon-macos-<commit>` in the fork), used by+ /// apps from 0.9.4. Without it Macs keep their pinned engine: upstream's needs macOS 26.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub metal_macos15: Option<ManifestAsset>,}/// Build number of an upstream release tag (`master-964-1d0a58a` -> 964).@@ -333,20 +346,35 @@ pub fn apply_engine_release(m: &EngineManifest, app_version: &str) -> Result<boo*ENGINE_OVERRIDE.write().unwrap() = None;return Ok(false);}- let page = format!("https://github.com/leejet/stable-diffusion.cpp/releases/tag/{}", m.tag);- let prefix = format!("https://github.com/leejet/stable-diffusion.cpp/releases/download/{}/", m.tag);let leak = |s: String| -> &'static str { Box::leak(s.into_boxed_str()) };let tag = leak(m.tag.clone());- let page = leak(page);- let build = |a: &ManifestAsset, base: Download, folder: &str| -> Result<Download, String> {- let file = a.url.strip_prefix(&prefix).filter(|f| !f.is_empty() && !f.contains(['/', '\\'])).ok_or_else(|| format!("unexpected engine URL: {}", a.url))?;+ let upstream = format!("https://github.com/leejet/stable-diffusion.cpp/releases/download/{}/", m.tag);+ let upstream_page = leak(format!("https://github.com/leejet/stable-diffusion.cpp/releases/tag/{}", m.tag));+ let commit = m.tag.rsplit('-').next().unwrap_or_default();+ let kokon = format!("https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-macos-{commit}/");+ let kokon_page = leak(format!("https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/tag/kokon-macos-{commit}"));+ let build = |a: &ManifestAsset, base: Download, folder: &str, prefix: &str, page: &'static str| -> Result<Download, String> {+ let file = a.url.strip_prefix(prefix).filter(|f| !f.is_empty() && !f.contains(['/', '\\'])).ok_or_else(|| format!("unexpected engine URL: {}", a.url))?;if a.sha256.len() != 64 || !a.sha256.chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()) || a.size == 0 {return Err(format!("bad size or SHA-256 for {}", a.url));}Ok(Download { url: leak(a.url.clone()), page, size: a.size, sha256: leak(a.sha256.clone()), dest: leak(format!("{folder}{file}")), engine_tag: Some(tag), ..base })};- let r = EngineRelease { tag, cuda: build(&m.cuda, ENGINE_CUDA, "")?, vulkan: build(&m.vulkan, ENGINE_VULKAN, "engine-vulkan/")?, metal: build(&m.metal, ENGINE_METAL, "engine-metal/")? };- *ENGINE_OVERRIDE.write().unwrap() = Some(r);+ let cuda = build(&m.cuda, ENGINE_CUDA, "", &upstream, upstream_page)?;+ let vulkan = build(&m.vulkan, ENGINE_VULKAN, "engine-vulkan/", &upstream, upstream_page)?;+ let upstream_metal = build(&m.metal, ENGINE_METAL, "engine-metal/", &upstream, upstream_page)?;+ let metal15 = m.metal_macos15.as_ref().map(|a| build(a, ENGINE_METAL, "engine-metal/", &kokon, kokon_page)).transpose()?;+ let metal = if cfg!(target_os = "macos") {+ // Macs run only Kokon's macOS 15 builds: no such build, no engine update.+ let Some(metal) = metal15 else {+ *ENGINE_OVERRIDE.write().unwrap() = None;+ return Ok(false);+ };+ metal+ } else {+ upstream_metal+ };+ *ENGINE_OVERRIDE.write().unwrap() = Some(EngineRelease { tag, cuda, vulkan, metal });Ok(true)}@@ -774,7 +802,11 @@ mod tests {size: 1,sha256: "0".repeat(64),};- EngineManifest { tag: format!("master-{n}-abcdef0"), min_app: "0.9.2".into(), cuda: asset("win-cuda12-x64"), vulkan: asset("win-vulkan-x64"), metal: asset("Darwin-macOS-26.6.2-arm64") }+ EngineManifest { tag: format!("master-{n}-abcdef0"), min_app: "0.9.2".into(), cuda: asset("win-cuda12-x64"), vulkan: asset("win-vulkan-x64"), metal: asset("Darwin-macOS-26.6.2-arm64"), metal_macos15: Some(ManifestAsset {+ url: "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-macos-abcdef0/sd-master-abcdef0-bin-Darwin-macOS-15.0-arm64.zip".into(),+ size: 1,+ sha256: "1".repeat(64),+ }) }}#[test]@@ -793,7 +825,14 @@ mod tests {assert_eq!(cuda[0].provides, ENGINE_CUDA.provides);assert_eq!(cuda[1].id, "cuda_runtime");assert_eq!(engine_downloads(GpuBackend::Vulkan)[0].dest, "engine-vulkan/sd-master-abcdef0-bin-win-vulkan-x64.zip");- assert_eq!(engine_downloads(GpuBackend::Metal)[0].dest, "engine-metal/sd-master-abcdef0-bin-Darwin-macOS-26.6.2-arm64.zip");+ let metal = engine_downloads(GpuBackend::Metal)[0];+ if cfg!(target_os = "macos") {+ // Kokon's macOS 15 build, never upstream's (macOS 26).+ assert_eq!(metal.dest, "engine-metal/sd-master-abcdef0-bin-Darwin-macOS-15.0-arm64.zip");+ assert!(metal.page.ends_with("/kokon-macos-abcdef0"));+ } else {+ assert_eq!(metal.dest, "engine-metal/sd-master-abcdef0-bin-Darwin-macOS-26.6.2-arm64.zip");+ }// Only official release downloads of that tag, with a real hash.let mut bad = manifest(971);bad.cuda.url = "https://example.com/sd.zip".into();@@ -803,6 +842,14 @@ mod tests {assert!(apply_engine_release(&bad, "0.9.2").is_err());assert!(apply_engine_release(&EngineManifest { tag: "kokon-x".into(), ..manifest(971) }, "0.9.2").is_err());assert_eq!(engine_tag(), "master-970-abcdef0", "a bad manifest keeps the last good release");+ // Kokon's macOS 15 build must come from the fork release of the same commit.+ let mut bad = manifest(971);+ bad.metal_macos15.as_mut().unwrap().url = "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-macos-1234567/x.zip".into();+ assert!(apply_engine_release(&bad, "0.9.2").is_err(), "another commit's build");+ // A manifest without it (written for apps up to 0.9.3) updates PCs; Macs keep their pin.+ let old = EngineManifest { metal_macos15: None, ..manifest(972) };+ assert!(!serde_json::to_string(&old).unwrap().contains("metal_macos15"));+ assert_eq!(apply_engine_release(&old, "0.9.2"), Ok(!cfg!(target_os = "macos")));// An app that pins a newer engine drops an older manifest release.assert_eq!(apply_engine_release(&manifest(960), "0.9.2"), Ok(false));assert_eq!(engine_tag(), ENGINE_TAG);diff --git a/crates/qls-core/src/config.rs b/crates/qls-core/src/config.rsindex 54c0f69..30b6d94 100644--- a/crates/qls-core/src/config.rs+++ b/crates/qls-core/src/config.rs@@ -74,7 +74,7 @@ pub enum GpuBackend {Cuda,/// AMD, Intel and NVIDIA through Vulkan. Works on NVIDIA; AMD/Intel unverified.Vulkan,- /// Apple Silicon (Metal build, macOS 26+). Beta.+ /// Apple Silicon (Metal build, macOS 15+). Beta.Metal,}diff --git a/docs/engineering-notes.md b/docs/engineering-notes.mdindex 00d812c..188f956 100644--- a/docs/engineering-notes.md+++ b/docs/engineering-notes.md@@ -49,7 +49,7 @@ Details and the reasoning are in [platforms.md](platforms.md); the short version| --- | --- | --- | --- || Windows + NVIDIA | CUDA 12 build | `<sdcpp>` | `--backend cuda0 --params-backend te=cpu`, SageAttention || Windows + AMD / Intel (also NVIDIA) | Vulkan build | `<sdcpp>/engine-vulkan` | `--backend vulkan0`, no SageAttention |-| macOS, Apple Silicon | Metal build (macOS 26+) | `<sdcpp>/engine-metal` | `--backend mtl0 --mmap`; 24 GB+: `--auto-fit off` (all weights on the GPU, zero-copy); 16 GB: `--params-backend disk` |+| macOS, Apple Silicon | Metal build (macOS 15+) | `<sdcpp>/engine-metal` | `--backend mtl0 --mmap`; 24 GB+: `--auto-fit off` (all weights on the GPU, zero-copy); 16 GB: `--params-backend disk` |- `GpuBackend` in `config.rs` picks the engine, its folder, device name and flags. Each engineis a pinned download in `catalog.rs`, so both Windows engines can stay installed.diff --git a/docs/linux.md b/docs/linux.mdindex 2291f40..cfd36a3 100644--- a/docs/linux.md+++ b/docs/linux.md@@ -60,7 +60,13 @@ direct-convolution fix and FLUX.3 Klein). When Windows/Mac move to a newer engin3. Wait for the run; it publishes `kokon-linux-<new commit>`. Check the glibc report in the build log.4. In Kokon: update the Linux URLs, sizes and SHA-256 in `catalog.rs` with the `ENGINE_TAG` bump,test once in WSL (engine download + one image), release.-5. Same pipeline later for #24: a Mac engine built for macOS 15 (planned 0.9.4).+5. **Mac too (#24, from 0.9.4):** the same push runs `kokon-macos.yml` (same `ENGINE_SHORT` to set),+ which builds upstream's Mac job with `CMAKE_OSX_DEPLOYMENT_TARGET=15.0`, checks `minos` 15.0, starts+ the engine on a macOS 15 runner and publishes prerelease `kokon-macos-<commit>`+ (`sd-master-<commit>-bin-Darwin-macOS-15.0-arm64.zip`). Pin it in `catalog.rs` (`ENGINE_METAL`,+ `MACOS_METAL_*`) and add it to `engine.json` as `metal_macos15`: apps from 0.9.4 on a Mac take+ engine updates only from that entry (`metal` stays upstream's build for apps up to 0.9.3, on 26).+ The two workflows ignore each other's file, so editing one doesn't rebuild the other.## Building and testing the Linux appdiff --git a/engine.json b/engine.jsonindex 1aaf258..a3993bb 100644--- a/engine.json+++ b/engine.json@@ -15,5 +15,10 @@"url": "https://github.com/leejet/stable-diffusion.cpp/releases/download/master-964-1d0a58a/sd-master-1d0a58a-bin-Darwin-macOS-26.6.2-arm64.zip","size": 35213648,"sha256": "45001839e925f98ecd18ef5251725f74cff874eeac4599f1136acba65b26911e"+ },+ "metal_macos15": {+ "url": "https://github.com/GabrieleLozupone/stable-diffusion.cpp/releases/download/kokon-macos-1d0a58a/sd-master-1d0a58a-bin-Darwin-macOS-15.0-arm64.zip",+ "size": 35215022,+ "sha256": "d9b2d6885e0b0cdbdb5a1acd629cf0191e748c2806d3e529d4a6ae1a60bd207e"}}diff --git a/scripts/dev/mac-dev.sh b/scripts/dev/mac-dev.shindex 19108c8..7525b5e 100755--- a/scripts/dev/mac-dev.sh+++ b/scripts/dev/mac-dev.sh@@ -4,7 +4,7 @@# bash scripts/dev/mac-dev.sh # build and start the app# bash scripts/dev/mac-dev.sh --check # only check the prerequisites#-# Needs: macOS 26+, Xcode Command Line Tools, Rust (rustup), Node.js 22+.+# Needs: macOS 15+ (Sequoia), Xcode Command Line Tools, Rust (rustup), Node.js 22+.set -euo pipefailcd "$(dirname "$0")/../.."ROOT="$(pwd)"@@ -16,7 +16,7 @@ ok() { echo "✓ $1"; }[ "$(uname -s)" = Darwin ] || fail "This script is for macOS."[ "$(uname -m)" = arm64 ] || fail "Kokon on Mac needs Apple Silicon (M1 or newer)."MACOS="$(sw_vers -productVersion)"-[ "${MACOS%%.*}" -ge 26 ] || fail "macOS $MACOS: the stable-diffusion.cpp build needs macOS 26 (Tahoe) or newer."+[ "${MACOS%%.*}" -ge 15 ] || fail "macOS $MACOS: Kokon needs macOS 15 (Sequoia) or newer."ok "macOS $MACOS on $(sysctl -n machdep.cpu.brand_string), $(( $(sysctl -n hw.memsize) / 1073741824 )) GB unified memory"xcode-select -p >/dev/null 2>&1 || fail "Xcode Command Line Tools missing: run xcode-select --install"ok "Xcode Command Line Tools"diff --git a/src-tauri/tauri.macos.conf.json b/src-tauri/tauri.macos.conf.jsonindex 3874c84..ec41b06 100644--- a/src-tauri/tauri.macos.conf.json+++ b/src-tauri/tauri.macos.conf.json@@ -2,6 +2,6 @@"bundle": {"targets": ["app", "dmg"],"icon": ["icons/macos/32x32.png", "icons/macos/128x128.png", "icons/macos/[email protected]", "icons/macos/icon.icns"],- "macOS": { "minimumSystemVersion": "26.0", "signingIdentity": "-" }+ "macOS": { "minimumSystemVersion": "15.0", "signingIdentity": "-" }}}diff --git a/src/components/Setup.tsx b/src/components/Setup.tsxindex d30587c..37ddd9e 100644--- a/src/components/Setup.tsx+++ b/src/components/Setup.tsx@@ -19,7 +19,7 @@ function engineOptions(vendor: string | null): { value: GpuBackend; label: strinfunction engineNote(b: GpuBackend, nvidia: boolean): string {if (b === "cuda") return "NVIDIA's CUDA build: the fastest and tested path. Recommended.";- if (b === "metal") return "Beta. Runs on the Mac's GPU through Metal. Needs macOS 26 or newer.";+ if (b === "metal") return "Beta. Runs on the Mac's GPU through Metal. Needs macOS 15 or newer.";return nvidia? "The same model through Vulkan: works on NVIDIA, but slower than CUDA (no SageAttention) and the first image takes longer. Useful to try the AMD / Intel path; both engines can stay installed.": "Beta. AMD and Intel cards run the model through Vulkan, with the graphics driver you already have. Not yet tested on a real AMD or Intel card: please report how it goes.";