Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

15.5 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import test from "node:test";

import {
  defaultsFor,
  defaultsKeyFor,
  loadedRecipeFor,
  residentDefaultsKey,
  residentRecipeFor,
  resolutionFor,
} from "../src/features/images/image-generation-defaults.ts";

import { readSrc } from "./helpers/kit.ts";

test("distinguishes Klein base checkpoints from distilled checkpoints", () => {
  for (const size of ["4B", "9B"]) {
    assert.deepEqual(defaultsFor(`unsloth/FLUX.2-klein-base-${size}`), {
      steps: 20,
      guidance: 5,
    });
    assert.deepEqual(defaultsFor(`unsloth/FLUX.2-klein-${size}`), {
      steps: 4,
      guidance: 1,
    });
  }
});

test("keeps the existing family defaults and fallback", () => {
  assert.deepEqual(defaultsFor("krea/Krea-2-Raw"), {
    steps: 52,
    guidance: 3.5,
  });
  assert.deepEqual(defaultsFor("black-forest-labs/FLUX.1-dev"), {
    steps: 20,
    guidance: 3.5,
  });
  assert.deepEqual(defaultsFor("local/unknown-image-model"), {
    steps: 9,
    guidance: 0,
  });
});

test("an explicit family keys defaults only for an opaque path, never flattening a named variant", () => {
  const opaque = "/models/my-private-finetune";
  const schnell = "black-forest-labs/FLUX.1-schnell";
  const explicit = (value: string) => ({ value, source: "explicit" as const });
  for (const [key, want] of [
    [defaultsKeyFor(opaque, "qwen-image"), "qwen-image"],
    [defaultsKeyFor(opaque, "auto"), opaque],
    [defaultsKeyFor(schnell, "flux.1"), schnell],
    [defaultsKeyFor("Tongyi-MAI/Z-Image-Turbo", "z-image"), "Tongyi-MAI/Z-Image-Turbo"],
    [residentDefaultsKey(opaque, opaque, explicit("qwen-image")), "qwen-image"],
    [residentDefaultsKey(opaque, null, { value: "qwen-image", source: "auto" }), opaque],
    [residentDefaultsKey(schnell, schnell, explicit("flux.1")), schnell],
  ]) {
    assert.equal(key, want);
  }
  assert.deepEqual(defaultsFor("qwen-image"), { steps: 20, guidance: 4 });
  assert.deepEqual(defaultsFor(schnell), { steps: 4, guidance: 0 });
});

test("routed image picks apply and transactionally roll back model defaults", () => {
  const source = readSrc("features/images/images-page.tsx");
  const routeStart = source.indexOf(
    "const pick = diffusionRoutePick(",
    source.indexOf("const handledRouteModel"),
  );
  const routeEnd = source.indexOf(
    "// Reload the current model with the current advanced options.",
    routeStart,
  );
  assert.ok(routeStart >= 0 && routeEnd > routeStart);
  const routeBlock = source.slice(routeStart, routeEnd);
  assert.match(routeBlock, /imagePresets\.hydrated/);
  assert.match(routeBlock, /quantRevert\.current = revert/);
  assert.match(routeBlock, /applyImageModelDefaults\(\s*wanted,\s*"auto",/);
  assert.match(routeBlock, /!started[\s\S]*revertPick\(revert\)/);
});

test("routed video picks apply and transactionally roll back model defaults", () => {
  const source = readSrc("features/video/video-page.tsx");
  const routeStart = source.indexOf(
    "const pick = diffusionRoutePick(",
    source.indexOf("const handledRouteModel"),
  );
  const routeEnd = source.indexOf(
    "// The task dialog defers the load",
    routeStart,
  );
  assert.ok(routeStart >= 0 && routeEnd > routeStart);
  const routeBlock = source.slice(routeStart, routeEnd);
  assert.match(routeBlock, /videoPresets\.hydrated/);
  assert.match(routeBlock, /quantRevert\.current = revert/);
  assert.match(routeBlock, /applyVideoModelDefaults\(/);
  assert.match(routeBlock, /!started[\s\S]*revertPick\(revert\)/);
});

test("failed image and video picks release their recipe hydration claims", () => {
  for (const path of [
    "../src/features/images/images-page.tsx",
    "../src/features/video/video-page.tsx",
  ]) {
    const source = readFileSync(new URL(path, import.meta.url), "utf8");
    assert.match(source, /const claim = claim\w+Recipe\(\)/);
    assert.match(source, /commitRecipeClaim = claim\.commit/);
    assert.match(source, /releaseRecipeClaim = claim\.release/);
    assert.match(source, /quantRevert\.current\?\.commitRecipeClaim\?\.\(\)/);
    assert.match(source, /revertPick[\s\S]*r\.releaseRecipeClaim\?\.\(\)/);
  }

  const hook = readSrc(
    "features/generation-presets/use-media-generation-presets.ts",
  );
  assert.match(
    hook,
    /deferredSavedSettingsRef\.current = committed \? null : settings/,
  );
  assert.match(hook, /formClaim\.current = previousClaim/);
  assert.match(hook, /hydrateSavedSettings\(deferred\)/);
  assert.match(hook, /source === "claiming"\s*\? "claimed" : source/);
});

test("an auto-engaged Qwen-Image-2.1 quant keeps the 1024 canvas; a picked quant still shrinks it", () => {
  const repo = "Qwen/Qwen-Image-2.1";
  assert.deepEqual(
    resolutionFor(repo, { modelKind: "pipeline", transformerQuant: "int8", transformerQuantSource: "auto" }),
    { width: 1024, height: 1024 },
  );
  assert.deepEqual(
    resolutionFor(repo, { modelKind: "pipeline", transformerQuant: "fp8", transformerQuantSource: "auto" }),
    { width: 1024, height: 1024 },
  );
  assert.deepEqual(
    resolutionFor(repo, { modelKind: "pipeline", transformerQuant: "int8", transformerQuantSource: "explicit" }),
    { width: 512, height: 512 },
  );
  assert.deepEqual(
    resolutionFor(repo, { modelKind: "pipeline", transformerQuant: "int8" }),
    { width: 512, height: 512 },
  );
  assert.deepEqual(
    resolutionFor(repo, { modelKind: "gguf", transformerQuant: "int8", transformerQuantSource: "explicit" }),
    { width: 1024, height: 1024 },
  );
  assert.deepEqual(resolutionFor(repo, { modelKind: "pipeline", transformerQuant: null }), {
    width: 1024,
    height: 1024,
  });
});

test("every images-page canvas seed passes the quant provenance", () => {
  const source = readSrc("features/images/images-page.tsx");
  const calls = source.split("resolutionFor(").slice(1);
  assert.equal(calls.length, 3);
  for (const call of calls) {
    assert.match(call.slice(0, 400), /transformerQuantSource: status\??\.resolved\?\.transformer_quant\?\.source/);
  }
});

test("defaults follow ComfyUI's official templates for the same model", () => {
  for (const [id, want] of [
    ["black-forest-labs/FLUX.1-dev", { steps: 20, guidance: 3.5 }],
    ["black-forest-labs/FLUX.1-Krea-dev", { steps: 20, guidance: 3.5 }],
    ["black-forest-labs/FLUX.1-Kontext-dev", { steps: 20, guidance: 2.5 }],
    ["black-forest-labs/FLUX.2-dev", { steps: 20, guidance: 4 }],
    ["Qwen/Qwen-Image-Edit-2511", { steps: 40, guidance: 4 }],
    ["Qwen/Qwen-Image-Edit-2509", { steps: 20, guidance: 4 }],
    ["Qwen/Qwen-Image-2512", { steps: 50, guidance: 4 }],
    ["Qwen/Qwen-Image", { steps: 20, guidance: 4 }],
    ["Tongyi-MAI/Z-Image-Turbo", { steps: 8, guidance: 0 }],
    // diffusers Z-Image guidance g equals ComfyUI cfg g + 1.
    ["Tongyi-MAI/Z-Image", { steps: 25, guidance: 3 }],
    ["stabilityai/stable-diffusion-xl-base-1.0", { steps: 25, guidance: 7 }],
    ["stabilityai/sdxl-turbo", { steps: 1, guidance: 0 }],
    ["unsloth/sdxl-turbo", { steps: 1, guidance: 0 }],
    ["ideogram-ai/ideogram-4-fp8", { steps: 20, guidance: 7 }],
  ] as const) {
    assert.deepEqual(defaultsFor(id), want, id);
  }
});

test("every Qwen-Image-Layered spelling the backend accepts gets its 20 / 2.5 recipe", () => {
  for (const id of [
    "unsloth/Qwen-Image-Layered-GGUF",
    "local/qwen_image_layered",
    "local/qwenimagelayered-q4",
  ]) {
    assert.deepEqual(defaultsFor(id), { steps: 20, guidance: 2.5 }, id);
  }
});

test("every Qwen-Image-2.1 spelling gets Turbo's 8 / 1 recipe when it names Turbo, and the base keeps 25", () => {
  for (const id of [
    "Qwen/Qwen-Image-2.1-Turbo",
    "/models/qwen-image-21-turbo",
    "/models/qwen_image_21_turbo",
    "/models/qwen-image-21_turbo",
    "/models/qwenimage21-turbo",
    "/models/qwenimage21_turbo",
    "/models/qwenimage21turbo",
    "/models/qwenimage21turbo-Q4_K_M.gguf",
    "/models/qwen_image_2.1_turbo_Q4_K_M.gguf",
  ]) {
    assert.deepEqual(defaultsFor(id), { steps: 8, guidance: 1 }, id);
  }
  for (const id of ["Qwen/Qwen-Image-2.1", "/models/qwen_image_21", "/models/qwenimage21", "/models/qwen_image_2.1.gguf"]) {
    assert.deepEqual(defaultsFor(id), { steps: 25, guidance: 1 }, id);
  }
});

test("a community single file picked by path takes its family recipe once loaded (#11391)", () => {
  const pick = defaultsFor(defaultsKeyFor("/models/checkpoints/RealVisXL_V4.0.safetensors", null));
  const resident = residentDefaultsKey(
    "/models/checkpoints",
    "stabilityai/stable-diffusion-xl-base-1.0",
    { value: "sdxl", source: "auto" },
  );
  assert.deepEqual(loadedRecipeFor(pick, resident), { steps: 25, guidance: 7 });
  // A pick whose name already chose a recipe keeps it (Schnell is not re-seeded as dev).
  assert.equal(
    loadedRecipeFor(defaultsFor("black-forest-labs/FLUX.1-schnell"), "black-forest-labs/FLUX.1-dev"),
    null,
  );
  // An unrecognised resident leaves the form alone.
  assert.equal(loadedRecipeFor(pick, "/models/unknown"), null);
  assert.equal(loadedRecipeFor(null, resident), null);
  // The backend's header-read recipe wins: a renamed FLUX.1-dev keeps 20 steps, not its schnell base's 4.
  const schnellBase = residentDefaultsKey("/models/my_flux.safetensors", "black-forest-labs/FLUX.1-schnell", null);
  assert.deepEqual(loadedRecipeFor(pick, schnellBase, { steps: 20, guidance: 3.5 }), { steps: 20, guidance: 3.5 });
  assert.equal(loadedRecipeFor(pick, schnellBase, { steps: 9, guidance: 0 }), null);
});

test("the Images page applies the loaded family recipe only to an untouched fallback form", () => {
  const src = readSrc("features/images/images-page.tsx");
  const ready = src.slice(src.indexOf('if (p.phase === "ready")'), src.indexOf('if (p.phase === "error")'));
  assert.match(ready, /loadedRecipeFor\(\s*pickDefaults\.current/);
  assert.match(ready, /!pickRecipeSuperseded\.current\?\.\(\)/);
  assert.match(ready, /cur === DEFAULT_GEN\.steps \? loadedRecipe\.steps : cur/);
});

test("the resident recipe prefers the backend-reported one", () => {
  const schnellBase = residentDefaultsKey("/models/my_flux.safetensors", "black-forest-labs/FLUX.1-schnell", null);
  assert.deepEqual(residentRecipeFor(schnellBase, { steps: 20, guidance: 3.5 }), { steps: 20, guidance: 3.5 });
  // An older backend (or the native engine) reports nothing: the base-repo key decides, as before.
  assert.deepEqual(residentRecipeFor(schnellBase, null), defaultsFor("black-forest-labs/FLUX.1-schnell"));
  assert.deepEqual(residentRecipeFor(schnellBase, {}), defaultsFor("black-forest-labs/FLUX.1-schnell"));
});

test("the Images page seeds Default from the resident recipe and drops the pick token on revert", () => {
  const src = readSrc("features/images/images-page.tsx");
  assert.match(src, /residentRecipeFor\(\s*residentDefaults,\s*status\?\.generation_defaults/);
  assert.doesNotMatch(src, /defaultsFor\(residentDefaults\)/);
  const revert = src.slice(src.indexOf("const revertPick = useCallback"), src.indexOf("}, []);", src.indexOf("const revertPick = useCallback")));
  assert.match(revert, /pickDefaults\.current = null/);
});

test("every FLUX.3 Klein alias the backend registers gets its family recipe", () => {
  for (const id of [
    "black-forest-labs/flux-3-image-klein-base",
    "someone/flux3-image-klein-base-finetune",
    "someone/flux3_image_klein_base",
    "someone/flux3-klein-base-merge",
    "flux.3-klein-base",
  ]) {
    assert.deepEqual(defaultsFor(id), { steps: 50, guidance: 3.5 }, id);
  }
  for (const id of [
    "black-forest-labs/flux-3-image-klein",
    "someone/flux3-image-klein-finetune",
    "someone/flux3_image_klein",
    "someone/flux3-klein-lora-merge",
    "flux.3-klein",
  ]) {
    assert.deepEqual(defaultsFor(id), { steps: 16, guidance: 1 }, id);
  }
});

test("an opaque FLUX.3 path keys its defaults by the explicit family", () => {
  for (const [family, want] of [
    ["flux.3-klein", { steps: 16, guidance: 1 }],
    ["flux.3-klein-base", { steps: 50, guidance: 3.5 }],
  ] as const) {
    const key = defaultsKeyFor("/models/my-model", family);
    assert.equal(key, family);
    assert.deepEqual(defaultsFor(key), want);
  }
});

test("an explicit FLUX.3 family decides the recipe over a name that reads as the other variant", () => {
  // BFL's ComfyUI base file has no "base" in its name; the backend checks it against the family.
  const comfyBase = "black-forest-labs/flux-3-image-klein-comfy";
  assert.equal(defaultsKeyFor(comfyBase, "flux.3-klein-base"), "flux.3-klein-base");
  assert.deepEqual(defaultsFor(defaultsKeyFor(comfyBase, "flux.3-klein-base")), { steps: 50, guidance: 3.5 });
  assert.deepEqual(defaultsFor(defaultsKeyFor(comfyBase, "flux.3-klein")), { steps: 16, guidance: 1 });
  assert.deepEqual(defaultsFor(defaultsKeyFor(comfyBase, "auto")), { steps: 16, guidance: 1 });
  assert.equal(
    residentDefaultsKey("/models/flux3_image_klein_bf16.safetensors", "black-forest-labs/flux-3-image-klein", {
      value: "flux.3-klein-base",
      source: "explicit",
    }),
    "flux.3-klein-base",
  );
});

test("MOSS-Image SFT and Base get the reference workflow's 25 / 2.5 recipe", () => {
  for (const id of [
    "OpenMOSS-Team/MOSS-Image-SFT",
    "OpenMOSS-Team/MOSS-Image-Base",
    "someone/moss_image_sft_merge",
    "moss-image",
  ]) {
    assert.deepEqual(defaultsFor(id), { steps: 25, guidance: 2.5 }, id);
  }
  const key = defaultsKeyFor("/models/my-model", "moss-image");
  assert.equal(key, "moss-image");
  assert.deepEqual(defaultsFor(key), { steps: 25, guidance: 2.5 });
});

test("a GGUF filename naming Krea 2 Raw outranks its multi-checkpoint repo", () => {
  const repo = "realrebelai/KREA-2_GGUFs";
  const raw = { steps: 52, guidance: 3.5 };
  const turbo = { steps: 8, guidance: 0 };
  assert.deepEqual(defaultsFor(defaultsKeyFor(repo, "auto", "BASE/Krea-2-Base-Q4_K_M.gguf")), raw);
  assert.deepEqual(defaultsFor(defaultsKeyFor(repo, "auto", "TURBO/Krea-2-Turbo-Q4_K_M.gguf")), turbo);
  assert.deepEqual(defaultsFor(defaultsKeyFor("vantagewithai/Krea-2-Raw-GGUF", "auto", "krea2_raw-Q4_K_M.gguf")), raw);
  // No filename (or one naming nothing) keeps the repo key.
  assert.deepEqual(defaultsFor(defaultsKeyFor(repo, "auto")), turbo);
  assert.deepEqual(defaultsFor(defaultsKeyFor("krea/Krea-2-Raw", "auto", "model-Q4_K_M.gguf")), raw);
  // The resident recipe reads the loaded GGUF the same way.
  assert.deepEqual(
    residentRecipeFor(residentDefaultsKey(repo, "krea/Krea-2-Turbo", null, "BASE/Krea-2-Base-Q4_K_M.gguf")),
    raw,
  );
});

test("every GGUF or single-file pick path keys its defaults on the selected filename", () => {
  const src = readSrc("features/images/images-page.tsx");
  assert.match(src, /applyImageModelDefaults\(repoId, effectiveFamilyOverride, false, filename\)/);
  assert.match(src, /applyImageModelDefaults\(id, nextFamilyOverride, false, meta\.ggufFilename\)/);
  assert.match(src, /applyImageModelDefaults\(id, nextFamilyOverride, false, filename\)/);
  assert.match(src, /"auto",\s*false,\s*pick\.opts\.kind === "pipeline" \? null : \(pick\.opts\.filename \?\? null\)/);
  assert.match(src, /defaultsKeyFor\(repoId, effectiveFamilyOverride, ggufFilename\)/);
  assert.match(src, /status\?\.resolved\?\.family_override,\s*status\?\.gguf_filename/);
  assert.match(src, /loaded\.resolved\?\.family_override,\s*loaded\.gguf_filename/);
});

test("a Hub-routed single-file checkpoint keys its recipe on the selected file", () => {
  const key = defaultsKeyFor("acme/sdxl-checkpoints", "auto", "sdxl-turbo.safetensors");
  assert.deepEqual(
    { steps: defaultsFor(key).steps, guidance: defaultsFor(key).guidance },
    { steps: 1, guidance: 0 },
  );
});