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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: download image model assets without loading (#10789)
Michael Han217614f8b26e
diff --git a/.github/workflows/studio-ui-smoke.yml b/.github/workflows/studio-ui-smoke.ymlindex b2281ed3543..3e49cca8da0 100644--- a/.github/workflows/studio-ui-smoke.yml+++ b/.github/workflows/studio-ui-smoke.yml@@ -679,6 +679,7 @@ jobs:run: |mkdir -p logs/playwright_image_cancel_retrypython tests/studio/playwright_image_download_cancel_retry.py+ PW_DOWNLOAD_ONLY=1 PW_ART_DIR="$PW_ART_DIR/download-only" python tests/studio/playwright_image_download_cancel_retry.py# Same drive with the checkpoint absent, so the plan stages two entries instead of one and# the queue's ordering and cancellation are covered as well as the single-entry path.@@ -692,6 +693,19 @@ jobs:run: |mkdir -p logs/playwright_image_cancel_retry_coldpython tests/studio/playwright_image_download_cancel_retry.py+ PW_DOWNLOAD_ONLY=1 PW_ART_DIR="$PW_ART_DIR/download-only" python tests/studio/playwright_image_download_cancel_retry.py++ - name: Image download queue regression (Playwright)+ if: matrix.shard == 'extra'+ env:+ BASE_URL: http://127.0.0.1:18894+ PW_ART_DIR: logs/playwright_image_download_queue+ run: |+ PW_ART_DIR="$PW_ART_DIR/queue" python tests/studio/playwright_image_download_queue.py+ PW_ART_DIR="$PW_ART_DIR/load" PW_LOAD_SECOND=1 python tests/studio/playwright_image_download_queue.py+ PW_ART_DIR="$PW_ART_DIR/late-plan" PW_LOAD_SECOND=1 PW_HOLD_FIRST_PLAN=1 python tests/studio/playwright_image_download_queue.py+ PW_ART_DIR="$PW_ART_DIR/late-filename" PW_RESOLVE_FIRST=1 python tests/studio/playwright_image_download_queue.py+ PW_ART_DIR="$PW_ART_DIR/late-quant" PW_LOAD_SECOND=1 PW_HOLD_FIRST_PLAN=1 PW_DIFFERENT_QUANT=1 python tests/studio/playwright_image_download_queue.py# The Text encoder precision control: what the select sends to the plan and to the load, that# Default omits the field entirely, that a refresh race cannot leave a stale reading, and that@@ -903,6 +917,7 @@ jobs:logs/playwright_image_footprintlogs/playwright_image_cancel_retrylogs/playwright_image_cancel_retry_cold+ logs/playwright_image_download_queuelogs/playwright_image_text_encoderlogs/playwright_modelcfglogs/playwright_memory_estimatediff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.pyindex 09f09ef83af..e398a4dcf2b 100644--- a/studio/backend/core/inference/diffusion.py+++ b/studio/backend/core/inference/diffusion.py@@ -2348,7 +2348,12 @@ class DiffusionBackend:return {}def _dit_prequant_plan_source(- self, fam: Any, kind: str, hf_token: Optional[str], kwargs: dict[str, Any]+ self,+ fam: Any,+ kind: str,+ hf_token: Optional[str],+ kwargs: dict[str, Any],+ failures_out: Optional[list] = None,) -> Optional[tuple[str, str, int]]:"""The hosted PRE-QUANTIZED transformer this pick loads INSTEAD of the base repo's denseshards, as ``(repo, filename, declared_size)``, or None when no such artifact is used.@@ -2442,9 +2447,25 @@ class DiffusionBackend:for name in (source.filename, source.fallback_filename):if name and name in sizes:return (source.location, name, int(sizes[name]))+ # The repo answered and holds NEITHER name. Not "no prequant is used" -- this pick+ # is configured to use one and the dense shards are already excluded for it, so the+ # plan names no transformer source at all and must say it is partial.+ if failures_out is not None:+ failures_out.append(+ RuntimeError(+ f"prequant artifact missing from {source.location}: "+ f"{source.filename!r} / {source.fallback_filename!r}"+ )+ )return Noneexcept Exception as exc: # noqa: BLE001 -- an unsizable prequant must not fail the planlogger.warning("diffusion.dit_prequant_plan_failed: %s", exc)+ # Best-effort for the UI, but NOT for a caller that must not download afterwards: the+ # dense shards are already excluded for this pick, so a swallowed lookup leaves a plan+ # naming neither transformer source and calling itself complete. Download only would+ # then report success and the load would still pull multi-GB inline, or fail offline.+ if failures_out is not None:+ failures_out.append(exc)return None@staticmethod@@ -2761,7 +2782,9 @@ class DiffusionBackend:# footprint the plan would otherwise never report. Sized against the RESOLVED base, as the load passes it: a# variant base picks its own prequant repo.dit_prequant = (- self._dit_prequant_plan_source(fam, kind, hf_token, {**load_kwargs, "base_repo": base})+ self._dit_prequant_plan_source(+ fam, kind, hf_token, {**load_kwargs, "base_repo": base}, plan_failures+ )if allow_device_probeelse None)diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.pyindex 1898b3d2ca0..955b6eb9906 100644--- a/studio/backend/models/inference.py+++ b/studio/backend/models/inference.py@@ -4132,10 +4132,10 @@ class DiffusionDownloadPlanEntry(BaseModel):class DiffusionDownloadPlanResponse(BaseModel):- """What to download before a load, so the Hub download manager can fetch it with the- same file scope the loader would. Empty entries mean nothing to download (local path)."""+ """Files to stage before loading; plan_failed marks an incomplete listing."""entries: List[DiffusionDownloadPlanEntry] = Field(default_factory = list)+ plan_failed: bool = Field(False, description = "Metadata discovery left the file list incomplete")total_bytes: int = Field(0, description = "Sum of the remaining download entries, 0 when ready or unknown")diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.pyindex 3bfcd4c015a..54ef937a561 100644--- a/studio/backend/tests/test_diffusion_backend.py+++ b/studio/backend/tests/test_diffusion_backend.py@@ -7379,7 +7379,9 @@ def test_download_plan_stages_nothing_for_a_base_wholly_in_the_other_root(monkeydef test_download_plan_declines_an_unrecognised_gguf_instead_of_raising(monkeypatch):# A neutral repo whose id AND filename match no family resolves no companions, and the family# fallback used to raise on None. The picker asks for a plan on every hub pick, so that 500s- # the route; planning no work is the honest answer and the load still handles its own fetch.+ # the route; planning no work is the honest answer. /images/download-plan refuses this pick+ # outright before the planner is reached (see test_diffusion_routes.py), so nothing downstream+ # depends on the shape of this answer._fake_hf_api(monkeypatch, {})plan = DiffusionBackend().download_plan(@@ -10066,6 +10068,8 @@ def test_an_unsupported_host_is_not_told_its_shards_are_unstaged(def test_generation_in_flight_tracks_a_generation(fake_runtime, tmp_path, monkeypatch):+ from types import SimpleNamespace+import core.inference.diffusion as diffusion_modbackend = _loaded_backend(tmp_path)@@ -10097,3 +10101,44 @@ def test_generation_in_flight_never_builds_a_backend(fake_runtime, monkeypatch):lambda *a, **k: pytest.fail("liveness constructed a diffusion backend"),)assert diffusion_mod.generation_in_flight() is False+++def test_a_prequant_repo_missing_its_artifact_marks_the_plan_incomplete(monkeypatch):+ """The repo answers and holds NEITHER the primary nor the fallback name. That is not "no+ prequant is used": this pick is configured to use one and the dense shards are already excluded+ for it, so the plan would name no transformer source at all while calling itself complete."""+ from types import SimpleNamespace++ import core.inference.diffusion as diffusion_mod++ source = SimpleNamespace(+ kind = "repo",+ location = "unsloth/some-prequant",+ filename = "transformer_fp8.safetensors",+ fallback_filename = "transformer.fp8.safetensors",+ )+ monkeypatch.setattr(diffusion_mod, "usable_prequant_source", lambda *a, **k: source)+ monkeypatch.setattr(diffusion_mod, "select_transformer_quant_scheme", lambda *a, **k: "fp8")+ monkeypatch.setattr(+ DiffusionBackend, "_target_for_ordinal", lambda self, fam, ordinal: SimpleNamespace()+ )+ # A repo that exists but carries something else entirely.+ _fake_hf_api(+ monkeypatch,+ {"unsloth/some-prequant": [_FakeSibling("README.md", 10)]},+ )++ failures: list = []+ got = DiffusionBackend()._dit_prequant_plan_source(+ SimpleNamespace(name = "flux.2-klein"),+ "gguf",+ None,+ {"transformer_quant": "fp8"},+ failures,+ )++ assert got is None+ assert (+ failures+ ), "a configured prequant that is not in its repo left the plan calling itself complete"+ assert "prequant artifact missing" in str(failures[0])diff --git a/studio/backend/tests/test_diffusion_routes.py b/studio/backend/tests/test_diffusion_routes.pyindex 60e32008bcf..f1a9724adbd 100644--- a/studio/backend/tests/test_diffusion_routes.py+++ b/studio/backend/tests/test_diffusion_routes.py@@ -1713,7 +1713,10 @@ def test_download_plan_suppresses_only_the_verdict_while_training_runs(client, massert "allow_device_probe" not in seen, training-def test_download_plan_response_keeps_the_planners_checkpoint_marker(client, monkeypatch):[email protected]("plan_failed", [False, True])+def test_download_plan_response_keeps_the_planners_checkpoint_marker(+ client, monkeypatch, plan_failed+):# Through the ROUTE, not the planner: the response model is what the picker actually reads, and# a field the planner sets but the model does not declare is dropped silently on serialization.# That is exactly how the checkpoint marker was lost, leaving a mirrored pipeline mislabelled.@@ -1741,6 +1744,7 @@ def test_download_plan_response_keeps_the_planners_checkpoint_marker(client, mon"checkpoint": False,},],+ "plan_failed": plan_failed,"total_bytes": 30,"required_bytes": 30,"checkpoint_bytes": 10,@@ -1756,6 +1760,7 @@ def test_download_plan_response_keeps_the_planners_checkpoint_marker(client, mon)assert resp.status_code == 200+ assert resp.json()["plan_failed"] is plan_failedassert [e["checkpoint"] for e in resp.json()["entries"]] == [True, False]@@ -1785,6 +1790,7 @@ def test_download_plan_defaults_the_checkpoint_marker_for_an_older_planner(clien)assert resp.status_code == 200+ assert resp.json()["plan_failed"] is Falseassert resp.json()["entries"][0]["checkpoint"] is False@@ -2409,3 +2415,18 @@ def test_download_plan_still_refuses_a_bad_gpu_while_training_holds_the_cards(clresp = client.post("/api/inference/images/download-plan", json = {**body, "gpu_ids": [7]})assert resp.status_code == 400assert "visible to this process" in resp.json()["detail"]+++def test_the_plan_route_refuses_an_unrecognised_model_before_planning(client):+ """The route validates exactly as /images/load does, on purpose: an unloadable pick has to fail+ HERE rather than after a multi-GB download. So an unrecognised repo never reaches the planner,+ and Download only surfaces the reason instead of fetching a model nothing can open."""+ resp = _post_download_plan(+ client,+ model_path = "someone/mixed-gguf-collection",+ gguf_filename = "totally-unknown-thing-Q4_K_M.gguf",+ model_kind = "gguf",+ )++ assert resp.status_code == 400, resp.text+ assert "Could not infer a diffusion family" in resp.json()["detail"]diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.tsindex a85e25f7910..cc949ef314d 100644--- a/studio/frontend/src/features/images/api.ts+++ b/studio/frontend/src/features/images/api.ts@@ -287,6 +287,8 @@ export async function loadDiffusionModel(body: DiffusionLoadRequest): Promise<Di}export interface DiffusionDownloadPlan {+ /** Metadata discovery failed, so the file list may be incomplete. */+ plan_failed?: boolean;entries: {repo_id: string;files: string[];diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsxindex 901d28cf898..54ef88fecd2 100644--- a/studio/frontend/src/features/images/images-page.tsx+++ b/studio/frontend/src/features/images/images-page.tsx@@ -166,7 +166,7 @@ import {shouldReportGenerateError,} from "./lib/generation-stop";import { useNavigate, useSearch } from "@tanstack/react-router";-import { useStagedDownload } from "@/features/hub/download-manager";+import { useStagedDownload, type StagedDownloadEntry } from "@/features/hub/download-manager";import { DiffusionTrainPanel } from "./train/diffusion-train-panel";import {TrainBaseSelector,@@ -1266,6 +1266,7 @@ export function ImagesPage({);// Advanced (load-time) options; "auto"/"off"/"none" map to the backend defaults. Changing one// while loaded shows "Reapply".+ const [modelSelectionAction, setModelSelectionAction] = useState<"load" | "download">("load");const [speedMode, setSpeedMode] = useState<"auto" | "off" | "eager" | "default" | "max">("auto");const [transformerQuant, setTransformerQuant] = useState<"none" | "auto" | "int8" | "fp8" | "nvfp4" | "mxfp8"@@ -1413,7 +1414,8 @@ export function ImagesPage({const claimImageRecipe = imagePresets.claimRecipe;const imageFormClaimId = imagePresets.formClaimId;const applyImageModelDefaults = useCallback(- (repoId: string) => {+ (repoId: string, forceLoad = false) => {+ if (modelSelectionAction === "download" && !forceLoad) return;const revert = quantRevert.current;if (revert && !revert.releaseRecipeClaim) {const claim = claimImageRecipe();@@ -1433,7 +1435,7 @@ export function ImagesPage({revert.appliedGuidance = recommended.guidance;}},- [claimImageRecipe, imageFormClaimId],+ [claimImageRecipe, imageFormClaimId, modelSelectionAction],);const dismissLoadToast = useCallback(() => {@@ -1463,8 +1465,10 @@ export function ImagesPage({// Client-side state that only means anything while a model is resident: the replacement// load's tracking and the Reapply target. Shared with the indicator eject.const dropResidentState = useCallback(() => {- // Cancel, not release: a resolving pick or a staged download would load back what was just- // ejected. Here rather than in handleUnload, so the loaded-models card is covered too.+ // Cancel picks that could reload the ejected model. Download-only work carries no pick token+ // at all now, so it keeps running without needing an exception here -- the exception it used to+ // need was inert anyway, since the marker was cleared when the PLAN resolved rather than when+ // the download finished.pickGuard.cancel();// Everything in flight is now stale. Clearing the timer stops the NEXT poll tick but not a// request awaiting its response, and those still apply terminal state; the counter is what@@ -2543,17 +2547,37 @@ export function ImagesPage({},[pickGuard, revertPick],);+ // Each download-only selection keeps its complete plan until it finishes or is cancelled.+ const downloadOnlyPlans = useRef<StagedDownloadEntry[][]>([]);+ const pendingLoadEntries = useRef<StagedDownloadEntry[] | null>(null);+ const stagedPlan = useRef<"download" | { token: number } | null>(null);+const { stage } = useStagedDownload({scopeId: "diffusion",onReady: () => {- if (!active) {- stagedLoadDeferred.current = true;+ if (stagedPlan.current === "download") {+ finishDownloadOnlyPlan();return;}- const pending = pendingStagedLoad.current;- if (pending) runStagedLoad(pending);+ if (pendingStagedLoad.current?.token === stagedPlan.current?.token) {+ pendingLoadEntries.current = null;+ }+ stagedPlan.current = null;+ if (startQueuedDownload()) return;+ resumePendingLoad();},onCancelled: () => {+ const cancelled = stagedPlan.current;+ if (cancelled === "download") {+ finishDownloadOnlyPlan();+ return;+ }+ stagedPlan.current = null;+ if (pendingStagedLoad.current?.token !== cancelled?.token) {+ startQueuedDownload();+ return;+ }+ pendingLoadEntries.current = null;// The selected model is only an intent until every dependency is ready: a cancelled companion// must not leave that intent behind for a late completion to load.pendingStagedLoad.current = null;@@ -2565,9 +2589,54 @@ export function ImagesPage({quantRevert.current = null;}stagedQuantRevert.current = null;+ startQueuedDownload();},});+ /** A staged file set, as the identity two picks of the same model share. */+ function planKey(entries: StagedDownloadEntry[]) {+ return JSON.stringify(+ entries.map((e) => [e.repoId, e.ggufFilename ?? "", [...e.files].sort()]).sort(),+ );+ }++ /** The file sets already queued, including the one downloading right now (the queue head). */+ function queuedDownloadKeys() {+ return new Set(downloadOnlyPlans.current.map(planKey));+ }++ function startQueuedDownload() {+ const next = downloadOnlyPlans.current[0];+ if (!next) return false;+ stagedPlan.current = "download";+ stage(next);+ return true;+ }++ function finishDownloadOnlyPlan() {+ stagedPlan.current = null;+ downloadOnlyPlans.current.shift();+ if (startQueuedDownload()) return;+ resumePendingLoad();+ }++ function resumePendingLoad() {+ const entries = pendingLoadEntries.current;+ const pending = pendingStagedLoad.current;+ if (!pending || !pickGuard.isLatest(pending.token)) {+ pendingLoadEntries.current = null;+ return;+ }+ if (entries) {+ stagedPlan.current = { token: pending.token };+ stage(entries);+ } else if (!active) {+ stagedLoadDeferred.current = true;+ } else {+ runStagedLoad(pending);+ }+ }+useEffect(() => {if (!active || !stagedLoadDeferred.current) return;stagedLoadDeferred.current = false;@@ -2613,71 +2682,113 @@ export function ImagesPage({opts: { kind: "gguf" | "single_file" | "pipeline"; filename?: string },source: ModelSelectorChangeMeta["source"] = "hub",token?: number,+ downloadSnapshot?: LoadAdvanced,): Promise<boolean> => {+ const downloadOnly = downloadSnapshot !== undefined || modelSelectionAction === "download";// Staging never sets `busy`, so a second pick passes the guard while this plan is in flight, and// plans resolve in response order rather than pick order. Bumped before the non-hub return too, so- // a local pick invalidates an in-flight hub plan.- const pick = ++pickSeq.current;+ // a local pick invalidates an in-flight hub plan. Never for a download-only pick: it supersedes+ // nothing, and retiring the sequence made the load it interrupted fail its own stale check below+ // and return silently, leaving the selected model neither staged nor loaded.+ const pick = downloadOnly ? pickSeq.current : ++pickSeq.current;// The previous pick's staged intent dies with it: a pick that stages nothing never calls// stage(), so the queue keeps the older job and its onReady loads the abandoned model.- pendingStagedLoad.current = null;- stagedLoadDeferred.current = false;- stagedQuantRevert.current = null;- const owns = () => token === undefined || pickGuard.holds(token);- if (!owns()) return true;- if (source !== "hub") return handleLoadRef.current(repoId, opts);+ // Only load intents have an owner; a download-only pick holds no token and answers true.+ const owns = () => token === undefined || downloadOnly || pickGuard.holds(token);+ // Resolved downloads retain their snapshot without replacing a newer load intent. Neither does+ // a download-only pick: it adds files to fetch, so retiring the staged load here left the model+ // that load was waiting for fully downloaded and never loaded.+ if (!downloadSnapshot && !downloadOnly) {+ pendingStagedLoad.current = null;+ pendingLoadEntries.current = null;+ stagedLoadDeferred.current = false;+ stagedQuantRevert.current = null;+ if (!owns()) return true;+ }+ if (source !== "hub" && !downloadOnly) return handleLoadRef.current(repoId, opts);// ONE snapshot for the plan and the load it fires: the download runs for minutes without setting `busy`.- const advanced = currentLoadAdvanced(repoId);+ const advanced = downloadSnapshot ?? currentLoadAdvanced(repoId);// Read before the await: a pick made while the plan resolves replaces quantRevert, and this- // job must not revert it.- const ownRevert = quantRevert.current;+ // job must not revert it. A download-only pick claims no slot at all: it never relabels the+ // selector, so there is nothing here it could own, and reverting what it found would restore+ // the PREVIOUS resident under a staged load that is still coming and then leave that load+ // nothing to commit.+ const ownRevert = downloadSnapshot || downloadOnly ? null : quantRevert.current;// Read inside the try, acted on outside it: refusing from in there would fall through to the// load if the refusal itself threw.let incompatible: string | null = null;try {const plan = await requestDownloadPlan(repoId, opts, advanced);- // Superseded. Report started so this pick's `.then` leaves the newer label alone.- if (pick !== pickSeq.current || !owns()) return true;+ // Only load intents are superseded; accepted downloads keep their own plans.+ if (!downloadOnly && (pick !== pickSeq.current || !owns())) return true;+ if (downloadOnly && plan.plan_failed) {+ throw new Error("Required asset metadata is incomplete. Retry when it is available.");+ }incompatible = plan.incompatible_reason ?? null;if (!incompatible && plan.entries.length > 0) {- pendingStagedLoad.current = {- repoId,- opts,- advanced,- token: token ?? pickGuard.claim(),- };- stagedQuantRevert.current = ownRevert;- stage(- plan.entries.map((e) => ({- repoId: e.repo_id,- files: e.files,- bytes: e.bytes,- ggufFilename: e.gguf_filename,- // The entry carrying the picked checkpoint file, so the panel can label it without guessing:- // filenames cannot tell the two apart, and repo identity is not enough when a checkpoint shares- // its repo with cached companions. The backend's answer wins, since a gated pipeline is staged- // from an ungated MIRROR. Nullish coalescing, not `or`: a planner answering false is still an answer.- checkpoint:- e.checkpoint ??- (opts.filename- ? e.files.includes(opts.filename)- : e.repo_id === repoId),- })),- );+ if (!downloadOnly) {+ pendingStagedLoad.current = {+ repoId,+ opts,+ advanced,+ token: token ?? pickGuard.claim(),+ };+ stagedQuantRevert.current = ownRevert;+ }+ const entries = plan.entries.map((e) => ({+ repoId: e.repo_id,+ files: e.files,+ bytes: e.bytes,+ ggufFilename: e.gguf_filename,+ // Keep the planner's checkpoint marker, including explicit false for companions.+ checkpoint:+ e.checkpoint ??+ (opts.filename+ ? e.files.includes(opts.filename)+ : e.repo_id === repoId),+ }));+ if (downloadOnly) {+ // Picking the same model twice plans the same files twice. Queueing both downloaded+ // every byte twice, and the second start could come back "busy" against the first.+ if (queuedDownloadKeys().has(planKey(entries))) return true;+ downloadOnlyPlans.current.push(entries);+ // A late plan waits for the active file set, including a normal load's download.+ if (stagedPlan.current === null) {+ stagedPlan.current = "download";+ stage(entries);+ }+ } else {+ pendingLoadEntries.current = entries;+ const pending = pendingStagedLoad.current;+ if (downloadOnlyPlans.current.length === 0 && pending) {+ stagedPlan.current = { token: pending.token };+ stage(entries);+ }+ }+ return true;+ }+ } catch (error) {+ if (downloadOnly) {+ toast.error("Could not plan the download", {+ description: error instanceof Error ? error.message : "Try selecting the model again.",+ });return true;}- } catch {// No plan (older backend, metadata hiccup): fall back to the load's own download.}// Re-checked: a plan that REJECTED after a newer pick would otherwise reach the fallback load.- if (pick !== pickSeq.current || !owns()) return true;+ if (!downloadOnly && (pick !== pickSeq.current || !owns())) return true;if (incompatible) {toast.error(incompatible);- return false;+ return downloadOnly;+ }+ if (downloadOnly) {+ toast.info("No downloads were planned for this selection");+ return true;}return handleLoadRef.current(repoId, opts, advanced);},- [stage, currentLoadAdvanced, requestDownloadPlan],+ [stage, currentLoadAdvanced, requestDownloadPlan, modelSelectionAction, pickGuard, revertPick],);const resolveDownloadFootprint = useCallback(@@ -2699,6 +2810,14 @@ export function ImagesPage({[currentLoadAdvanced, requestDownloadPlan, pickGuard, stage],);+ const beginPick = useCallback(() => {+ pickSeq.current += 1;+ pendingStagedLoad.current = null;+ pendingLoadEntries.current = null;+ stagedLoadDeferred.current = false;+ stagedQuantRevert.current = null;+ }, []);+// A GGUF pick can arrive with only a repo id. The backend rejects a gguf load with no filename// and a pipeline load of a GGUF repo, so name the file from the listing first.const loadGgufRepoPick = useCallback(@@ -2708,9 +2827,15 @@ export function ImagesPage({source: ModelSelectorChangeMeta["source"] = "hub",localPath?: string | null,): Promise<boolean> => {- // Claimed here so every entry point is covered; the next pick's claim makes this one inert.- const token = pickGuard.claim();- const isCurrent = () => isMounted.current && pickGuard.holds(token);+ // Normal loads belong to the latest selection. A download-only pick claims nothing and+ // retires nothing: it fetches files, and a staged load already in flight still owns the page.+ const downloadOnly = modelSelectionAction === "download";+ const token = downloadOnly ? 0 : pickGuard.claim();+ const downloadSnapshot = downloadOnly ? currentLoadAdvanced(repoId) : undefined;+ const isCurrent = () => isMounted.current &&+ (downloadOnly || pickGuard.holds(token));+ // onResolved skips the label for a download-only pick, so this snapshot is never installed+ // for one; taking the slot over would strand a staged load's own baseline in it.const revert: PickRevert = quantRevert.current ?? { prev: quant, steps, guidance };return runGgufRepoPick({isCurrent,@@ -2722,24 +2847,29 @@ export function ImagesPage({}),// Still ambiguous (several quants, or the listing failed): only the expander can say which.onAmbiguous: () =>- toast.error("Pick a quantization for this model to load it"),+ toast.error(downloadOnly+ ? "Pick a quantization for this model to download it"+ : "Pick a quantization for this model to load it"),// Optimistic label, reverted if the load never starts, like the curated GGUF branch below.onResolved: (filename) => {+ if (downloadOnly) return;quantRevert.current = revert;setQuant(quantHint ?? filename);applyImageModelDefaults(repoId);},onNotStarted: () => {- if (quantRevert.current === revert) {+ // Nothing was applied for a download-only pick, so there is nothing to hand back, and+ // what sits in the slot is the staged load's own baseline.+ if (!downloadOnly && quantRevert.current === revert) {revertPick(revert);quantRevert.current = null;}},load: (filename) =>- loadOrStage(repoId, { kind: "gguf", filename }, source, token),+ loadOrStage(repoId, { kind: "gguf", filename }, source, token, downloadSnapshot),});},- [applyImageModelDefaults, loadOrStage, pickGuard, quant, revertPick],+ [applyImageModelDefaults, currentLoadAdvanced, loadOrStage, modelSelectionAction, pickGuard, quant, revertPick],);// A hidden page owns nothing: both stay mounted, so a resolution started here must not load after the user switched.@@ -2772,8 +2902,11 @@ export function ImagesPage({const key = `${wanted}|${routeSearch?.quant ?? ""}|${routeSearch?.ggufQuant ?? ""}`;if (handledRouteModel.current === key) return;handledRouteModel.current = key;- // This arrival owns the page like a direct pick, so a download staged by an earlier one cannot land on top.- const token = pickGuard.claim();+ // This arrival owns the page like a direct pick, so a download staged by an earlier one cannot+ // land on top -- unless it is a Download only arrival, which owns nothing and must leave a load+ // already staging with its claim, or resumePendingLoad drops that load once its files arrive.+ const downloadOnlyPick = modelSelectionAction === "download";+ const token = downloadOnlyPick ? undefined : pickGuard.claim();void navigateSelf({ to: "/images", search: {}, replace: true });// A label means a GGUF repo whatever the catalog says, and is not loadable, so resolve it// rather than routing it as a filename.@@ -2796,13 +2929,18 @@ export function ImagesPage({return;}// Match every direct picker branch: the routed intent owns both the visible build label and- // the Default recipe, and a load that never becomes resident rolls both back.- const revert: PickRevert = quantRevert.current ?? { prev: quant, steps, guidance };- quantRevert.current = revert;- setQuant(pick.opts.kind === "pipeline" ? null : (pick.opts.filename ?? null));- applyImageModelDefaults(wanted);+ // the Default recipe, and a load that never becomes resident rolls both back. A Download only+ // arrival owns neither, and quantRevert is one slot a staged load may already hold.+ const revert: PickRevert | null = downloadOnlyPick+ ? null+ : (quantRevert.current ?? { prev: quant, steps, guidance });+ if (revert) {+ quantRevert.current = revert;+ setQuant(pick.opts.kind === "pipeline" ? null : (pick.opts.filename ?? null));+ applyImageModelDefaults(wanted);+ }void loadOrStage(pick.repoId, pick.opts, "hub", token).then((started) => {- if (!started && pickGuard.holds(token) && quantRevert.current === revert) {+ if (!started && revert && token !== undefined && pickGuard.holds(token) && quantRevert.current === revert) {revertPick(revert);quantRevert.current = null;}@@ -2816,6 +2954,7 @@ export function ImagesPage({routeSearch?.ggufQuant,loadOrStage,loadGgufRepoPick,+ modelSelectionAction,navigateSelf,pickGuard,quant,@@ -2839,39 +2978,47 @@ export function ImagesPage({}}, [revertPick]);- const beginPick = useCallback(() => {- pickSeq.current += 1;- pendingStagedLoad.current = null;- stagedLoadDeferred.current = false;- stagedQuantRevert.current = null;- }, []);-// The chat picker emits (modelId, quant + filename) for a GGUF, or just (modelId) for a curated safetensors pick.const handleModelSelect = useCallback((id: string, meta: ModelSelectorChangeMeta) => {- // Ignore picks while a load/generation/unload is in flight: the backend rejects a second load with a 409.- if (busy !== null) return;- beginPick();+ // A Download only selection fetches files; it does not take over the page. Retiring the staged+ // intent and claiming the page for it stranded a load that was already downloading: that model+ // finished downloading and then never loaded, with no toast and nothing to retry from.+ const downloadOnlyPick = modelSelectionAction === "download";+ // Ignore picks while a load/generation/unload is in flight: the backend rejects a second load+ // with a 409. A download-only pick submits no load, so that cannot happen, and the selector+ // stays interactive during a generation: refusing it there was a silent dead click.+ if (busy !== null && !downloadOnlyPick) return;+ if (!downloadOnlyPick) beginPick();// This pick owns the page now, so one still awaiting a listing or a plan drops out. Before any// branch, since staging never sets `busy`.- const token = pickGuard.claim();+ const token = downloadOnlyPick ? undefined : pickGuard.claim();+ // A download-only pick holds no token, and an absent token owns nothing to hand back.+ const stillOwnsPick = (): boolean => token !== undefined && pickGuard.holds(token);// Curated non-GGUF model: load as a full pipeline or single-file safetensors.const spec = loadSpecFor(id, IMAGE_CATALOG);if (spec && spec.kind !== "gguf") {// Carried forward when one is already pending: a superseded staged pick left its optimistic// quant and recipe in state, so snapshotting now would record THAT and restore a model that// never loaded. Leaving the old entry would also let that download revert this pick.- const revert: PickRevert = quantRevert.current ?? { prev: quant, steps, guidance };- quantRevert.current = revert;- setQuant(null);- applyImageModelDefaults(id);+ // A Download only pick fetches files and never becomes the resident model, so it+ // relabels nothing and claims no revert: quantRevert is ONE slot, and a staged load+ // already in flight owns what is in it and still has to commit it.+ const revert: PickRevert | null = downloadOnlyPick+ ? null+ : (quantRevert.current ?? { prev: quant, steps, guidance });+ if (revert) {+ quantRevert.current = revert;+ setQuant(null);+ applyImageModelDefaults(id);+ }void loadOrStage(id,{ kind: spec.kind, filename: spec.filename },meta.source,token,).then((started) => {- if (!started && pickGuard.holds(token)) {+ if (!started && revert && stillOwnsPick()) {revertPick(revert);quantRevert.current = null;}@@ -2881,10 +3028,17 @@ export function ImagesPage({// GGUF quant pick from the variant expander. Optimistic for instant feedback, but reverted if// the load fails to START or later in the poll: the old pipeline stays loaded either way.if (meta.ggufVariant && meta.ggufFilename) {- const revert: PickRevert = quantRevert.current ?? { prev: quant, steps, guidance };- quantRevert.current = revert;- setQuant(meta.ggufVariant);- applyImageModelDefaults(id);+ // A Download only pick fetches files and never becomes the resident model, so it+ // relabels nothing and claims no revert: quantRevert is ONE slot, and a staged load+ // already in flight owns what is in it and still has to commit it.+ const revert: PickRevert | null = downloadOnlyPick+ ? null+ : (quantRevert.current ?? { prev: quant, steps, guidance });+ if (revert) {+ quantRevert.current = revert;+ setQuant(meta.ggufVariant);+ applyImageModelDefaults(id);+ }void loadOrStage(id,{ kind: "gguf", filename: meta.ggufFilename },@@ -2892,7 +3046,7 @@ export function ImagesPage({token,).then((started) => {// `quantRevert` is one slot, so only the pick that set the label may take it back.- if (!started && pickGuard.holds(token)) {+ if (!started && revert && stillOwnsPick()) {revertPick(revert);quantRevert.current = null;}@@ -2918,12 +3072,21 @@ export function ImagesPage({}// A direct pick carries no curated variant label, so surface the filename or the selector// keeps advertising the old quant. Optimistic, reverted if the load never starts.- const revert: PickRevert = quantRevert.current ?? { prev: quant, steps, guidance };- quantRevert.current = revert;- setQuant(filename);- applyImageModelDefaults(id);- void handleLoad(dir, { kind: "gguf", filename }).then((started) => {- if (!started) {+ // A Download only pick fetches files and never becomes the resident model, so it+ // relabels nothing and claims no revert: quantRevert is ONE slot, and a staged load+ // already in flight owns what is in it and still has to commit it.+ const revert: PickRevert | null = downloadOnlyPick+ ? null+ : (quantRevert.current ?? { prev: quant, steps, guidance });+ if (revert) {+ quantRevert.current = revert;+ setQuant(filename);+ applyImageModelDefaults(id);+ }+ void loadOrStage(dir, { kind: "gguf", filename }, meta.source, token).then((started) => {+ // Guarded like every sibling branch: quantRevert is one slot, so a pick that no longer+ // owns the page must not hand back a label a newer pick has already set.+ if (!started && revert && stillOwnsPick()) {revertPick(revert);quantRevert.current = null;}@@ -2937,12 +3100,19 @@ export function ImagesPage({const slash = norm.lastIndexOf("/");const filename = slash >= 0 ? norm.slice(slash + 1) : norm;const dir = slash >= 0 ? norm.slice(0, slash) : ".";- const revert: PickRevert = quantRevert.current ?? { prev: quant, steps, guidance };- quantRevert.current = revert;- setQuant(filename);- applyImageModelDefaults(id);- void handleLoad(dir, { kind: "single_file", filename }).then((started) => {- if (!started) {+ // A Download only pick fetches files and never becomes the resident model, so it+ // relabels nothing and claims no revert: quantRevert is ONE slot, and a staged load+ // already in flight owns what is in it and still has to commit it.+ const revert: PickRevert | null = downloadOnlyPick+ ? null+ : (quantRevert.current ?? { prev: quant, steps, guidance });+ if (revert) {+ quantRevert.current = revert;+ setQuant(filename);+ applyImageModelDefaults(id);+ }+ void loadOrStage(dir, { kind: "single_file", filename }, meta.source, token).then((started) => {+ if (!started && revert && stillOwnsPick()) {revertPick(revert);quantRevert.current = null;}@@ -2963,17 +3133,26 @@ export function ImagesPage({}// Otherwise treat it as a full diffusers repo. The backend gates loads to unsloth/* repos or on-device paths.if (meta.source !== "local" && !id.toLowerCase().startsWith("unsloth/")) {+ // A refused Download only pick retires nothing: it never claimed the page, and the rollback+ // slot it would clear belongs to whatever load is still staging.toast.error("Only unsloth or on-device image models can be loaded here");- abandonPick();+ if (!downloadOnlyPick) abandonPick();return;}// Optimistically clear the quant label, revert it if the load never starts.- const revert: PickRevert = quantRevert.current ?? { prev: quant, steps, guidance };- quantRevert.current = revert;- setQuant(null);- applyImageModelDefaults(id);+ // A Download only pick fetches files and never becomes the resident model, so it+ // relabels nothing and claims no revert: quantRevert is ONE slot, and a staged load+ // already in flight owns what is in it and still has to commit it.+ const revert: PickRevert | null = downloadOnlyPick+ ? null+ : (quantRevert.current ?? { prev: quant, steps, guidance });+ if (revert) {+ quantRevert.current = revert;+ setQuant(null);+ applyImageModelDefaults(id);+ }void loadOrStage(id, { kind: "pipeline" }, meta.source, token).then((started) => {- if (!started && pickGuard.holds(token)) {+ if (!started && revert && stillOwnsPick()) {revertPick(revert);quantRevert.current = null;}@@ -3016,7 +3195,7 @@ export function ImagesPage({const revert: PickRevert = quantRevert.current ?? { prev: quant, steps, guidance };quantRevert.current = revert;setQuant(null);- applyImageModelDefaults(args.baseRepo);+ applyImageModelDefaults(args.baseRepo, true);void handleLoad(args.baseRepo, { kind: "pipeline" }).then((started) => {if (!started) {pendingDeploy.current = null;@@ -3413,6 +3592,16 @@ export function ImagesPage({const advancedControls = (<>+ <AdvancedSelect+ label="On model selection"+ hint="Choose Download only to prepare the selected model and its required assets without loading it. Applies to the next model you select; progress and cancellation appear in Downloads."+ value={modelSelectionAction}+ onValueChange={(v) => setModelSelectionAction(v as typeof modelSelectionAction)}+ options={[+ ["load", "Download and load"],+ ["download", "Download only"],+ ]}+ /><AdvancedSelectlabel="Speed"hint="Auto picks per model: GGUF compiles at load; a dense model keeps the first two images exact and eager, then compiles from the 3rd (~2x from there). eager = fused kernels, no compile. default/max add torch.compile (max also TF32 + fused QKV)."diff --git a/tests/studio/playwright_image_download_cancel_retry.py b/tests/studio/playwright_image_download_cancel_retry.pyindex 09ec0332901..2a68981bd0f 100644--- a/tests/studio/playwright_image_download_cancel_retry.py+++ b/tests/studio/playwright_image_download_cancel_retry.py@@ -16,11 +16,12 @@ No model bytes are downloaded and no GPU is required.import jsonimport os+import reimport timefrom pathlib import Pathfrom urllib.parse import parse_qs, urlparse-from playwright.sync_api import Route, sync_playwright+from playwright.sync_api import Route, expect, sync_playwrightfrom playwright_image_model_footprint import (BASE_URL,@@ -40,6 +41,7 @@ ART_DIR.mkdir(parents = True, exist_ok = True)EXPECT = os.environ.get("PW_EXPECT", "after").strip().lower()if EXPECT not in {"before", "after"}:raise ValueError("PW_EXPECT must be 'before' or 'after'")+DOWNLOAD_ONLY = os.environ.get("PW_DOWNLOAD_ONLY", "0") == "1"CHECKPOINT_CACHED = os.environ.get("PW_CHECKPOINT_CACHED", "1").strip() != "0"if EXPECT == "before" and not CHECKPOINT_CACHED:raise ValueError("The before-state requires PW_CHECKPOINT_CACHED=1")@@ -87,14 +89,30 @@ def _entry(repo_id: str) -> dict[str, object]:def _open_quant(page, *, navigate: bool) -> None:if navigate:page.goto(f"{BASE_URL}/images", wait_until = "domcontentloaded")- trigger = page.get_by_role("button", name = "Select image model")+ trigger = page.locator(".unsloth-model-selector-trigger:visible")trigger.wait_for(state = "visible", timeout = 30_000)+ trigger.scroll_into_view_if_needed()+ # Finish input scrolling before opening the dismiss-on-scroll picker.+ page.evaluate("""async () => {+ const scrollers = [...document.querySelectorAll('*')]+ .filter(el => el.scrollHeight > el.clientHeight);+ let last = '', stable = 0;+ await new Promise(resolve => {+ function frame() {+ const positions = scrollers.map(el => el.scrollTop).join(',');+ stable = positions === last ? stable + 1 : 0;+ last = positions;+ if (stable >= 8) resolve(); else requestAnimationFrame(frame);+ }+ requestAnimationFrame(frame);+ });+ }""")trigger.click()klein_row(page).click()gguf = page.get_by_text("GGUF", exact = True)if gguf.count() == 1:gguf.click()- quant = page.locator("button").filter(has_text = "Q4_K_M")+ quant = page.locator("button[data-model-picker-option]").filter(has_text = "Q4_K_M")quant.wait_for(state = "visible")assert quant.count() == 1quant.click()@@ -110,10 +128,13 @@ def main() -> None:"load_calls": 0,"load_payloads": [],"load_progress_polls": 0,- "loaded": False,+ "loaded": DOWNLOAD_ONLY,"plan_snapshots": [],}page_errors: list[str] = []+ unload_calls = []+ held_plans = []+ hold_plan = DOWNLOAD_ONLYdef download_plan() -> dict[str, object]:entries = [_entry(COMPANION_REPO)]@@ -188,7 +209,11 @@ def main() -> None:}with sync_playwright() as playwright:- browser = playwright.chromium.launch(headless = True)+ engine = getattr(playwright, os.environ.get("PW_BROWSER", "chromium"))+ executable = os.environ.get("PW_EXECUTABLE")+ browser = engine.launch(+ headless = True, **({"executable_path": executable} if executable else {})+ )context = browser.new_context(viewport = {"width": 1440, "height": 900},reduced_motion = "reduce",@@ -220,6 +245,9 @@ def main() -> None:_json(route, variants)returnif path == "/api/inference/images/download-plan":+ if hold_plan:+ held_plans.append(route)+ return_json(route, download_plan())returnif path == "/api/studio/download-transport-capabilities":@@ -261,6 +289,11 @@ def main() -> None:if path in {"/api/hub/gguf-download-progress", "/api/hub/download-progress"}:_json(route, job_progress(query["repo_id"][0]))return+ if path == "/api/inference/images/unload" and request.method == "POST":+ unload_calls.append(payload)+ state["loaded"] = False+ _json(route, _status(loaded = False))+ returnif path == "/api/inference/images/load" and request.method == "POST":state["load_calls"] = int(state["load_calls"]) + 1state["load_payloads"].append(payload)@@ -313,7 +346,31 @@ def main() -> None:page = context.new_page()page.on("pageerror", lambda exc: page_errors.append(str(exc)))- _open_quant(page, navigate = True)+ if DOWNLOAD_ONLY:+ page.goto(f"{BASE_URL}/images", wait_until = "domcontentloaded")+ page.get_by_role("button", name = "Advanced", exact = True).click()+ page.get_by_role("combobox", name = "On model selection").click()+ page.get_by_role("option", name = "Download only", exact = True).click()+ page.get_by_role("textbox", name = "Steps", exact = True).fill("17")+ page.get_by_role("textbox", name = "Guidance", exact = True).fill("2.5")+ _open_quant(page, navigate = not DOWNLOAD_ONLY)+ if DOWNLOAD_ONLY:+ with page.expect_request(+ lambda request: urlparse(request.url).path == "/api/inference/images/unload"+ ):+ page.locator("[data-eject-hit]:visible").click()+ expect(page.get_by_role("button", name = "Select image model")).to_be_visible()+ page.get_by_test_id("nav-row-hub").click()+ # The path, not the whole URL: the Hub appends its own ?tab= once it has mounted, and an+ # exact-URL assertion loses that race on every CI runner.+ expect(page).to_have_url(re.compile(r"/hub(\?|$)"))+ assert held_plans, "No pending plan to exercise"+ hold_plan = False+ for route in held_plans:+ _json(route, download_plan())+ held_plans.clear()+ page.get_by_test_id("nav-row-images").click()+ expect(page).to_have_url(re.compile(r"/images(\?|$)"))if EXPECT == "before":deadline = time.monotonic() + 20while int(state["load_calls"]) < 1 and time.monotonic() < deadline:@@ -379,6 +436,21 @@ def main() -> None:assert state["load_calls"] == 0, "cancelled staging unexpectedly loaded the model"_open_quant(page, navigate = False)+ if DOWNLOAD_ONLY:+ page.locator(".hub-download-panel li").filter(has_text = COMPANION_REPO).get_by_text(+ "Downloaded", exact = True+ ).wait_for(timeout = 20_000)+ assert state["starts"] == [*expected_initial_starts, COMPANION_REPO], state["starts"]+ assert state["load_calls"] == 0, "download-only completion loaded the model"+ assert state["loaded"] is False and len(unload_calls) == 1+ expect(page.get_by_role("textbox", name = "Steps", exact = True)).to_have_value("17")+ expect(page.get_by_role("textbox", name = "Guidance", exact = True)).to_have_value("2.5")+ assert not page_errors, page_errors+ browser.close()+ print(+ "PASS download-only cancel, retry and completion preserve the generation settings"+ )+ returnpage.locator("[data-sonner-toast]").filter(has_text = "Loading to GPU").wait_for(state = "visible", timeout = 20_000)diff --git a/tests/studio/playwright_image_download_queue.py b/tests/studio/playwright_image_download_queue.pynew file mode 100644index 00000000000..abb679e5142--- /dev/null+++ b/tests/studio/playwright_image_download_queue.py@@ -0,0 +1,264 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Keep a download-only plan when another selection arrives mid-checkpoint.++Uses the rendered UI with deterministic API responses; no model bytes or GPU.+PW_LOAD_SECOND=1 also checks loading the same model after its queued download.+PW_HOLD_FIRST_PLAN=1 delays the first plan until the second selection has staged.+PW_RESOLVE_FIRST=1 delays the first selection's GGUF filename lookup.+PW_DIFFERENT_QUANT=1 selects another quant with PW_LOAD_SECOND=1.+"""++import json+import os+import time+from pathlib import Path+from urllib.parse import parse_qs, urlparse++from playwright.sync_api import sync_playwright++from playwright_image_model_footprint import (+ BASE_URL,+ REPO_ID,+ FILENAME,+ _api_payload,+ _json,+ klein_row,+)+from playwright_image_download_cancel_retry import _open_quant++LOAD_SECOND = os.environ.get("PW_LOAD_SECOND", "0") == "1"+HOLD_FIRST_PLAN = os.environ.get("PW_HOLD_FIRST_PLAN", "0") == "1"+RESOLVE_FIRST = os.environ.get("PW_RESOLVE_FIRST", "0") == "1"+DIFFERENT_QUANT = os.environ.get("PW_DIFFERENT_QUANT", "0") == "1"+SECOND_FILENAME = FILENAME.replace("Q4_K_M", "Q8_0")+SECOND = REPO_ID if LOAD_SECOND else "Tongyi-MAI/Z-Image-Turbo"+COMPANION = "black-forest-labs/FLUX.2-klein-4B"+ART = Path(os.environ.get("PW_ART_DIR", "logs/playwright_image_download_queue"))+ART.mkdir(parents = True, exist_ok = True)+++def main() -> None:+ state = {"jobs": {}, "starts": [], "calls": [], "plans": [], "release": False, "files": []}+ errors = []+ held_plans = []+ held_listings = []+ hold_plans = HOLD_FIRST_PLAN++ def plan(repo, filename = None):+ entries = [+ {+ "repo_id": repo,+ "files": [filename or FILENAME]+ if repo == REPO_ID+ else ["transformer/model.safetensors"],+ "bytes": 1024,+ "checkpoint": True,+ }+ ]+ if repo == REPO_ID:+ entries.append(+ {+ "repo_id": COMPANION,+ "files": ["vae/model.safetensors"],+ "bytes": 2048,+ "checkpoint": False,+ }+ )+ return {"entries": entries, "total_bytes": sum(e["bytes"] for e in entries)}++ with sync_playwright() as p:+ engine = getattr(p, os.environ.get("PW_BROWSER", "chromium"))+ executable = os.environ.get("PW_EXECUTABLE")+ browser = engine.launch(+ headless = True, **({"executable_path": executable} if executable else {})+ )+ context = browser.new_context(+ viewport = {"width": 1440, "height": 1000}, reduced_motion = "reduce"+ )+ context.add_init_script(+ "localStorage.setItem('unsloth_auth_token','rendered-ui-test');localStorage.setItem('unsloth_download_transport','http')"+ )++ def route(r):+ path = urlparse(r.request.url).path+ query = parse_qs(urlparse(r.request.url).query)+ if not path.startswith("/api/"):+ if urlparse(r.request.url).hostname in ("127.0.0.1", "localhost"):+ r.continue_()+ else:+ _json(r, [])+ return+ payload = json.loads(r.request.post_data or "{}")+ repo = payload.get("repo_id") or query.get("repo_id", [None])[0]+ if path == "/api/inference/images/download-plan":+ selected = payload["model_path"]+ state["plans"].append(selected)+ result = plan(selected, payload.get("gguf_filename"))+ if hold_plans:+ held_plans.append((r, result))+ else:+ _json(r, result)+ elif path == "/api/studio/download-transport-capabilities":+ _json(+ r,+ {+ "http": {"available": True},+ "xet": {"available": False},+ "auto_resolves_to": "http",+ },+ )+ elif path == "/api/hub/transport-status":+ _json(r, {"has_partial": False, "last_transport": None, "resumable": False})+ elif path == "/api/hub/download" and r.request.method == "POST":+ assert payload["scope_id"] == "diffusion", payload+ state["starts"].append(repo)+ state["files"].append(payload.get("files", []))+ job = {"state": "running", "generation": len(state["starts"]), "polls": 0}+ state["jobs"][repo] = job+ _json(+ r,+ {+ **job,+ "accepted": True,+ "job_key": f"model:{repo}:@diffusion",+ "transport": "http",+ },+ )+ elif path == "/api/hub/download-status":+ job = state["jobs"].get(repo, {"state": "idle"})+ if job["state"] == "running" and state["release"]:+ job["polls"] += 1+ if job["polls"] >= 2:+ job["state"] = "complete"+ _json(r, {**job, "error": None})+ elif path in ("/api/hub/download-progress", "/api/hub/gguf-download-progress"):+ complete = state["jobs"].get(repo, {}).get("state") == "complete"+ size = 2048 if repo == COMPANION else 1024+ _json(+ r,+ {+ "downloaded_bytes": size if complete else 256,+ "completed_bytes": size if complete else 256,+ "complete_on_disk": complete,+ "expected_bytes": size,+ "progress": 1 if complete else 0.25,+ "cache_path": "C:\\mock-cache",+ },+ )+ elif path in ("/api/inference/images/load", "/api/inference/images/unload"):+ state["calls"].append(path)+ _json(r, _api_payload("/api/inference/images/status", {}, full_footprint = True))+ else:+ result = _api_payload(path, query, full_footprint = True)+ if path in ("/api/hub/gguf-variants", "/api/models/gguf-variants"):+ result["variants"][0]["downloaded"] = False+ if DIFFERENT_QUANT:+ result["variants"].append(+ {**result["variants"][0], "filename": SECOND_FILENAME, "quant": "Q8_0"}+ )+ if RESOLVE_FIRST:+ held_listings.append((r, result))+ return+ _json(r, result)++ context.route("**/*", route)+ page = context.new_page()+ page.on("pageerror", lambda e: errors.append(str(e)))++ def wait_for(predicate):+ deadline = time.monotonic() + 15+ while not predicate() and time.monotonic() < deadline:+ page.wait_for_timeout(100)+ assert predicate(), state++ page.goto(BASE_URL + "/images", wait_until = "domcontentloaded")+ page.get_by_role("button", name = "Advanced", exact = True).click()+ page.get_by_role("combobox", name = "On model selection").click()+ page.get_by_role("option", name = "Download only", exact = True).click()+ page.get_by_role("button", name = "Advanced", exact = True).click()+ if RESOLVE_FIRST:+ page.evaluate(+ """url => {+ history.pushState(null, '', url);+ dispatchEvent(new PopStateEvent('popstate'));+ }""",+ f"/images?model={REPO_ID}&ggufQuant=Q4_K_M",+ )+ wait_for(lambda: len(held_listings) > 0)+ else:+ _open_quant(page, navigate = False)+ if RESOLVE_FIRST:+ assert not state["starts"]+ elif HOLD_FIRST_PLAN:+ wait_for(lambda: state["plans"].count(REPO_ID) >= 2)+ else:+ wait_for(lambda: REPO_ID in state["starts"])+ hold_plans = False+ plan_count = len(state["plans"])+ if LOAD_SECOND:+ page.get_by_role("button", name = "Advanced", exact = True).click()+ page.get_by_role("combobox", name = "On model selection").click()+ page.get_by_role("option", name = "Download and load", exact = True).click()+ page.get_by_role("button", name = "Advanced", exact = True).click()+ if DIFFERENT_QUANT:+ trigger = page.locator(".unsloth-model-selector-trigger:visible")+ trigger.scroll_into_view_if_needed()+ trigger.click()+ klein_row(page).click()+ gguf = page.get_by_text("GGUF", exact = True)+ if gguf.count() == 1:+ gguf.click()+ page.locator("button[data-model-picker-option]").filter(has_text = "Q8_0").click()+ else:+ _open_quant(page, navigate = False)+ else:+ trigger = page.locator(".unsloth-model-selector-trigger:visible")+ trigger.scroll_into_view_if_needed()+ trigger.click()+ page.locator(".unsloth-model-selector-menu [data-model-picker-option]").filter(+ has_text = "Z-Image-Turbo"+ ).filter(has_text = "BF16").first.click()+ wait_for(lambda: len(state["plans"]) > plan_count and SECOND in state["plans"])+ page.wait_for_timeout(300)+ assert state["starts"] == [SECOND if HOLD_FIRST_PLAN or RESOLVE_FIRST else REPO_ID], state+ for route, result in held_listings:+ _json(route, result)+ held_listings.clear()+ for route, result in held_plans:+ _json(route, result)+ held_plans.clear()+ page.wait_for_timeout(300)+ state["release"] = True+ expected = [REPO_ID, COMPANION] if LOAD_SECOND else [REPO_ID, COMPANION, SECOND]+ if (HOLD_FIRST_PLAN or RESOLVE_FIRST) and not LOAD_SECOND:+ expected = [SECOND, REPO_ID, COMPANION]+ try:+ wait_for(+ lambda: len(state["starts"]) >= len(expected)+ and all(j["state"] == "complete" for j in state["jobs"].values())+ )+ if LOAD_SECOND:+ wait_for(lambda: len(state["calls"]) > 0)+ assert state["starts"] == expected * 2, state+ assert all(job["state"] == "complete" for job in state["jobs"].values()), state+ else:+ assert state["starts"] == expected, state+ expected_calls = ["/api/inference/images/load"] if LOAD_SECOND else []+ assert state["calls"] == expected_calls, state+ if DIFFERENT_QUANT:+ assert [FILENAME] in state["files"], state+ assert [SECOND_FILENAME] in state["files"], state+ assert not errors, errors+ finally:+ (ART / "result.json").write_text(+ json.dumps({**state, "page_errors": errors}, indent = 2), encoding = "utf-8"+ )+ page.screenshot(path = str(ART / "queue.png"), full_page = True)+ browser.close()+ print(f'PASS download-only queue: {state["starts"]}', flush = True)+++if __name__ == "__main__":+ main()diff --git a/tests/studio/test_model_picker_contracts.py b/tests/studio/test_model_picker_contracts.pyindex 512777f5baf..77d53fc74d3 100644--- a/tests/studio/test_model_picker_contracts.py+++ b/tests/studio/test_model_picker_contracts.py@@ -1552,9 +1552,14 @@ def test_a_hidden_diffusion_page_does_not_load_when_its_download_lands():src = _read(rel)ready = re.search(r"onReady: \(\) => \{.*?\n \},", src, re.S)assert ready, f"{rel}: staged-download onReady not found"- assert "if (!active)" in ready.group(0), f"{rel}: a hidden page still takes the GPU"+ region = ready.group(0)+ if "resumePendingLoad();" in region:+ resume = re.search(r"function resumePendingLoad\(\) \{.*?\n \}", src, re.S)+ assert resume, f"{rel}: staged-load continuation not found"+ region += resume.group(0)+ assert "if (!active)" in region, f"{rel}: a hidden page still takes the GPU"# Deferred, not dropped: something has to fire the held pick when the page returns.- assert "stagedLoadDeferred" in ready.group(0), f"{rel}: the pick is discarded"+ assert "stagedLoadDeferred" in region, f"{rel}: the pick is discarded"# The deps array grew when the load body moved into runStagedLoad, so match the# effect by its guard and check the deps separately. Keying the boundary on# `[active` instead lets a reordered array run the match on into the next hook,@@ -1606,7 +1611,12 @@ def test_a_dying_staged_download_only_rolls_back_its_own_pick():for rel in ("features/images/images-page.tsx", "features/video/video-page.tsx"):src = _read(rel)# Captured before the plan await, otherwise it is the newer pick's entry that gets stored.- own = re.search(r"const ownRevert = quantRevert\.current;\n(.*?)await ", src, re.S)+ own = re.search(+ r"const ownRevert = (?:downloadSnapshot(?: \|\| downloadOnly)? \? null : )?"+ r"quantRevert\.current;\n(.*?)await ",+ src,+ re.S,+ )assert own, f"{rel}: loadOrStage does not capture its own rollback entry"assert "await" not in own.group(1@@ -1633,7 +1643,7 @@ def test_a_plan_that_lands_after_a_newer_pick_is_dropped():first plan is still in flight. Plans then resolve in RESPONSE order, not pick order: the olderone would restage over the newer queue, or fall through and load the model the user left.- So each pick takes a sequence number and gives up if a newer one has been made since. It must+ Each load pick takes a sequence number and gives up if a newer one has been made since. It mustreport started, not failed: returning false would send this pick's `.then` rollback at a labelthe newer pick now owns. Every exit that acts on the pick is covered, not just the one after asuccessful plan -- a rejected plan falls through to the load, and a pick that never asks for a@@ -1643,9 +1653,14 @@ def test_a_plan_that_lands_after_a_newer_pick_is_dropped():body = re.search(r"const loadOrStage = useCallback\(\n(.*?)\n \);", src, re.S)assert body, f"{rel}: loadOrStage not found"text = body.group(1)- assert "const pick = ++pickSeq.current;" in text, f"{rel}: no pick sequence is taken"+ sequence = re.search(+ r"const pick = (?:(?:downloadSnapshot|downloadOnly) \? pickSeq\.current : )?"+ r"\+\+pickSeq\.current;",+ text,+ )+ assert sequence, f"{rel}: no pick sequence is taken"# Before any real await, or two picks can share a number.- seq = text.index("const pick = ++pickSeq.current;")+ seq = sequence.start()first_await = min((text.index(tok)@@ -1657,19 +1672,20 @@ def test_a_plan_that_lands_after_a_newer_pick_is_dropped():assert seq < first_await, f"{rel}: the sequence is taken after the plan await"# Before the non-hub return, so a local pick invalidates an in-flight hub plan.assert seq < text.index(- 'if (source !== "hub")'+ 'if (source !== "hub"'), f"{rel}: a non-hub pick returns without invalidating an in-flight hub plan"guards = re.findall(- r"if \(pick !== pickSeq\.current(?: \|\| !owns\(\))?\) return (\w+);", text+ r"if \((?:!downloadOnly && \()?pick !== pickSeq\.current(?: \|\| !owns\(\))?\){1,2} return (\w+);",+ text,)assert guards, f"{rel}: a superseded plan is not dropped"assert (set(guards) == {"true"}), f"{rel}: a superseded pick reports failure, so its rollback fires at the newer pick's label"# The fallback load after a rejected plan is guarded too.- tail = text[text.rindex("} catch {") :]+ tail = text[text.rindex("} catch") :]assert re.search(- r"if \(pick !== pickSeq\.current(?: \|\| !owns\(\))?\) return true;.*?return handleLoadRef",+ r"if \((?:!downloadOnly && \()?pick !== pickSeq\.current(?: \|\| !owns\(\))?\){1,2} return true;.*?return handleLoadRef",tail,re.S,), f"{rel}: a plan that rejected after a newer pick still reaches the fallback load"@@ -1805,11 +1821,11 @@ def test_a_new_pick_drops_the_previous_staged_intent():text = body.group(1)cleared = text.index("pendingStagedLoad.current = null;")assert cleared < text.index(- 'if (source !== "hub")'+ 'if (source !== "hub"'), f"{rel}: a non-hub pick returns while the previous staged intent is still armed"assert cleared < text.index("await "), f"{rel}: the intent survives until the plan resolves"# The deferred re-fire and the rollback owner belong to that dead intent too.- head = text[: text.index('if (source !== "hub")')]+ head = text[: text.index('if (source !== "hub"')]assert ("stagedLoadDeferred.current = false;" in head), f"{rel}: a deferred staged load can still fire for the abandoned pick"@@ -3778,7 +3794,7 @@ def test_a_refused_load_after_staging_rolls_the_pick_back():the same bug."""for page in ("features/images/images-page.tsx", "features/video/video-page.tsx"):src = _read(page)- helper = src.split("const runStagedLoad = useCallback(", 1)[1].split("[revertPick],", 1)[0]+ helper = src.split("const runStagedLoad = useCallback(", 1)[1].split("\n );", 1)[0]# Fire-and-forget is precisely the defect: the boolean has to be observed.assert ".then((started) => {" in helper, pageassert "if (started) return;" in helper, page@@ -3787,8 +3803,21 @@ def test_a_refused_load_after_staging_rolls_the_pick_back():assert "const owned = stagedQuantRevert.current;" in helper, pageassert "quantRevert.current === owned" in helper, pageassert "revertPick(quantRevert.current);" in helper, page- # One implementation, reached from both deferred paths, so neither can drift.- assert src.count("if (pending) runStagedLoad(pending);") == 2, page+ # Both visible and deferred loads must use the rollback helper.+ ready = re.search(r"onReady: \(\) => \{.*?\n \},", src, re.S)+ assert ready, page+ continuation = ready.group(0)+ if "resumePendingLoad();" in continuation:+ resume = re.search(r"function resumePendingLoad\(\) \{.*?\n \}", src, re.S)+ assert resume, page+ continuation = resume.group(0)+ assert "runStagedLoad(pending);" in continuation, page+ deferred = re.search(+ r"if \(!active \|\| !stagedLoadDeferred\.current\) return;.*?\n \}, \[[^\]]*\]\);",+ src,+ re.S,+ )+ assert deferred and "runStagedLoad(pending);" in deferred.group(0), page# Exactly one direct call left, the one inside the helper itself.assert len(re.findall(r"void handleLoadRef\s*\.current\(\s*pending\.", src)) == 1, page@@ -3872,3 +3901,153 @@ def test_the_media_gpu_pick_survives_a_reload():assert "gpuChoices.some((d) => String(d.index) === selectedGpu)" in src or ("controls.gpuChoices.some((d) => String(d.index) === controls.selectedGpu)" in src), page+++def test_a_download_only_pick_does_not_strand_a_staged_load():+ """Download only fetches files. It must not take the page from a load that is already staging.++ Both pick routes used to retire the staged intent unconditionally: `handleModelSelect` called+ `beginPick()` plus `pickGuard.claim()` before it looked at the mode, and `loadGgufRepoPick` did+ the same, so picking a second model in Download only mode left the first one downloaded in full+ and never loaded, with no toast and nothing to retry from. `loadOrStage` cleared the same refs a+ second time on its way in.++ So: the mode is read first, and a download-only pick claims nothing and clears nothing."""+ src = _read("features/images/images-page.tsx")+ select = re.search(r"const handleModelSelect = useCallback\(\n(.*?)\n \);", src, re.S)+ assert select, "handleModelSelect not found"+ pick = select.group(1)+ mode = re.search(r'const (\w+) = modelSelectionAction === "download";', pick)+ assert mode, "handleModelSelect does not read the selection mode before branching"+ flag = mode.group(1)+ assert pick.index(mode.group(0)) < pick.index(+ "beginPick();"+ ), "the mode is read after the staged intent has already been retired"+ assert (+ f"if (!{flag}) beginPick();" in pick+ ), "a download-only pick still retires the staged load"+ assert re.search(+ rf"const token = {flag} \? undefined : pickGuard\.claim\(\);", pick+ ), "a download-only pick still claims the page, which makes the staged load's token stale"++ repo_pick = re.search(r"const loadGgufRepoPick = useCallback\(\n(.*?)\n \);", src, re.S)+ assert repo_pick, "loadGgufRepoPick not found"+ repo = repo_pick.group(1)+ assert (+ "beginPick();" not in repo+ ), "the repo-level download-only pick still retires the staged load"+ assert re.search(+ r"const token = downloadOnly \? 0 : pickGuard\.claim\(\);", repo+ ), "the repo-level download-only pick still claims the page"++ stage_fn = re.search(r"const loadOrStage = useCallback\(\n(.*?)\n \);", src, re.S)+ assert stage_fn, "loadOrStage not found"+ body = stage_fn.group(1)+ clearing = re.search(r"if \(([^)]*)\) \{\n\s*pendingStagedLoad\.current = null;", body)+ assert clearing, "loadOrStage no longer has the staged-intent clearing block"+ assert "!downloadOnly" in clearing.group(+ 1+ ), "loadOrStage still clears the staged load intent for a download-only pick"+++def test_every_optimistic_pick_hands_its_label_back_under_a_guard():+ """`quantRevert` is one slot. A pick that no longer owns the page must not revert over the label+ a newer pick has already set, so every `!started` rollback is guarded. Two branches lost that+ guard when they moved from `handleLoad` to `loadOrStage`."""+ src = _read("features/images/images-page.tsx")+ start = src.index("const handleModelSelect = useCallback(")+ # Bounded at the next top-level callback: handleDeployAdapter rolls back a deploy, not a pick.+ pick = src[start : src.index("const handleDeployAdapter", start)]+ rollbacks = re.findall(r"if \(!started(.*?)\) \{\n\s*revertPick\(", pick, re.S)+ assert rollbacks, "no optimistic rollback found; this guard has gone stale"+ for tail in rollbacks:+ assert (+ "stillOwnsPick()" in tail+ ), "an optimistic pick reverts its label without checking it still owns the page"+++def test_a_repeated_download_only_pick_queues_one_download():+ """Two picks of the same model planned the same files twice and downloaded every byte twice;+ the second start could also come back "busy" against the first and be dropped silently."""+ src = " ".join(_read("features/images/images-page.tsx").split())+ assert (+ "if (queuedDownloadKeys().has(planKey(entries))) return true;" in src+ ), "download-only plans are queued without checking what is already queued"+ assert "function planKey(entries: StagedDownloadEntry[])" in src+++def test_a_download_only_pick_does_not_retire_the_pick_sequence():+ """`pickSeq` is how a load pick tells a NEWER load pick from itself. A Download only pick is+ neither: it fetches files and takes over nothing. Advancing the sequence for one made the+ ordinary selection that was still awaiting its plan fail its own stale check and return+ silently, leaving that model neither staged nor loaded and nothing on screen to say so."""+ src = _read("features/images/images-page.tsx")+ body = re.search(r"const loadOrStage = useCallback\(\n(.*?)\n \);", src, re.S)+ assert body, "loadOrStage not found"+ text = body.group(1)+ assert "const pick = downloadOnly ? pickSeq.current : ++pickSeq.current;" in text+ # The flag has to be decided first, or the ternary reads an undefined binding.+ assert text.index("const downloadOnly =") < text.index("const pick =")+++def test_a_download_only_pick_claims_no_label_rollback():+ """`quantRevert` is ONE slot and a staged load in flight owns what is in it: that entry is the+ baseline it restores on failure and commits on success. A Download only pick used to take the+ slot for an optimistic label it then reverted, which restored the PREVIOUS resident's quant and+ recipe underneath a load that was still coming and left it nothing to commit. So it installs no+ label at all, and reads no rollback out of the slot."""+ src = _read("features/images/images-page.tsx")+ start = src.index("const handleModelSelect = useCallback(")+ pick = src[start : src.index("const handleDeployAdapter", start)]+ installs = re.findall(r"const revert: PickRevert(.*?);\n", pick, re.S)+ assert installs, "no optimistic label install found; this guard has gone stale"+ for tail in installs:+ assert "downloadOnlyPick" in tail, "a download-only pick installs an optimistic label"+ assert "const ownRevert = downloadSnapshot || downloadOnly ? null : quantRevert.current;" in src+++def test_a_routed_download_only_arrival_claims_nothing():+ """A ?model= arrival from the chat picker or the Hub takes the page like a direct pick. Under+ Download only it must not: claiming there revokes the token of a load that is already staging,+ and resumePendingLoad then drops that load once its files have finished arriving."""+ src = _read("features/images/images-page.tsx")+ body = re.search(r"const handledRouteModel = useRef(.*?)\n \]\);", src, re.S)+ assert body, "the routed-pick effect was not found; this guard has gone stale"+ text = body.group(1)+ assert 'const downloadOnlyPick = modelSelectionAction === "download";' in text+ assert "const token = downloadOnlyPick ? undefined : pickGuard.claim();" in text+ # And no optimistic label either: quantRevert is the staged load's slot, not this arrival's.+ assert "const revert: PickRevert | null = downloadOnlyPick" in text+++def test_a_refused_download_only_pick_leaves_the_staged_rollback_alone():+ """abandonPick() reverts and clears quantRevert. A Download only pick refused for being an+ unsupported repo never claimed the page, so what it would clear is the staged load's own+ baseline: that load would then resume with the previous resident's steps and guidance and have+ nothing left to commit."""+ src = " ".join(_read("features/images/images-page.tsx").split())+ assert "if (!downloadOnlyPick) abandonPick();" in src+++def test_an_unresolvable_download_only_gguf_hands_nothing_back():+ """A GGUF repo whose filename cannot be resolved (several quants and no hint, or a failed+ listing) reaches onNotStarted. Under Download only nothing was applied, so what sits in+ quantRevert is the staged load's own baseline: reverting it would load that model with the+ previous resident's steps and guidance and leave it nothing to commit."""+ src = _read("features/images/images-page.tsx")+ body = re.search(r"onNotStarted: \(\) => \{\n(.*?)\n \},", src, re.S)+ assert body, "the not-started callback was not found; this guard has gone stale"+ assert "!downloadOnly &&" in body.group(1)+++def test_a_download_only_pick_is_allowed_while_the_page_is_busy():+ """The busy guard exists because the backend 409s a second load. A Download only pick submits+ no load, and the selector stays interactive during a generation, so refusing it there was a+ silent dead click: the user picked a model to download and nothing happened."""+ src = _read("features/images/images-page.tsx")+ body = re.search(r"const handleModelSelect = useCallback\(\n(.*?)\n \);", src, re.S)+ assert body, "handleModelSelect not found"+ text = body.group(1)+ assert "if (busy !== null && !downloadOnlyPick) return;" in text+ # Decided before the guard, or the guard reads an undefined binding.+ assert text.index("const downloadOnlyPick =") < text.index("if (busy !== null")