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.

Unsloth Studio / Desktop: the Images page Compare grid, for API callers (server-rendered X/Y grid, no UI change) (#15169)

Leo Borcherding5f1d55556fd8
diff --git a/studio/backend/core/inference/diffusion_xy.py b/studio/backend/core/inference/diffusion_xy.py
new file mode 100644
index 00000000000..b6791249a79
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_xy.py
@@ -0,0 +1,242 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""X/Y grid over /images/generate (AUTOMATIC1111's X/Y plot): cell requests and the labelled grid image."""
+
+from __future__ import annotations
+
+import math
+import random
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from pydantic import ValidationError
+
+MAX_GRID_PIXELS = 32 * 1024 * 1024
+
+_LABELS = {
+ "seed": "Seed",
+ "steps": "Steps",
+ "guidance": "CFG",
+ "shift": "Shift",
+ "base_shift": "Base shift",
+ "max_shift": "Max shift",
+ "strength": "Denoise",
+ "clip_skip": "Clip skip",
+ "cfg_rescale": "CFG rescale",
+ "variation_seed": "Var. seed",
+ "variation_strength": "Var. strength",
+ "lora_weight": "LoRA weight",
+}
+
+
+@dataclass
+class XYCell:
+ ix: int
+ iy: int
+ label: str
+ request: Any # DiffusionGenerateRequest
+
+
+@dataclass
+class XYPlan:
+ cells: list[XYCell] # row by row: index ix + iy * nx
+ nx: int
+ ny: int
+ x_labels: list[str]
+ y_labels: list[str]
+ order: list[int]
+
+ def describe(self, axes: list[Any]) -> dict[str, Any]:
+ out: dict[str, Any] = {}
+ for name, axis, labels in zip(("x", "y"), axes, (self.x_labels, self.y_labels)):
+ if axis is not None:
+ out[name] = {
+ "field": axis.field,
+ "index": axis.index,
+ "values": list(axis.values),
+ "labels": labels,
+ }
+ return out
+
+
+def _number(value: Any) -> str:
+ return f"{value:g}" if isinstance(value, float) else str(value)
+
+
+def axis_label(axis: Any, value: Any) -> str:
+ from core.inference.diffusion_sampler import sampler_label, schedule_label
+
+ if axis.field == "prompt_sr":
+ return str(value)
+ if axis.field == "sampler":
+ return sampler_label(str(value)) or ("Default" if value == "default" else str(value))
+ if axis.field == "schedule_type":
+ return schedule_label(str(value)) or ("Automatic" if value == "automatic" else str(value))
+ return f"{_LABELS[axis.field]}: {_number(value)}"
+
+
+def _apply(data: dict[str, Any], axis: Any, value: Any) -> None:
+ if axis.field == "prompt_sr":
+ search = axis.values[0]
+ prompt = data.get("prompt") or ""
+ negative = data.get("negative_prompt")
+ if search not in prompt and search not in (negative or ""):
+ raise ValueError(
+ f'xy prompt_sr: "{search}" is not in the prompt or the negative prompt'
+ )
+ data["prompt"] = prompt.replace(search, str(value))
+ if negative is not None:
+ data["negative_prompt"] = negative.replace(search, str(value))
+ elif axis.field == "lora_weight":
+ data["loras"] = [dict(l) for l in data["loras"]]
+ data["loras"][axis.index]["weight"] = value
+ else:
+ data[axis.field] = value
+
+
+def expand(request: Any, rng: Optional[random.Random] = None) -> XYPlan:
+ """Cell requests for ``request.xy``, validated as full generate requests. Raises ValueError naming the cell."""
+ from models.inference import DiffusionGenerateRequest
+
+ spec = request.xy
+ axes = [spec.x, spec.y]
+ # Unset fields stay unset per cell, so omitted steps / guidance still follow the loaded model.
+ base = request.model_dump(exclude_unset = True, exclude = {"xy"})
+ if request.loras:
+ # Nested defaults (weight 1.0) are unset too, and the weight is what the cells change.
+ base["loras"] = [l.model_dump() for l in request.loras]
+ if (
+ spec.x.field != "seed"
+ and (spec.y is None or spec.y.field != "seed")
+ and base.get("seed") is None
+ ):
+ # One seed for every cell, so only the swept setting differs (A1111 fix_seed).
+ base["seed"] = (rng or random).randrange(2**32)
+ fields = {spec.x.field, spec.y.field if spec.y else None}
+ if (
+ "variation_seed" not in fields
+ and base.get("variation_seed") is None
+ and ("variation_strength" in fields or base.get("variation_strength"))
+ ):
+ # Unset, the engine draws a variation seed per generation, so each cell would get other noise.
+ base["variation_seed"] = (rng or random).randrange(2**32)
+ # A rewrite per cell would change the thing being compared.
+ base.setdefault("enhance_prompt", False)
+ x_values = list(spec.x.values)
+ y_values = list(spec.y.values) if spec.y else [None]
+ x_labels = [axis_label(spec.x, v) for v in x_values]
+ y_labels = [axis_label(spec.y, v) for v in y_values] if spec.y else [""]
+ cells: list[XYCell] = []
+ for iy, y_value in enumerate(y_values):
+ for ix, x_value in enumerate(x_values):
+ label = ", ".join(l for l in (x_labels[ix], y_labels[iy]) if l)
+ data = dict(base)
+ _apply(data, spec.x, x_value)
+ if spec.y is not None:
+ _apply(data, spec.y, y_value)
+ try:
+ cell = DiffusionGenerateRequest.model_validate(data)
+ except ValidationError as exc:
+ err = exc.errors()[0]
+ where = ".".join(str(p) for p in err.get("loc", ())) or "request"
+ raise ValueError(f"xy cell ({label}): {where}: {err.get('msg')}") from None
+ if cell.loras:
+ # Weight 0 drops the adapter, as the Images page sends it; read after validation parsed "0".
+ active = [l for l in cell.loras if l.weight != 0]
+ if len(active) != len(cell.loras):
+ cell = cell.model_copy(update = {"loras": active or None})
+ cells.append(XYCell(ix, iy, label, cell))
+ # Adapter-free cells last: Speed Auto may compile on an adapter-free run, and a compiled load refuses LoRA after.
+ order = sorted(range(len(cells)), key = lambda i: not cells[i].request.loras)
+ return XYPlan(cells, len(x_values), len(y_values), x_labels, y_labels, order)
+
+
+def _font(size: int):
+ from PIL import ImageFont
+ try:
+ return ImageFont.load_default(size = size)
+ except (TypeError, OSError): # Pillow without FreeType: the fixed bitmap font
+ return ImageFont.load_default()
+
+
+def fit_cell(image: Any, plan: XYPlan) -> Any:
+ """``image`` scaled to its share of MAX_GRID_PIXELS, so a 64-cell grid holds no full-size renders meanwhile."""
+ budget = MAX_GRID_PIXELS / (plan.nx * plan.ny)
+ if image.width * image.height <= budget:
+ return image
+ from PIL import Image
+
+ scale = math.sqrt(budget / (image.width * image.height))
+ small = image.copy()
+ small.thumbnail(
+ (max(1, int(image.width * scale)), max(1, int(image.height * scale))), Image.LANCZOS
+ )
+ return small
+
+
+_MAX_LABEL_LINES = 3
+
+
+def _wrap(text: str, width: float, font) -> list[str]:
+ lines: list[str] = []
+ line = ""
+ for word in text.split():
+ nxt = f"{line} {word}" if line else word
+ if line and font.getlength(nxt) > width:
+ lines.append(line)
+ line = word
+ else:
+ line = nxt
+ if line:
+ lines.append(line)
+ if len(lines) > _MAX_LABEL_LINES:
+ lines = lines[:_MAX_LABEL_LINES]
+ lines[-1] += " ..."
+ return lines
+
+
+def compose_grid(images: list[Any], plan: XYPlan):
+ """The labelled grid, laid out after A1111's draw_grid_annotations: column labels above, row labels in a left
+ band 3/4 of a cell wide, font size (w + h) / 25. Cells are scaled down to keep the grid under MAX_GRID_PIXELS."""
+ from PIL import Image, ImageDraw
+
+ full_w = max(im.width for im in images)
+ full_h = max(im.height for im in images)
+ has_rows = any(plan.y_labels)
+ scale = min(1.0, math.sqrt(MAX_GRID_PIXELS / (plan.nx * plan.ny * full_w * full_h)))
+ for _ in range(4):
+ cw, ch = max(1, int(full_w * scale)), max(1, int(full_h * scale))
+ font_size = max(12, (cw + ch) // 25)
+ font = _font(font_size)
+ line_h = int(font_size * 1.25)
+ left = cw * 3 // 4 if has_rows else 0
+ col_lines = [_wrap(t, cw - font_size, font) for t in plan.x_labels]
+ row_lines = [_wrap(t, left - font_size, font) for t in plan.y_labels] if has_rows else []
+ top = max(len(l) for l in col_lines) * line_h + font_size if any(col_lines) else 0
+ total = (left + plan.nx * cw) * (top + plan.ny * ch)
+ if total <= MAX_GRID_PIXELS:
+ break
+ scale *= math.sqrt(MAX_GRID_PIXELS / total)
+ grid = Image.new("RGB", (left + plan.nx * cw, top + plan.ny * ch), "white")
+ draw = ImageDraw.Draw(grid)
+
+ def _text(lines: list[str], cx: float, y: float) -> None:
+ for k, line in enumerate(lines):
+ draw.text(
+ (cx - font.getlength(line) / 2, y + k * line_h), line, fill = "black", font = font
+ )
+
+ for ix, lines in enumerate(col_lines):
+ _text(lines, left + ix * cw + cw / 2, font_size / 2)
+ for iy, lines in enumerate(row_lines):
+ _text(lines, left / 2, top + iy * ch + (ch - len(lines) * line_h) / 2)
+ for index, image in enumerate(images):
+ cell = plan.cells[index]
+ if image.size != (cw, ch):
+ image = image.copy()
+ image.thumbnail((cw, ch), Image.LANCZOS)
+ x = left + cell.ix * cw + (cw - image.width) // 2
+ y = top + cell.iy * ch + (ch - image.height) // 2
+ grid.paste(image.convert("RGB"), (x, y))
+ return grid
diff --git a/studio/backend/core/inference/image_gallery.py b/studio/backend/core/inference/image_gallery.py
index 39acf31cab8..16b68b7c81d 100644
--- a/studio/backend/core/inference/image_gallery.py
+++ b/studio/backend/core/inference/image_gallery.py
@@ -49,6 +49,10 @@ def _params_text(meta: dict[str, Any]) -> str:
"""Automatic1111-style ``parameters`` string for cross-tool interop."""
from core.inference.diffusion_hires import infotext_fields as hires_infotext, infotext_meta
+ grid = meta.get("xy_grid") or {}
+ if grid.get("cell_width") and grid.get("cell_height"):
+ # An X/Y grid's recipe is its first cell's: A1111 writes the cell size, not the grid's pixels.
+ meta = {**meta, "width": grid["cell_width"], "height": grid["cell_height"]}
# A Hires fix image is written the way A1111 writes one: Size is the base pass, Hires upscale the factor.
meta = infotext_meta(meta)
# The caption the model encoded (FLUX.3 prompt upsampler): other tools reproduce the image from this line. The
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index df862be7710..47c71e74183 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -17,6 +17,8 @@ from pydantic import (
Discriminator,
Field,
PrivateAttr,
+ StrictFloat,
+ StrictInt,
Tag,
field_validator,
model_serializer,
@@ -5134,6 +5136,78 @@ class LocalizedEditSpec(BaseModel):
# All images of one request, base64: ten maximal uploads would otherwise buffer ~320 MiB.
_MAX_CONDITION_PAYLOAD = 128 * 1024 * 1024
+MAX_XY_CELLS = 64
+
+XYAxisField = Literal[
+ "seed",
+ "steps",
+ "guidance",
+ "sampler",
+ "schedule_type",
+ "shift",
+ "base_shift",
+ "max_shift",
+ "strength",
+ "clip_skip",
+ "cfg_rescale",
+ "variation_seed",
+ "variation_strength",
+ "lora_weight",
+ "prompt_sr",
+]
+
+
+class XYAxisSpec(BaseModel):
+ """One axis of an X/Y grid: a request field and the values its cells take."""
+
+ field: XYAxisField = Field(
+ ...,
+ description = "Request field the axis varies. lora_weight sets the weight of loras[index]; "
+ "prompt_sr (AUTOMATIC1111 Prompt S/R) replaces the first value in the prompt and negative "
+ "prompt with each value in turn, so the first cell keeps the prompt as typed.",
+ )
+ values: list[Union[StrictInt, StrictFloat, str]] = Field(
+ ...,
+ min_length = 1,
+ max_length = MAX_XY_CELLS,
+ description = "Values, one column (X) or row (Y) each",
+ )
+ index: Optional[int] = Field(
+ None, ge = 0, le = 7, description = "lora_weight only: which `loras` entry the axis weights"
+ )
+
+ @model_validator(mode = "after")
+ def _index_only_for_lora(self) -> "XYAxisSpec":
+ if (self.field == "lora_weight") != (self.index is not None):
+ raise ValueError("`index` is required for a lora_weight axis and only allowed there")
+ if self.field == "prompt_sr" and not all(isinstance(v, str) for v in self.values):
+ raise ValueError("prompt_sr values must be strings")
+ if self.field == "prompt_sr" and not self.values[0]:
+ raise ValueError(
+ "prompt_sr: the first value is the text searched for and cannot be empty"
+ )
+ return self
+
+
+class XYGridSpec(BaseModel):
+ """X/Y grid: every combination of the axes' values renders as its own gallery image, plus one
+ labelled grid image (X values across the top, Y values down the left)."""
+
+ x: XYAxisSpec = Field(..., description = "Column axis")
+ y: Optional[XYAxisSpec] = Field(None, description = "Row axis; omitted = a single row")
+
+ @model_validator(mode = "after")
+ def _bounded(self) -> "XYGridSpec":
+ cells = len(self.x.values) * (len(self.y.values) if self.y else 1)
+ if cells > MAX_XY_CELLS:
+ raise ValueError(
+ f"{cells} grid cells is over the limit of {MAX_XY_CELLS}; use fewer values"
+ )
+ y = self.y
+ if y and y.field == self.x.field and y.field != "prompt_sr" and y.index == self.x.index:
+ raise ValueError(f"x and y both vary {y.field}")
+ return self
+
class DiffusionDetailerSpec(BaseModel):
"""Detailer (face fix) post-pass, after ADetailer and ComfyUI-Impact-Pack's FaceDetailer: SAM 3 finds the targets,
@@ -5486,6 +5560,12 @@ class DiffusionGenerateRequest(BaseModel):
model: Optional[str] = Field(
None, description = "Model name on the connection named by `provider_id`."
)
+ xy: Optional[XYGridSpec] = Field(
+ None,
+ description = "X/Y grid: render one image per combination of the axes' values, each saved to "
+ "the gallery with its own recipe, plus one labelled grid image (returned as `grid`). Every "
+ "cell runs at batch size 1 on the same seed unless seed is an axis. Local models only.",
+ )
@field_validator("loras")
@classmethod
@@ -5530,6 +5610,21 @@ class DiffusionGenerateRequest(BaseModel):
raise ValueError("must be a multiple of 16")
return value
+ @model_validator(mode = "after")
+ def _xy_single_image_cells(self) -> "DiffusionGenerateRequest":
+ if self.xy is None:
+ return self
+ if self.batch_size != 1 or self.prompts is not None or self.seeds is not None:
+ raise ValueError(
+ "xy runs every cell at batch size 1: drop batch_size, prompts and seeds"
+ )
+ if self.provider_id:
+ raise ValueError("xy runs on the loaded local model, not a connection")
+ for axis in (self.xy.x, self.xy.y):
+ if axis and axis.field == "lora_weight" and axis.index >= len(self.loras or []):
+ raise ValueError(f"lora_weight axis index {axis.index} has no entry in loras")
+ return self
+
@model_validator(mode = "after")
def _batch_seeds_json_safe(self) -> "DiffusionGenerateRequest":
# A batch derives seeds as seed..seed+batch_size-1, so a derived top-of-batch seed can exceed the 2**53-1 JSON-safe cap.
@@ -5739,6 +5834,11 @@ class GalleryImage(BaseModel):
inpaint_padding: Optional[int] = Field(
None, description = "Padding (px) around the mask for an only-masked inpaint"
)
+ xy_grid: Optional[dict[str, Any]] = Field(
+ None,
+ description = "Set on an X/Y grid image: its axes ({field, index, values, labels}) and the "
+ "cell image ids row by row. Its other recipe fields are the first cell's, as in AUTOMATIC1111.",
+ )
detailer: Optional[Dict[str, Any]] = Field(
None,
description = "The Detailer pass this image ran: its settings, each detection (target, score, box, crop, "
@@ -5786,6 +5886,11 @@ class DiffusionGenerateResponse(BaseModel):
"""The persisted gallery records for one generation call (a batch)."""
images: list[GalleryImage] = Field(..., description = "Saved records, one per image in the batch")
+ grid: Optional[GalleryImage] = Field(
+ None,
+ description = "xy only: the labelled grid image, also saved to the gallery; `images` holds "
+ "the cells row by row",
+ )
class GalleryListResponse(BaseModel):
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 9aedfcd63d0..8c5d529438a 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -49512,9 +49512,115 @@ async def generate_diffusion_image(
):
if request.provider_id:
return await _external_image_generation(request, http_request)
+ if request.xy is not None:
+ return await _generate_xy_grid(request)
return await _generate_diffusion_image_core(request)
+# Running grids by account: a Stop between cells or before a queued cell finds no denoise to land on.
+_xy_grid_stops: list[tuple[Optional[str], Any]] = []
+
+
+def _stop_xy_grids() -> bool:
+ account = current_account_id()
+ tickets = [ticket for owner, ticket in _xy_grid_stops if owner == account]
+ for ticket in tickets:
+ ticket.stop()
+ return bool(tickets)
+
+
+def _loaded_diffusion_layer_count() -> int:
+ from core.inference.diffusion_engine_router import get_active_diffusion_engine
+ from core.inference.diffusion_families import detect_family
+
+ try:
+ name = get_active_diffusion_engine().status().get("family")
+ except Exception: # noqa: BLE001 -- nothing loaded: the cell run answers that
+ return 0
+ family = detect_family("", name) if name else None
+ return int(getattr(family, "layer_count", 0) or 0)
+
+
+async def _generate_xy_grid(request: DiffusionGenerateRequest) -> DiffusionGenerateResponse:
+ """Render every X/Y cell as its own gallery image, then save the labelled grid. A Stop or a failing cell ends the
+ grid with that cell's error; the cells before it stay in the gallery."""
+ from core.inference import diffusion_xy, image_gallery
+ from core.inference.diffusion_families import DIFFUSION_CANCELLED_MSG
+ from core.inference.diffusion_segment import render_fence
+ from core.inference.generation_ticket import GenerationTicket, generation_ticket
+
+ try:
+ plan = diffusion_xy.expand(request)
+ except ValueError as exc:
+ raise HTTPException(status_code = 400, detail = str(exc))
+ layers = _loaded_diffusion_layer_count()
+ if layers:
+ raise HTTPException(
+ status_code = 400,
+ detail = f"xy needs one image per cell; the loaded model returns {layers} layers per image",
+ )
+ records: list[Optional[GalleryImage]] = [None] * len(plan.cells)
+ pictures: list[Any] = [None] * len(plan.cells)
+ global _diffusion_persist_active
+ # Progress stays active between cells and through the grid save, so a reload does not settle the run early.
+ ticket = GenerationTicket()
+ stop = (current_account_id(), ticket)
+ _diffusion_persist_active += 1
+ try:
+ _xy_grid_stops.append(stop)
+ with render_fence():
+ for index in plan.order:
+ if ticket.cancelled():
+ raise HTTPException(status_code = 409, detail = DIFFUSION_CANCELLED_MSG)
+ captured: list[Any] = []
+ # The engine binds each cell's cancel to the ticket before it waits for the slot.
+ with generation_ticket(ticket):
+ result = await _generate_diffusion_image_run(
+ plan.cells[index].request, captured = captured
+ )
+ records[index] = result.images[0]
+ pictures[index] = diffusion_xy.fit_cell(captured[0], plan)
+ # No await between these two: a Stop after the last cell ends the grid, one after this is not acknowledged.
+ _xy_grid_stops.remove(stop)
+ if ticket.cancelled():
+ raise HTTPException(status_code = 409, detail = DIFFUSION_CANCELLED_MSG)
+ first = records[0]
+
+ def _save_grid() -> dict:
+ grid = diffusion_xy.compose_grid(pictures, plan)
+ meta = first.model_dump(
+ exclude = {"id", "url", "pinned", "archived", "order_at", "schema_version"}
+ )
+ meta.update(
+ width = grid.width,
+ height = grid.height,
+ batch_index = 0,
+ batch_size = 1,
+ xy_grid = {
+ **plan.describe([request.xy.x, request.xy.y]),
+ "cells": [r.id for r in records],
+ "cell_width": first.width,
+ "cell_height": first.height,
+ },
+ created_at = time.time(),
+ )
+ return image_gallery.save(grid, meta)
+
+ try:
+ grid_record = await asyncio.to_thread(_save_grid)
+ except Exception as exc:
+ logger.error("diffusion.xy_grid_failed: %s", exc, exc_info = True)
+ raise HTTPException(
+ status_code = 500,
+ detail = "The grid cells are in the gallery, but the grid image could not be saved.",
+ )
+ finally:
+ if stop in _xy_grid_stops:
+ _xy_grid_stops.remove(stop)
+ _diffusion_persist_active -= 1
+ return DiffusionGenerateResponse(images = records, grid = GalleryImage(**grid_record))
+
+
async def _generate_diffusion_image_core(
request: DiffusionGenerateRequest,
) -> DiffusionGenerateResponse:
@@ -49528,7 +49634,7 @@ async def _generate_diffusion_image_core(
async def _generate_diffusion_image_run(
- request: DiffusionGenerateRequest,
+ request: DiffusionGenerateRequest, captured: Optional[list] = None
) -> DiffusionGenerateResponse:
from core.inference import image_gallery
from core.inference.diffusion_engine_router import get_active_diffusion_engine
@@ -49713,6 +49819,9 @@ async def _generate_diffusion_image_run(
raise
generation_seconds = time.perf_counter() - generation_started
+ # After the Detailer, so an X/Y cell is the picture the gallery keeps.
+ if captured is not None:
+ captured.extend(result["images"])
# Persist each image with its full recipe. BOTH engines batch with a distinct seed per image, returned in ``seeds``, so each is individually reproducible.
created_at = time.time()
per_image_seeds = result.get("seeds")
@@ -50867,13 +50976,14 @@ async def cancel_diffusion_generation(
saved image connection instead."""
if target == "connection":
return {"cancelled": _stop_external_image_runs()}
+ grids = _stop_xy_grids()
if account_access.generation_is_foreign("diffusion"):
- return {"cancelled": False}
+ return {"cancelled": grids}
mine = account_access.generation_is_mine("diffusion")
if not mine and (
account_access.foreign_work_active() or account_access.resident_hidden("diffusion")
):
- return {"cancelled": False}
+ return {"cancelled": grids}
from core.inference.diffusion_engine_router import get_active_diffusion_engine
if (
@@ -50883,7 +50993,7 @@ async def cancel_diffusion_generation(
"diffusion", get_active_diffusion_engine().status().get("repo_id")
)
):
- return {"cancelled": False}
+ return {"cancelled": grids}
# A run still upsampling its prompt has not reached the engine yet.
from core.inference.flux3_prompt_upsampler import cancel_active as cancel_upsampling
@@ -50899,7 +51009,7 @@ async def cancel_diffusion_generation(
if expected is not None:
cancel = functools.partial(cancel, expected_account = expected)
cancelled = await asyncio.get_running_loop().run_in_executor(_CANCEL_EXECUTOR, cancel)
- return {"cancelled": bool(cancelled or upsampling or detailing)}
+ return {"cancelled": bool(cancelled or upsampling or detailing or grids)}
# ── FLUX.3 prompt upsampler (llama.cpp sidecar) ──────────────────────────────────────────────────────────
diff --git a/studio/backend/tests/test_diffusion_xy.py b/studio/backend/tests/test_diffusion_xy.py
new file mode 100644
index 00000000000..24bf3ecc52d
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_xy.py
@@ -0,0 +1,472 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""X/Y grid on /images/generate, renderer faked."""
+
+from __future__ import annotations
+
+import random
+import sys
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from core.inference import diffusion_xy
+from models.inference import MAX_XY_CELLS, DiffusionGenerateRequest
+
+_TESTS_DIR = str(Path(__file__).resolve().parent)
+if _TESTS_DIR not in sys.path:
+ sys.path.insert(0, _TESTS_DIR)
+
+from test_diffusion_routes import client # noqa: E402,F401 (fixture)
+
+
+def _req(**body) -> DiffusionGenerateRequest:
+ return DiffusionGenerateRequest.model_validate({"prompt": "a red sloth", **body})
+
+
+def test_expand_is_row_major_with_one_shared_seed():
+ plan = diffusion_xy.expand(
+ _req(
+ xy = {
+ "x": {"field": "steps", "values": [4, 8, 12]},
+ "y": {"field": "guidance", "values": [0, 1.5]},
+ }
+ ),
+ rng = random.Random(0),
+ )
+ assert (plan.nx, plan.ny) == (3, 2)
+ assert [(c.request.steps, c.request.guidance) for c in plan.cells] == [
+ (4, 0.0),
+ (8, 0.0),
+ (12, 0.0),
+ (4, 1.5),
+ (8, 1.5),
+ (12, 1.5),
+ ]
+ assert len({c.request.seed for c in plan.cells}) == 1
+ assert all(c.request.xy is None and c.request.enhance_prompt is False for c in plan.cells)
+ assert plan.x_labels == ["Steps: 4", "Steps: 8", "Steps: 12"]
+ assert plan.y_labels == ["CFG: 0", "CFG: 1.5"]
+
+
+def test_expand_keeps_unswept_fields_unset_so_model_defaults_still_apply():
+ plan = diffusion_xy.expand(_req(xy = {"x": {"field": "steps", "values": [4, 8]}}))
+ fields = plan.cells[0].request.model_fields_set
+ assert "steps" in fields and "guidance" not in fields and "width" not in fields
+ assert plan.y_labels == [""]
+
+
+def test_seed_axis_sets_each_cell_seed():
+ plan = diffusion_xy.expand(_req(seed = 1, xy = {"x": {"field": "seed", "values": [7, 8]}}))
+ assert [c.request.seed for c in plan.cells] == [7, 8]
+
+
+def test_sampler_axis_uses_display_labels():
+ plan = diffusion_xy.expand(
+ _req(xy = {"x": {"field": "sampler", "values": ["default", "euler", "dpmpp_2m"]}})
+ )
+ assert [c.request.sampler for c in plan.cells] == ["default", "euler", "dpmpp_2m"]
+ assert plan.x_labels[0] == "Default" and plan.x_labels[1] == "Euler"
+
+
+def test_prompt_sr_replaces_the_first_value_in_prompt_and_negative():
+ plan = diffusion_xy.expand(
+ _req(
+ negative_prompt = "red blur",
+ xy = {"x": {"field": "prompt_sr", "values": ["red", "blue"]}},
+ )
+ )
+ assert [c.request.prompt for c in plan.cells] == ["a red sloth", "a blue sloth"]
+ assert plan.cells[1].request.negative_prompt == "blue blur"
+ with pytest.raises(ValueError, match = "not in the prompt"):
+ diffusion_xy.expand(_req(xy = {"x": {"field": "prompt_sr", "values": ["green", "blue"]}}))
+
+
+def test_lora_weight_axis_targets_one_entry_and_zero_drops_it():
+ plan = diffusion_xy.expand(
+ _req(
+ loras = [{"id": "a", "weight": 1.0}, {"id": "b", "weight": 0.5}],
+ xy = {"x": {"field": "lora_weight", "index": 1, "values": [0, 1]}},
+ )
+ )
+ assert [[(l.id, l.weight) for l in c.request.loras] for c in plan.cells] == [
+ [("a", 1.0)],
+ [("a", 1.0), ("b", 1.0)],
+ ]
+ assert plan.order == [0, 1]
+
+
+def test_out_of_range_value_names_the_cell():
+ with pytest.raises(ValueError, match = r"xy cell \(Steps: 200\): steps"):
+ diffusion_xy.expand(_req(xy = {"x": {"field": "steps", "values": [4, 200]}}))
+
+
+ "body, match",
+ [
+ ({"xy": {"x": {"field": "width", "values": [512]}}}, "field"),
+ (
+ {
+ "xy": {
+ "x": {"field": "steps", "values": list(range(1, 10))},
+ "y": {"field": "guidance", "values": list(range(8))},
+ }
+ },
+ "over the limit",
+ ),
+ (
+ {
+ "xy": {
+ "x": {"field": "steps", "values": [4]},
+ "y": {"field": "steps", "values": [8]},
+ }
+ },
+ "both vary",
+ ),
+ ({"batch_size": 2, "xy": {"x": {"field": "steps", "values": [4]}}}, "batch size 1"),
+ ({"seeds": [1, 2], "xy": {"x": {"field": "steps", "values": [4]}}}, "batch size 1"),
+ ({"xy": {"x": {"field": "lora_weight", "values": [1]}}}, "index"),
+ ({"xy": {"x": {"field": "lora_weight", "index": 0, "values": [1]}}}, "no entry in loras"),
+ ({"xy": {"x": {"field": "prompt_sr", "values": ["", "x"]}}}, "cannot be empty"),
+ ],
+)
+def test_spec_is_validated(body, match):
+ with pytest.raises(ValidationError, match = match):
+ _req(**body)
+
+
+def test_cap_matches_the_images_page_compare_grid():
+ assert MAX_XY_CELLS == 64
+ _req(
+ xy = {
+ "x": {"field": "steps", "values": list(range(1, 9))},
+ "y": {"field": "seed", "values": list(range(8))},
+ }
+ )
+
+
+def _cells(plan, size = (64, 48)):
+ from PIL import Image
+ return [Image.new("RGB", size, (40 * c.ix, 40 * c.iy, 200)) for c in plan.cells]
+
+
+def test_compose_grid_lays_out_headers_and_cells():
+ plan = diffusion_xy.expand(
+ _req(
+ xy = {
+ "x": {"field": "steps", "values": [4, 8, 12]},
+ "y": {"field": "guidance", "values": [0, 1, 2]},
+ }
+ )
+ )
+ grid = diffusion_xy.compose_grid(_cells(plan), plan)
+ left, top = 64 * 3 // 4, grid.height - 3 * 48
+ assert grid.width == left + 3 * 64 and top > 0
+ assert grid.getpixel((left + 2 * 64 + 32, top + 48 + 24)) == (80, 40, 200)
+ band = grid.crop((left, 0, grid.width, top))
+ assert band.convert("L").getextrema()[0] < 128
+ assert grid.getpixel((1, 1)) == (255, 255, 255)
+
+
+def test_compose_grid_without_y_has_no_left_band():
+ plan = diffusion_xy.expand(_req(xy = {"x": {"field": "steps", "values": [4, 8]}}))
+ grid = diffusion_xy.compose_grid(_cells(plan), plan)
+ assert grid.width == 2 * 64
+
+
+def test_compose_grid_scales_down_past_the_pixel_budget(monkeypatch):
+ monkeypatch.setattr(diffusion_xy, "MAX_GRID_PIXELS", 4 * 640 * 480)
+ plan = diffusion_xy.expand(
+ _req(
+ xy = {"x": {"field": "steps", "values": [4, 8]}, "y": {"field": "seed", "values": [1, 2]}}
+ )
+ )
+ grid = diffusion_xy.compose_grid(_cells(plan, size = (1280, 960)), plan)
+ assert grid.width * grid.height <= 4 * 640 * 480 and grid.width < 2 * 640 * 1.75
+
+
+def test_route_renders_each_cell_and_saves_a_labelled_grid(client):
+ import core.inference.diffusion as diffusion_module
+ from PIL import Image
+
+ client.post(
+ "/api/inference/images/load",
+ json = {"model_path": "x/z-image", "gguf_filename": "q.gguf"},
+ )
+ backend = diffusion_module.get_diffusion_backend()
+ calls = []
+
+ def _generate(**kwargs):
+ calls.append(kwargs)
+ return {
+ "images": [Image.new("RGB", (64, 64), "gray")],
+ "seed": kwargs["seed"],
+ "repo_id": "x/z-image",
+ "workflow": "txt2img",
+ }
+
+ backend.generate = _generate
+ resp = client.post(
+ "/api/inference/images/generate",
+ json = {
+ "prompt": "a sloth",
+ "seed": 11,
+ "xy": {
+ "x": {"field": "steps", "values": [2, 4, 6]},
+ "y": {"field": "guidance", "values": [0, 1, 2]},
+ },
+ },
+ )
+ assert resp.status_code == 200, resp.text
+ body = resp.json()
+ assert [(c["steps"], c["guidance"]) for c in calls] == [
+ (2, 0.0),
+ (4, 0.0),
+ (6, 0.0),
+ (2, 1.0),
+ (4, 1.0),
+ (6, 1.0),
+ (2, 2.0),
+ (4, 2.0),
+ (6, 2.0),
+ ]
+ assert {c["seed"] for c in calls} == {11}
+ cells = body["images"]
+ assert [(c["steps"], c["guidance"]) for c in cells] == [
+ (c["steps"], c["guidance"]) for c in calls
+ ]
+ grid = body["grid"]
+ assert grid["xy_grid"]["cells"] == [c["id"] for c in cells]
+ assert grid["xy_grid"]["x"]["labels"] == ["Steps: 2", "Steps: 4", "Steps: 6"]
+ assert (grid["xy_grid"]["cell_width"], grid["xy_grid"]["cell_height"]) == (64, 64)
+ assert grid["width"] == 48 + 3 * 64 and grid["height"] > 3 * 64
+ gallery = client.get("/api/inference/images/gallery").json()["images"]
+ assert len(gallery) == 10
+
+
+def test_route_refuses_a_bad_cell_before_rendering(client):
+ import core.inference.diffusion as diffusion_module
+
+ client.post(
+ "/api/inference/images/load",
+ json = {"model_path": "x/z-image", "gguf_filename": "q.gguf"},
+ )
+ backend = diffusion_module.get_diffusion_backend()
+ backend.generate = lambda **kw: pytest.fail("no cell may render")
+ resp = client.post(
+ "/api/inference/images/generate",
+ json = {"prompt": "a sloth", "xy": {"x": {"field": "steps", "values": [4, 500]}}},
+ )
+ assert resp.status_code == 400 and "Steps: 500" in resp.json()["detail"]
+ over = client.post(
+ "/api/inference/images/generate",
+ json = {"prompt": "a sloth", "xy": {"x": {"field": "seed", "values": list(range(65))}}},
+ )
+ assert over.status_code == 422
+
+
+def test_stop_between_cells_ends_the_grid(client):
+ import core.inference.diffusion as diffusion_module
+ from PIL import Image
+
+ client.post(
+ "/api/inference/images/load",
+ json = {"model_path": "x/z-image", "gguf_filename": "q.gguf"},
+ )
+ backend = diffusion_module.get_diffusion_backend()
+ calls = []
+
+ def _generate(**kwargs):
+ calls.append(kwargs)
+ assert client.post("/api/inference/images/generate/cancel").json() == {"cancelled": True}
+ return {
+ "images": [Image.new("RGB", (64, 64), "gray")],
+ "seed": kwargs["seed"],
+ "repo_id": "x/z-image",
+ "workflow": "txt2img",
+ }
+
+ backend.generate = _generate
+ backend.cancel_generate = lambda **kw: False
+ resp = client.post(
+ "/api/inference/images/generate",
+ json = {"prompt": "a sloth", "xy": {"x": {"field": "steps", "values": [2, 4, 6]}}},
+ )
+ assert resp.status_code == 409, resp.text
+ assert len(calls) == 1
+ assert len(client.get("/api/inference/images/gallery").json()["images"]) == 1
+ assert client.post("/api/inference/images/generate/cancel").json() == {"cancelled": False}
+
+
+def test_grid_infotext_records_the_cell_size():
+ from core.inference import image_gallery
+
+ meta = {"prompt": "a sloth", "width": 2880, "height": 2441, "seed": 1, "steps": 8}
+ assert "Size: 2880x2441," in image_gallery._params_text(meta)
+ meta["xy_grid"] = {"cell_width": 768, "cell_height": 768}
+ assert "Size: 768x768," in image_gallery._params_text(meta)
+
+
+def test_lora_with_its_default_weight_expands():
+ plan = diffusion_xy.expand(
+ _req(loras = [{"id": "adapter"}], xy = {"x": {"field": "steps", "values": [2, 4]}})
+ )
+ assert [c.request.loras[0].weight for c in plan.cells] == [1.0, 1.0]
+
+
+def test_variation_strength_sweep_shares_one_variation_seed():
+ plan = diffusion_xy.expand(
+ _req(xy = {"x": {"field": "variation_strength", "values": [0.1, 0.3, 0.5]}}),
+ rng = random.Random(0),
+ )
+ seeds = {c.request.variation_seed for c in plan.cells}
+ assert len(seeds) == 1 and None not in seeds
+ plain = diffusion_xy.expand(_req(xy = {"x": {"field": "steps", "values": [2, 4]}}))
+ assert {c.request.variation_seed for c in plain.cells} == {None}
+
+
+def test_cells_with_any_adapter_render_before_adapter_free_ones():
+ plan = diffusion_xy.expand(
+ _req(
+ loras = [{"id": "a", "weight": 1}, {"id": "b", "weight": 0}],
+ xy = {"x": {"field": "lora_weight", "index": 0, "values": [0, 1]}},
+ )
+ )
+ assert plan.order == [1, 0]
+
+
+def test_stop_reaches_a_cell_still_waiting_for_the_engine(client):
+ import core.inference.diffusion as diffusion_module
+ import threading
+ from core.inference.diffusion_families import DIFFUSION_CANCELLED_MSG
+ from core.inference.generation_ticket import bind_generation_cancel
+
+ client.post(
+ "/api/inference/images/load",
+ json = {"model_path": "x/z-image", "gguf_filename": "q.gguf"},
+ )
+ backend = diffusion_module.get_diffusion_backend()
+
+ def _generate(**kwargs):
+ # As the engine does: bind the cell's cancel, then (here) be stopped while queued for the slot.
+ cancel = threading.Event()
+ bind_generation_cancel(cancel)
+ client.post("/api/inference/images/generate/cancel")
+ assert cancel.is_set()
+ raise RuntimeError(DIFFUSION_CANCELLED_MSG)
+
+ backend.generate = _generate
+ backend.cancel_generate = lambda **kw: False
+ resp = client.post(
+ "/api/inference/images/generate",
+ json = {"prompt": "a sloth", "xy": {"x": {"field": "steps", "values": [2, 4]}}},
+ )
+ assert resp.status_code == 409, resp.text
+ assert client.get("/api/inference/images/gallery").json()["images"] == []
+
+
+def test_string_zero_lora_weight_drops_the_adapter_and_renders_last():
+ plan = diffusion_xy.expand(
+ _req(
+ loras = [{"id": "a", "weight": 1}],
+ xy = {"x": {"field": "lora_weight", "index": 0, "values": ["0", "1"]}},
+ )
+ )
+ assert [c.request.loras for c in plan.cells][0] is None
+ assert plan.order == [1, 0]
+
+
+def test_long_labels_and_big_cells_stay_inside_the_pixel_budget():
+ from PIL import Image
+
+ long = " ".join(["word"] * 600)
+ plan = diffusion_xy.expand(
+ _req(
+ prompt = "a red sloth",
+ xy = {
+ "x": {"field": "prompt_sr", "values": ["red", long] + [f"c{i}" for i in range(62)]}
+ },
+ )
+ )
+ cells = [Image.new("RGB", (720, 720), "gray") for _ in plan.cells]
+ grid = diffusion_xy.compose_grid(cells, plan)
+ assert grid.width * grid.height <= diffusion_xy.MAX_GRID_PIXELS
+
+
+def test_fit_cell_keeps_each_render_to_its_share_of_the_budget():
+ from PIL import Image
+
+ plan = diffusion_xy.expand(_req(xy = {"x": {"field": "seed", "values": list(range(64))}}))
+ small = diffusion_xy.fit_cell(Image.new("RGB", (2048, 2048)), plan)
+ assert small.width * small.height <= diffusion_xy.MAX_GRID_PIXELS / 64
+ same = Image.new("RGB", (512, 512))
+ assert diffusion_xy.fit_cell(same, plan) is same
+
+
+def test_stop_after_the_last_cell_ends_the_grid_unsaved(client):
+ import core.inference.diffusion as diffusion_module
+ from PIL import Image
+
+ client.post(
+ "/api/inference/images/load",
+ json = {"model_path": "x/z-image", "gguf_filename": "q.gguf"},
+ )
+ backend = diffusion_module.get_diffusion_backend()
+ calls = []
+
+ def _generate(**kwargs):
+ calls.append(kwargs)
+ if len(calls) == 2:
+ assert client.post("/api/inference/images/generate/cancel").json() == {
+ "cancelled": True
+ }
+ return {
+ "images": [Image.new("RGB", (64, 64), "gray")],
+ "seed": kwargs["seed"],
+ "repo_id": "x/z-image",
+ "workflow": "txt2img",
+ }
+
+ backend.generate = _generate
+ backend.cancel_generate = lambda **kw: False
+ resp = client.post(
+ "/api/inference/images/generate",
+ json = {"prompt": "a sloth", "xy": {"x": {"field": "steps", "values": [2, 4]}}},
+ )
+ assert resp.status_code == 409, resp.text
+ gallery = client.get("/api/inference/images/gallery").json()["images"]
+ assert len(gallery) == 2 and not any(g.get("xy_grid") for g in gallery)
+
+
+def test_layered_model_is_refused_before_any_cell_renders(client, monkeypatch):
+ import core.inference.diffusion as diffusion_module
+ import core.inference.diffusion_engine_router as router
+
+ client.post(
+ "/api/inference/images/load",
+ json = {"model_path": "x/z-image", "gguf_filename": "q.gguf"},
+ )
+ backend = diffusion_module.get_diffusion_backend()
+ backend.generate = lambda **kw: pytest.fail("no cell may render")
+ engine = router.get_active_diffusion_engine()
+ real_status = engine.status
+ monkeypatch.setattr(engine, "status", lambda: {**real_status(), "family": "qwen-image-layered"})
+ resp = client.post(
+ "/api/inference/images/generate",
+ json = {"prompt": "a sloth", "xy": {"x": {"field": "steps", "values": [2, 4]}}},
+ )
+ assert resp.status_code == 400 and "2 layers" in resp.json()["detail"], resp.text
+
+
+def test_grid_stop_is_keyed_on_the_stable_account_id(monkeypatch):
+ import routes.inference as routes_inference
+ from core.inference.generation_ticket import GenerationTicket
+
+ ticket = GenerationTicket()
+ monkeypatch.setattr(routes_inference, "_xy_grid_stops", [("owner-id", ticket)])
+ monkeypatch.setattr(routes_inference, "current_account_id", lambda: "owner-id")
+ # Scope moves from None to the owner's id once the first managed account exists.
+ monkeypatch.setattr(routes_inference.account_access, "account_scope", lambda: "something-else")
+ assert routes_inference._stop_xy_grids() is True and ticket.cancelled()
diff --git a/studio/backend/tests/test_liveness_reports_inference_active.py b/studio/backend/tests/test_liveness_reports_inference_active.py
index b154c6d79a7..031f92db5dc 100644
--- a/studio/backend/tests/test_liveness_reports_inference_active.py
+++ b/studio/backend/tests/test_liveness_reports_inference_active.py
@@ -283,8 +283,8 @@ def test_liveness_covers_the_image_persist_tail():
_PERSIST_COUNTER = "_diffusion_persist_active"
-# The two image routes' run bodies: the Unsloth /images/generate and the OpenAI-compatible /images/generations.
-_PERSIST_ROUTES = {"_generate_diffusion_image_run", "_generate_openai_images"}
+# The image routes' run bodies: /images/generate, its X/Y grid, and the OpenAI-compatible /images/generations.
+_PERSIST_ROUTES = {"_generate_diffusion_image_run", "_generate_openai_images", "_generate_xy_grid"}
def _persist_marker_violations(source: str) -> list[str]:
diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.ts
index 6d082e2e7d3..9bc1553270e 100644
--- a/studio/frontend/src/features/images/api.ts
+++ b/studio/frontend/src/features/images/api.ts
@@ -267,6 +267,17 @@ export interface DiffusionGenerateRequest {
hires?: HiresRequest;
// Upscale workflow: a model upscaler id from status.upscale_models; omitted = Lanczos.
upscale_model?: string | null;
+ // Server-side X/Y grid (API callers; the page's Compare grid builds its cells client-side).
+ xy?: { x: XYAxisSpec; y?: XYAxisSpec };
+}
+
+export interface XYAxisSpec {
+ field:
+ | "seed" | "steps" | "guidance" | "sampler" | "schedule_type" | "shift" | "base_shift" | "max_shift"
+ | "strength" | "clip_skip" | "cfg_rescale" | "variation_seed" | "variation_strength" | "lora_weight"
+ | "prompt_sr";
+ values: Array<number | string>;
+ index?: number;
}
export interface LoraSpecInput {
@@ -376,6 +387,13 @@ export interface GalleryImage {
hires_base_width?: number | null;
hires_base_height?: number | null;
created_at: number;
+ xy_grid?: {
+ x: { field: string; index: number | null; values: Array<number | string>; labels: string[] };
+ y?: { field: string; index: number | null; values: Array<number | string>; labels: string[] };
+ cells: string[];
+ cell_width?: number;
+ cell_height?: number;
+ } | null;
pinned?: boolean;
archived?: boolean;
order_at?: number | null;
@@ -383,6 +401,7 @@ export interface GalleryImage {
export interface DiffusionGenerateResponse {
images: GalleryImage[];
+ grid?: GalleryImage | null;
}
export async function parseJson<T>(response: Response): Promise<T> {
diff --git a/studio/frontend/src/features/images/image-size.ts b/studio/frontend/src/features/images/image-size.ts
index ccf977c07aa..5e5d929e267 100644
--- a/studio/frontend/src/features/images/image-size.ts
+++ b/studio/frontend/src/features/images/image-size.ts
@@ -117,3 +117,12 @@ export function restorableSize(
const scale = upTo > downTo ? 1 : Math.min(Math.max(1, upTo), downTo);
return fitSize(width * scale, height * scale, limits);
}
+
+// A server X/Y grid's width / height are the grid's pixels; its recipe is the first cell's, at the cell size.
+export function xyGridCellSize(image: {
+ xy_grid?: { cell_width?: number; cell_height?: number } | null;
+}): { width: number; height: number } | null {
+ const w = image.xy_grid?.cell_width;
+ const h = image.xy_grid?.cell_height;
+ return w && h && w > 0 && h > 0 ? { width: w, height: h } : null;
+}
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 33eda789e4d..1a129e3c3e7 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -254,6 +254,7 @@ import {
restorableSize,
sizeLimitsFrom,
snapDim,
+ xyGridCellSize,
} from "./image-size";
import {
ANNOTATION_COLORS,
@@ -2964,7 +2965,7 @@ export function ImagesPage({
// advances it again.
if (!viaConnection) setSeed(String(image.batch_seed ?? image.seed));
// A Hires fix image records its output size; the Width / Height controls take the base pass.
- const base = hiresBaseSize(image) ?? { width: image.width, height: image.height };
+ const base = hiresBaseSize(image) ?? xyGridCellSize(image) ?? { width: image.width, height: image.height };
const restored = restorableSize(base.width, base.height, image.workflow, sizeLimits);
setHires(resolveRestoredHires(hiresFromRecipe(image), status?.hires));
setUpscaleModel(image.upscale_model ?? null);
diff --git a/studio/frontend/src/features/images/lib/image-metadata.ts b/studio/frontend/src/features/images/lib/image-metadata.ts
index ed346f6ce24..f09a9b3c221 100644
--- a/studio/frontend/src/features/images/lib/image-metadata.ts
+++ b/studio/frontend/src/features/images/lib/image-metadata.ts
@@ -6,6 +6,7 @@ import {
detailerRecordOf,
type DetailerRecord,
} from "./detailer.ts";
+import { xyGridCellSize } from "../image-size.ts";
import { parseHiresInfotext } from "./hires-choice.ts";
import { SAMPLER_LABELS, SCHEDULE_LABELS } from "./sampler-choice.ts";
import type { SdControlsCapability } from "./sd-controls.ts";
@@ -1009,6 +1010,7 @@ export const APPLIED_RECIPE_KEYS = [
"hires_guidance",
"hires_base_width",
"hires_base_height",
+ "xy_grid",
] as const;
/** Known but not applied: loading a model or a ControlNet image stays the user's call. */
@@ -1262,8 +1264,9 @@ export function recipeSettings(
r: ImportedRecipe,
d: RecipeDefaults,
): RestorableRecipe {
- const width = int(r.width);
- const height = int(r.height);
+ const cell = xyGridCellSize(r as Parameters<typeof xyGridCellSize>[0]);
+ const width = cell?.width ?? int(r.width);
+ const height = cell?.height ?? int(r.height);
return {
prompt: str(r.prompt) ?? "",
negative_prompt: str(r.negative_prompt) ?? null,
diff --git a/studio/frontend/tests/image-restore-settings-size.test.ts b/studio/frontend/tests/image-restore-settings-size.test.ts
index 82d5c86ac4c..ef909f9fced 100644
--- a/studio/frontend/tests/image-restore-settings-size.test.ts
+++ b/studio/frontend/tests/image-restore-settings-size.test.ts
@@ -87,8 +87,11 @@ test("restoreSettings puts the record through restorableSize", () => {
body,
/restorableSize\(base\.width, base\.height, image\.workflow, sizeLimits\)/,
);
- // A Hires fix record restores its base pass; every other record its own size.
- assert.match(body, /const base = hiresBaseSize\(image\) \?\? \{ width: image\.width, height: image\.height \}/);
+ // A Hires fix record restores its base pass, an X/Y grid its cell size, every other record its own size.
+ assert.match(
+ body,
+ /const base = hiresBaseSize\(image\) \?\? xyGridCellSize\(image\) \?\? \{ width: image\.width, height: image\.height \}/,
+ );
assert.doesNotMatch(
body,
/setWidth\(image\.width\)|setHeight\(image\.height\)/,
diff --git a/studio/frontend/tests/images-xy-api.test.ts b/studio/frontend/tests/images-xy-api.test.ts
new file mode 100644
index 00000000000..c70806026cd
--- /dev/null
+++ b/studio/frontend/tests/images-xy-api.test.ts
@@ -0,0 +1,64 @@
+// 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 { availableAxes, MAX_COMPARE_CELLS, type CompareContext } from "../src/features/images/compare/compare-axes.ts";
+import { xyGridCellSize } from "../src/features/images/image-size.ts";
+import { recipeSettings, unknownRecipeKeys } from "../src/features/images/lib/image-metadata.ts";
+import { readSrc } from "./helpers/kit.ts";
+
+const backend = readFileSync(new URL("../../backend/models/inference.py", import.meta.url), "utf8");
+
+function literal(source: RegExp, text: string): string[] {
+ const body = text.match(source)?.[1];
+ assert.ok(body, `no match for ${source}`);
+ return [...body.matchAll(/"([a-z_]+)"/g)].map((m) => m[1]).sort();
+}
+
+test("the XYAxisSpec field union in api.ts is the backend's XYAxisField literal", () => {
+ const server = literal(/XYAxisField = Literal\[([\s\S]*?)\]/, backend);
+ const client = literal(/export interface XYAxisSpec \{\s*field:([\s\S]*?);/, readSrc("features/images/api.ts"));
+ assert.deepEqual(client, server);
+});
+
+test("every Images page Compare axis has a server-side xy field, under the same cell cap", () => {
+ const server = new Set(literal(/XYAxisField = Literal\[([\s\S]*?)\]/, backend));
+ const ctx: CompareContext = {
+ prompt: "a fox",
+ negativePrompt: "",
+ negativeCapable: true,
+ negativeMinGuidance: 1,
+ guidanceFixed: false,
+ guidance: 6,
+ samplers: [
+ { id: "default", label: "Default", schedule_types: ["automatic"] },
+ { id: "euler", label: "Euler", schedule_types: ["automatic", "karras"] },
+ ],
+ samplerChoice: { sampler: "default", scheduleType: "automatic" },
+ shift: { node: "flux", base_shift: 0.5, max_shift: 1.15 },
+ loraCapable: true,
+ loras: [{ id: "a", weight: 1, label: "a" }],
+ sdControls: { clip_skip: { min: 1, max: 12 }, cfg_rescale: { min: 0, max: 1 }, variation_seed: true },
+ controlnetEngaged: false,
+ } as unknown as CompareContext;
+ const toServer = (id: string) => (id === "schedule" ? "schedule_type" : id.startsWith("lora:") ? "lora_weight" : id);
+ for (const axis of availableAxes(ctx)) {
+ if (axis.id === "nothing") continue;
+ assert.ok(server.has(toServer(axis.id)), axis.id);
+ }
+ assert.match(backend, new RegExp(`^MAX_XY_CELLS = ${MAX_COMPARE_CELLS}$`, "m"));
+});
+
+test("reusing a server grid's recipe restores the cell size, not the grid's pixels", () => {
+ assert.deepEqual(xyGridCellSize({ xy_grid: { cell_width: 768, cell_height: 512 } }), { width: 768, height: 512 });
+ assert.equal(xyGridCellSize({ xy_grid: null }), null);
+ assert.equal(xyGridCellSize({}), null);
+ assert.match(readSrc("features/images/images-page.tsx"), /hiresBaseSize\(image\) \?\? xyGridCellSize\(image\) \?\?/);
+ const dropped = { prompt: "a fox", width: 2880, height: 2441, xy_grid: { cell_width: 768, cell_height: 768, cells: [] } };
+ const settings = recipeSettings(dropped, { width: 1024, height: 1024, steps: 8, guidance: 1 });
+ assert.deepEqual([settings.width, settings.height], [768, 768]);
+ assert.deepEqual(unknownRecipeKeys(dropped), []);
+});