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.

feat(mac): macOS 15 Sequoia support with Kokon's own Metal engine build (#24)

Gabriele Lozupone14ade1eb7d8e
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 602bbb0..49e179d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -23,7 +23,7 @@ npx tauri dev # run the desktop app in development
powershell -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+.
```bash
bash scripts/dev/mac-dev.sh --check # check the prerequisites
diff --git a/README.md b/README.md
index 5fea5b0..663feb3 100644
--- a/README.md
+++ b/README.md
@@ -611,7 +611,7 @@ npx tauri dev # run the desktop app in development
powershell -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+.
```bash
bash scripts/dev/mac-dev.sh --check # check the prerequisites
diff --git a/crates/qls-core/src/catalog.rs b/crates/qls-core/src/catalog.rs
index 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.rs
index 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.md
index 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 engine
is a pinned download in `catalog.rs`, so both Windows engines can stay installed.
diff --git a/docs/linux.md b/docs/linux.md
index 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 engin
3. 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 app
diff --git a/engine.json b/engine.json
index 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.sh
index 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 pipefail
cd "$(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.json
index 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.tsx
index 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: strin
function 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.";