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.

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.yml
index 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_retry
python 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_cold
python 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_footprint
logs/playwright_image_cancel_retry
logs/playwright_image_cancel_retry_cold
+ logs/playwright_image_download_queue
logs/playwright_image_text_encoder
logs/playwright_modelcfg
logs/playwright_memory_estimate
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 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 dense
shards, 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 None
except Exception as exc: # noqa: BLE001 -- an unsizable prequant must not fail the plan
logger.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_probe
else None
)
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 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.py
index 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(monkey
def 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_mod
backend = _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.py
index 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, m
assert "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_failed
assert [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 False
assert 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(cl
resp = client.post("/api/inference/images/download-plan", json = {**body, "gpu_ids": [7]})
assert resp.status_code == 400
assert "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.ts
index 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.tsx
index 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"],
+ ]}
+ />
<AdvancedSelect
label="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.py
index 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 json
import os
+import re
import time
from pathlib import Path
from urllib.parse import parse_qs, urlparse
-from playwright.sync_api import Route, sync_playwright
+from playwright.sync_api import Route, expect, sync_playwright
from 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() == 1
quant.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_ONLY
def 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)
return
if path == "/api/inference/images/download-plan":
+ if hold_plan:
+ held_plans.append(route)
+ return
_json(route, download_plan())
return
if 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))
+ return
if path == "/api/inference/images/load" and request.method == "POST":
state["load_calls"] = int(state["load_calls"]) + 1
state["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() + 20
while 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"
+ )
+ return
page.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.py
new file mode 100644
index 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.py
index 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 older
one 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 must
report started, not failed: returning false would send this pick's `.then` rollback at a label
the newer pick now owns. Every exit that acts on the pick is covered, not just the one after a
successful 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, page
assert "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, page
assert "quantRevert.current === owned" in helper, page
assert "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")