Skip to content

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

Unsloth Studio / Desktop: colour a companion download's bar by model, text encoder and VAE (#13112)

Leo Borcherdingeb84cce811f5
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index b227937e150..dbb28739b9b 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -5081,6 +5081,9 @@ class DiffusionBackend:
entry["bytes"] += int(
sum(declared_sizes.get(n, 0) for n in newly_missing if n not in reusable)
)
+ entry["file_bytes"].update(
+ {n: int(declared_sizes.get(n, 0)) for n in newly_missing if n not in reusable}
+ )
entry["gguf_filename"] = scoped_gguf[repo]
entry["checkpoint"] = repo in missing_checkpoints
return
@@ -5094,6 +5097,11 @@ class DiffusionBackend:
"bytes": int(
sum(declared_sizes.get(name, 0) for name in missing if name not in reusable)
),
+ "file_bytes": {
+ name: int(declared_sizes.get(name, 0))
+ for name in missing
+ if name not in reusable
+ },
"gguf_filename": scoped_gguf[repo],
"checkpoint": repo in missing_checkpoints,
}
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 429c78cc231..f27257f8851 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -5254,6 +5254,7 @@ class VideoBackend:
"repo_id": repo,
"files": names,
"bytes": sum(size for _name, size in staged),
+ "file_bytes": {name: int(size) for name, size in staged},
"gguf_filename": gguf,
# Describes the ENTRY, not the pick: a 2.3 repo whose checkpoint is already cached stages companion
# files only, and calling that "Model file" misdescribes what is downloading. A pipeline pick has no
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index ae7576ce47b..dd4efddca6f 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -5122,6 +5122,11 @@ class DiffusionDownloadPlanEntry(BaseModel):
bytes: int = Field(
0, description = "Declared size of the files still missing from cache, 0 when unknown"
)
+ file_bytes: Dict[str, int] = Field(
+ default_factory = dict,
+ description = "Declared size of each file counted in ``bytes``. Empty from a planner that "
+ "does not break it down; the download panel then shows one bar.",
+ )
gguf_filename: Optional[str] = Field(
None, description = "Set when this entry is the single-file GGUF checkpoint"
)
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 464fc46a6f9..965b0b0647c 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -8695,6 +8695,21 @@ def test_download_plan_omits_a_cached_gguf_but_keeps_missing_companions(monkeypa
assert plan["checkpoint_bytes"] == 7 * GB
+def test_download_plan_sizes_each_file_it_counts(monkeypatch):
+ """The download panel colours the bar by what each file is, so the plan breaks ``bytes`` down."""
+ _fake_flux_hub(monkeypatch)
+ _no_cache(monkeypatch)
+
+ plan = _flux_download_plan()
+
+ for entry in plan["entries"]:
+ assert entry["file_bytes"], entry["repo_id"]
+ assert set(entry["file_bytes"]) <= set(entry["files"])
+ assert sum(entry["file_bytes"].values()) == entry["bytes"]
+ checkpoint = next(e for e in plan["entries"] if e["checkpoint"])
+ assert checkpoint["file_bytes"] == {"flux1-dev-Q4_K_M.gguf": 7 * GB}
+
+
def test_download_plan_stages_but_does_not_count_a_file_an_older_snapshot_holds(monkeypatch):
"""README-only commit on a no-symlink cache: the GGUF is still staged but counts no bytes."""
_fake_flux_hub(monkeypatch)
@@ -8713,6 +8728,7 @@ def test_download_plan_stages_but_does_not_count_a_file_an_older_snapshot_holds(
assert checkpoint["repo_id"] == "unsloth/FLUX.1-dev-GGUF"
assert checkpoint["files"] == ["flux1-dev-Q4_K_M.gguf"]
assert checkpoint["bytes"] == 0
+ assert checkpoint["file_bytes"] == {}
assert checkpoint["checkpoint"] is True
assert base["bytes"] > 0
assert plan["total_bytes"] == base["bytes"]
diff --git a/studio/frontend/src/features/hub/catalog/use-required-assets-download.tsx b/studio/frontend/src/features/hub/catalog/use-required-assets-download.tsx
index ff601c72910..1479e84a9ad 100644
--- a/studio/frontend/src/features/hub/catalog/use-required-assets-download.tsx
+++ b/studio/frontend/src/features/hub/catalog/use-required-assets-download.tsx
@@ -13,9 +13,11 @@ import { useInventoryVersion } from "../stores/inventory-events";
import { useHfTokenStore } from "../stores/hf-token-store";
import {
additionalAssetDownloads,
+ checkpointFirst,
selectDownloadEntries,
} from "../download-manager/required-assets";
import { RequiredAssetsDownloadDialog } from "../download-manager/required-assets-dialog";
+import { withPlanBreakdown } from "../download-manager/download-breakdown";
import { enqueueHubDownload } from "../download-manager/use-hub-download-queue";
import type { StagedDownloadEntry } from "../download-manager/use-staged-download";
export type AssetRuntime = "images" | "video" | "audio";
@@ -37,6 +39,7 @@ export function useRequiredAssetsDownload({
const inventoryVersion = useInventoryVersion();
const sequence = useRef(0);
const starting = useRef(false);
+ const checkpointBytes = useRef<number | undefined>(undefined);
const fetchPlan = useCallback(async () => {
const body = {
model_path: repoId,
@@ -102,6 +105,15 @@ export function useRequiredAssetsDownload({
++sequence.current;
};
}, [fetchPlan, runtime]);
+ // The queue runs the checkpoint first and drops unticked assets, so each job's earlier and later
+ // parts are sized from that final list, not from the plan's order.
+ const enqueuePlan = (entries: StagedDownloadEntry[]) => {
+ if (!entries.length) return;
+ enqueueHubDownload(
+ withPlanBreakdown(checkpointFirst(entries), checkpointBytes.current),
+ { repoId, filename },
+ );
+ };
const request = async (fallback: () => void) => {
if (!runtime) {
fallback();
@@ -118,14 +130,15 @@ export function useRequiredAssetsDownload({
repoId: e.repo_id,
files: e.files,
bytes: e.bytes,
+ fileBytes: e.file_bytes,
ggufFilename: e.gguf_filename,
checkpoint:
e.checkpoint ??
(filename ? e.files.includes(filename) : e.repo_id === repoId),
}));
+ checkpointBytes.current = p.checkpoint_bytes;
if (additionalAssetDownloads(entries).length) setPending(entries);
- else if (entries.length)
- enqueueHubDownload(entries, { repoId, filename });
+ else if (entries.length) enqueuePlan(entries);
else fallback();
} catch (e) {
if (sequence.current !== id) return;
@@ -154,11 +167,7 @@ export function useRequiredAssetsDownload({
setPending(null);
}}
onConfirm={(include) => {
- if (pending)
- enqueueHubDownload(selectDownloadEntries(pending, include), {
- repoId,
- filename,
- });
+ if (pending) enqueuePlan(selectDownloadEntries(pending, include));
setPending(null);
}}
/>
diff --git a/studio/frontend/src/features/hub/download-manager/download-breakdown.ts b/studio/frontend/src/features/hub/download-manager/download-breakdown.ts
new file mode 100644
index 00000000000..44afc618a1a
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/download-breakdown.ts
@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { DownloadBreakdown } from "./download-manager-types";
+
+export type DownloadPartKind = "model" | "encoder" | "vae";
+
+export interface DownloadPart {
+ kind: DownloadPartKind;
+ bytes: number;
+ doneBytes: number;
+}
+
+// Same patterns assetLabel reads an entry's file list with.
+const ENCODER = /text_encoder|clip|t5|qwen.*vl/i;
+// `ae.safetensors` is FLUX.1's VAE, picked as a root-level VAE override; LTX-2's audio decoder is `vocoder/`.
+const VAE = /vae|decoder|codec|vocoder|(^|\/)ae\.safetensors$/i;
+// A weights file at the repo root is a single-file pick, the model itself: a hosted prequant such as
+// `Qwen-Image-2.1-FP8.safetensors` names no transformer/ folder. Encoder prequants there say text_encoder.
+// ComfyUI-layout single-file picks sit under diffusion_models/ or checkpoints/ (diffusion_content.py).
+const MODEL = /transformer|unet|diffusion_models\/|(^|\/)checkpoints\/|\.gguf$|^[^/]+\.(safetensors|pt|pth|bin)$/i;
+
+// Three parts only: the small leftovers (tokenizer, scheduler, model_index.json) count as the text encoder.
+function partOf(file: string): DownloadPartKind {
+ if (VAE.test(file)) return "vae";
+ if (MODEL.test(file) && !ENCODER.test(file)) return "model";
+ return "encoder";
+}
+
+const ORDER: DownloadPartKind[] = ["model", "encoder", "vae"];
+
+/** Bar segments for a companion download, or null when it doesn't split into two or more parts.
+ * Files arrive one at a time in name order (`snapshot_download`, `max_workers=1`), so the job's
+ * single byte count is spread over the files in that order. On a resumed download the job also
+ * counts files already on disk, so whatever `expectedBytes` holds beyond the listed files comes off
+ * the count first. */
+export function downloadParts(
+ breakdown: DownloadBreakdown | undefined,
+ downloadedBytes: number,
+ expectedBytes = 0,
+): DownloadPart[] | null {
+ if (!breakdown) return null;
+ const parts = new Map<DownloadPartKind, DownloadPart>();
+ // An unknown size arrives as 0: it has no width to draw, and an all-zero split would divide by zero.
+ const add = (kind: DownloadPartKind, bytes: number, doneBytes: number) => {
+ if (!(bytes > 0)) return;
+ const part = parts.get(kind) ?? { kind, bytes: 0, doneBytes: 0 };
+ part.bytes += bytes;
+ part.doneBytes += doneBytes;
+ parts.set(kind, part);
+ };
+ const cached = Math.max(0, breakdown.cachedCheckpointBytes ?? 0);
+ if (cached > 0) add("model", cached, cached);
+ for (const [file, b] of Object.entries(breakdown.earlierBytes ?? {})) add(partOf(file), Math.max(0, b), Math.max(0, b));
+ for (const [file, b] of Object.entries(breakdown.laterBytes ?? {})) add(partOf(file), Math.max(0, b), 0);
+ const listed = Object.values(breakdown.fileBytes).reduce((n, b) => n + Math.max(0, b ?? 0), 0);
+ let left = Math.max(0, downloadedBytes - Math.max(0, expectedBytes - listed));
+ for (const file of Object.keys(breakdown.fileBytes).sort()) {
+ const bytes = Math.max(0, breakdown.fileBytes[file] ?? 0);
+ if (bytes <= 0) continue;
+ const done = Math.min(bytes, left);
+ left -= done;
+ add(partOf(file), bytes, done);
+ }
+ const list = ORDER.flatMap((kind) => parts.get(kind) ?? []);
+ return list.length >= 2 ? list : null;
+}
+
+export function breakdownOfPersisted(
+ value: unknown,
+): { breakdown: DownloadBreakdown } | Record<string, never> {
+ if (!value || typeof value !== "object") return {};
+ const { fileBytes, cachedCheckpointBytes, earlierBytes, laterBytes } = value as Record<string, unknown>;
+ const sizes = sizesOf(fileBytes);
+ if (!sizes) return {};
+ const earlier = earlierBytes === undefined ? undefined : sizesOf(earlierBytes);
+ const later = laterBytes === undefined ? undefined : sizesOf(laterBytes);
+ if (earlier === null || later === null) return {};
+ return {
+ breakdown: {
+ fileBytes: sizes,
+ ...(typeof cachedCheckpointBytes === "number" &&
+ Number.isFinite(cachedCheckpointBytes)
+ ? { cachedCheckpointBytes }
+ : {}),
+ ...(earlier ? { earlierBytes: earlier } : {}),
+ ...(later ? { laterBytes: later } : {}),
+ },
+ };
+}
+
+function sizesOf(value: unknown): Record<string, number> | null {
+ if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+ const sizes = Object.entries(value);
+ if (!sizes.every(([, n]) => typeof n === "number" && Number.isFinite(n))) return null;
+ return Object.fromEntries(sizes) as Record<string, number>;
+}
+
+/** Gives each staged job the sizes of the plan's other jobs, so every row's bar shows model, text
+ * encoder and VAE from the start: earlier jobs as full segments, later ones as empty. A checkpoint
+ * already on disk goes on the first companion as a full model segment. */
+export function withPlanBreakdown<T extends { checkpoint?: boolean; fileBytes?: Record<string, number> }>(
+ entries: T[],
+ checkpointBytes: number | undefined,
+): (T & { cachedCheckpointBytes?: number; earlierBytes?: Record<string, number>; laterBytes?: Record<string, number> })[] {
+ // A checkpoint entry that counts no bytes only links a file an older snapshot holds, so it is cached too.
+ const checkpointDownloads = entries.some(
+ (e) => e.checkpoint && Object.keys(e.fileBytes ?? {}).length > 0,
+ );
+ const cachedOn =
+ checkpointBytes && checkpointBytes > 0 && !checkpointDownloads
+ ? entries.findIndex((e) => !e.checkpoint)
+ : -1;
+ // Summed, not overwritten: two repos can both stage `model.safetensors`.
+ const merged = (list: T[]) => {
+ const out: Record<string, number> = {};
+ for (const e of list) for (const [file, b] of Object.entries(e.fileBytes ?? {})) out[file] = (out[file] ?? 0) + b;
+ return out;
+ };
+ return entries.map((e, i) => {
+ const earlierBytes = merged(entries.slice(0, i));
+ const laterBytes = merged(entries.slice(i + 1));
+ return {
+ ...e,
+ ...(i === cachedOn ? { cachedCheckpointBytes: checkpointBytes } : {}),
+ ...(Object.keys(earlierBytes).length ? { earlierBytes } : {}),
+ ...(Object.keys(laterBytes).length ? { laterBytes } : {}),
+ };
+ });
+}
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
index 235eba8d1d6..c463f463f34 100644
--- a/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
@@ -31,6 +31,7 @@ import {
hydrateDownloadManager,
useDownloadManagerStore,
} from "./download-manager-controller";
+import { downloadParts } from "./download-breakdown";
import { DownloadProgressBar } from "./download-progress-bar";
import { presentedProgress } from "./download-presentation";
import { assetLabel } from "./required-assets";
@@ -215,6 +216,11 @@ function DownloadRow({ jobKey }: { jobKey: string }) {
cancelling={job.state === "cancelling"}
etaSeconds={job.etaSeconds}
activity={job.activity}
+ parts={
+ job.presentation
+ ? null
+ : downloadParts(job.breakdown, job.downloadedBytes, progress.expectedBytes)
+ }
/>
) : null}
{job.details?.length ? (
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-state.ts b/studio/frontend/src/features/hub/download-manager/download-manager-state.ts
index fe933f3220e..118535c6a58 100644
--- a/studio/frontend/src/features/hub/download-manager/download-manager-state.ts
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-state.ts
@@ -31,6 +31,7 @@ import {
downloadInventoryHintKind,
scopedDownloadInventoryKind,
} from "./download-manager-types";
+import { breakdownOfPersisted } from "./download-breakdown";
import { presentationForExpectedBytesUpdate } from "./download-presentation";
import {
clearRuntimeTimer,
@@ -154,6 +155,7 @@ function sanitizePersistedJob(
...(typeof value.checkpoint === "boolean"
? { checkpoint: value.checkpoint }
: {}),
+ ...breakdownOfPersisted(value.breakdown),
...inventoryKindOfPersisted(value, variant),
// A held reading must survive the reload: dropping the flag restores the stale downloadedBytes reading as measured, the "0 B left" the guard exists to stop.
// Absent means "never polled" only since the field existed, so a legacy record already carrying counters is read as held.
@@ -215,6 +217,7 @@ function toPersistedJob(
: {}),
...(job.scopedFiles !== undefined ? { scopedFiles: job.scopedFiles } : {}),
...(job.checkpoint !== undefined ? { checkpoint: job.checkpoint } : {}),
+ ...(job.breakdown !== undefined ? { breakdown: job.breakdown } : {}),
...(job.inventoryKind !== undefined
? { inventoryKind: job.inventoryKind }
: {}),
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-types.ts b/studio/frontend/src/features/hub/download-manager/download-manager-types.ts
index d44564cb5e5..1e25472ad8a 100644
--- a/studio/frontend/src/features/hub/download-manager/download-manager-types.ts
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-types.ts
@@ -38,6 +38,7 @@ export interface ManagedDownload {
scopedFiles?: string[];
/** True for the entry that IS the model the user picked, false for companion repos. Only the stager can tell them apart, since a checkpoint may be a single `.safetensors` and companions carry `.safetensors` too. */
checkpoint?: boolean;
+ breakdown?: DownloadBreakdown;
transport?: ResolvedTransport;
/** A Xet run that fell back to HTTP keeps its original cancel marker, so it, not `transport`, decides the stop control. */
cancelTransport?: ResolvedTransport;
@@ -56,11 +57,21 @@ export interface DownloadRequest {
scopeId?: string | null;
files?: string[];
checkpoint?: boolean;
+ breakdown?: DownloadBreakdown;
callerToast?: CallerToast;
/** Skip repeat Xet notices for later entries in a staged plan. */
skipXetNotice?: boolean;
}
+export interface DownloadBreakdown {
+ fileBytes: Record<string, number>;
+ /** The picked checkpoint, already on disk, shown as a full segment. */
+ cachedCheckpointBytes?: number;
+ /** The plan's other jobs: fetched before this one (full) and after it (empty). */
+ earlierBytes?: Record<string, number>;
+ laterBytes?: Record<string, number>;
+}
+
export interface DownloadPresentation {
label: string;
filename: string;
diff --git a/studio/frontend/src/features/hub/download-manager/download-progress-bar.tsx b/studio/frontend/src/features/hub/download-manager/download-progress-bar.tsx
index 4f874241c21..7d4ec3ffd71 100644
--- a/studio/frontend/src/features/hub/download-manager/download-progress-bar.tsx
+++ b/studio/frontend/src/features/hub/download-manager/download-progress-bar.tsx
@@ -2,8 +2,66 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { formatBytes, formatEta, formatRate } from "@/features/hub/lib/format";
+import type { DownloadPart, DownloadPartKind } from "./download-breakdown";
import { isIndeterminateProgress } from "./progress-reconcile";
+const PART_STYLE: Record<
+ DownloadPartKind,
+ { label: string; fill: string; track: string; text: string }
+> = {
+ model: {
+ label: "model",
+ fill: "bg-amber-500",
+ track: "bg-amber-500/25",
+ text: "text-amber-600 dark:text-amber-400",
+ },
+ encoder: {
+ label: "text encoder",
+ fill: "bg-blue-500",
+ track: "bg-blue-500/25",
+ text: "text-blue-600 dark:text-blue-400",
+ },
+ vae: {
+ label: "VAE",
+ fill: "bg-emerald-500",
+ track: "bg-emerald-500/25",
+ text: "text-emerald-600 dark:text-emerald-400",
+ },
+};
+
+function PartsBar({ parts }: { parts: DownloadPart[] }) {
+ const total = parts.reduce((n, p) => n + p.bytes, 0);
+ const widths = parts.map((p) => Math.max(2, (p.bytes / total) * 100));
+ return (
+ <div className="flex flex-col gap-1">
+ <div className="flex h-[3px] gap-0.5">
+ {parts.map((part, i) => (
+ <div
+ key={part.kind}
+ className={`relative overflow-hidden rounded-full ${PART_STYLE[part.kind].track}`}
+ style={{ width: `${widths[i]}%` }}
+ >
+ <div
+ className={`h-full ${PART_STYLE[part.kind].fill} transition-[width] duration-500 ease-linear`}
+ style={{
+ width: `${part.bytes > 0 ? (part.doneBytes / part.bytes) * 100 : 0}%`,
+ }}
+ />
+ </div>
+ ))}
+ </div>
+ {/* A legend, not labels under each segment: a 2% VAE segment has no room for its own. */}
+ <div className="flex flex-wrap gap-x-3 text-ui-10p5">
+ {parts.map((part) => (
+ <span key={part.kind} className={`whitespace-nowrap ${PART_STYLE[part.kind].text}`}>
+ {PART_STYLE[part.kind].label} {formatBytes(part.bytes)}
+ </span>
+ ))}
+ </div>
+ </div>
+ );
+}
+
export interface DownloadProgress {
expectedBytes: number;
downloadedBytes: number;
@@ -16,6 +74,7 @@ export function DownloadProgressBar({
cancelling = false,
etaSeconds = 0,
activity,
+ parts,
}: {
progress: DownloadProgress;
bytesPerSec: number;
@@ -27,6 +86,8 @@ export function DownloadProgressBar({
*/
etaSeconds?: number;
activity?: string;
+ /** From `downloadParts`; null or absent keeps the single bar. */
+ parts?: DownloadPart[] | null;
}) {
const exactPercent = Math.min(Math.max(progress.fraction, 0), 1) * 100;
const indeterminate = isIndeterminateProgress(progress, cancelling);
@@ -36,23 +97,27 @@ export function DownloadProgressBar({
const etaLabel = etaSeconds > 0 ? formatEta(etaSeconds) : "";
return (
<div className="flex flex-col gap-1.5 pb-1">
- <div className="relative h-[3px] overflow-hidden rounded-full bg-[color-mix(in_oklab,var(--foreground)_calc(6%*var(--contrast-wash-gain,1)),transparent)] dark:bg-[rgb(255_255_255_/_calc(0.06*var(--contrast-wash-gain,1)))]">
- {indeterminate ? (
- <div className="loading-bar-slide h-full w-1/3 rounded-full bg-status-warning/80" />
- ) : (
- <>
- <div
- className="h-full rounded-full bg-status-warning/80 transition-[width] duration-500 ease-linear"
- style={{ width: `${exactPercent}%` }}
- />
- <span
- aria-hidden="true"
- className="pointer-events-none absolute top-1/2 size-1.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-status-warning ring-2 ring-status-warning/30 transition-[left] duration-500 ease-linear"
- style={{ left: `${exactPercent}%` }}
- />
- </>
- )}
- </div>
+ {parts && !indeterminate ? (
+ <PartsBar parts={parts} />
+ ) : (
+ <div className="relative h-[3px] overflow-hidden rounded-full bg-[color-mix(in_oklab,var(--foreground)_calc(6%*var(--contrast-wash-gain,1)),transparent)] dark:bg-[rgb(255_255_255_/_calc(0.06*var(--contrast-wash-gain,1)))]">
+ {indeterminate ? (
+ <div className="loading-bar-slide h-full w-1/3 rounded-full bg-status-warning/80" />
+ ) : (
+ <>
+ <div
+ className="h-full rounded-full bg-status-warning/80 transition-[width] duration-500 ease-linear"
+ style={{ width: `${exactPercent}%` }}
+ />
+ <span
+ aria-hidden="true"
+ className="pointer-events-none absolute top-1/2 size-1.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-status-warning ring-2 ring-status-warning/30 transition-[left] duration-500 ease-linear"
+ style={{ left: `${exactPercent}%` }}
+ />
+ </>
+ )}
+ </div>
+ )}
<div className="flex items-center justify-between gap-2 text-ui-10p5 text-muted-foreground tabular-nums">
<span>
{indeterminate
diff --git a/studio/frontend/src/features/hub/download-manager/poll-loop.ts b/studio/frontend/src/features/hub/download-manager/poll-loop.ts
index 54c348fe6dc..b4e6a0667ef 100644
--- a/studio/frontend/src/features/hub/download-manager/poll-loop.ts
+++ b/studio/frontend/src/features/hub/download-manager/poll-loop.ts
@@ -794,6 +794,11 @@ export async function startJob(
: opts.adopt && existing?.checkpoint !== undefined
? { checkpoint: existing.checkpoint }
: {}),
+ ...(req.breakdown
+ ? { breakdown: req.breakdown }
+ : opts.adopt && existing?.breakdown
+ ? { breakdown: existing.breakdown }
+ : {}),
...(inventoryKind !== undefined
? { inventoryKind }
: opts.adopt && existing?.inventoryKind !== undefined
diff --git a/studio/frontend/src/features/hub/download-manager/use-staged-download.ts b/studio/frontend/src/features/hub/download-manager/use-staged-download.ts
index af232e5917d..dc7faddb5bb 100644
--- a/studio/frontend/src/features/hub/download-manager/use-staged-download.ts
+++ b/studio/frontend/src/features/hub/download-manager/use-staged-download.ts
@@ -26,6 +26,10 @@ export interface StagedDownloadEntry {
bytes: number;
ggufFilename?: string | null;
checkpoint?: boolean;
+ fileBytes?: Record<string, number>;
+ cachedCheckpointBytes?: number;
+ earlierBytes?: Record<string, number>;
+ laterBytes?: Record<string, number>;
/** A GGUF quant fetched as the standard variant download, as Chat does: the backend's variant
* plan brings its companion files, and the row reads "<repo> · <quant>". `files` is unused. */
ggufVariant?: string | null;
@@ -133,6 +137,16 @@ export function useStagedDownload({
scopeId,
files: current.files,
checkpoint: current.checkpoint,
+ ...(current.fileBytes && Object.keys(current.fileBytes).length > 0
+ ? {
+ breakdown: {
+ fileBytes: current.fileBytes,
+ cachedCheckpointBytes: current.cachedCheckpointBytes,
+ earlierBytes: current.earlierBytes,
+ laterBytes: current.laterBytes,
+ },
+ }
+ : {}),
skipXetNotice: laterEntry,
},
);
diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.ts
index c5a0c40da55..49cd7b52949 100644
--- a/studio/frontend/src/features/images/api.ts
+++ b/studio/frontend/src/features/images/api.ts
@@ -369,6 +369,8 @@ export interface DiffusionDownloadPlan {
repo_id: string;
files: string[];
bytes: number;
+ /** Size of each file counted in `bytes`. Absent on an older backend. */
+ file_bytes?: Record<string, number>;
gguf_filename: string | null;
/** Whether this entry holds the selected model. Only the planner knows, because a gated pick is
* staged from an ungated mirror under a different repo id. Absent on an older backend. */
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index e54b8dbf272..6bd99e16113 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -3350,7 +3350,10 @@ export function ImagesPage({
};
stagedQuantRevert.current = ownRevert;
}
- const entries = diffusionStagingEntries(plan.entries, repoId, opts);
+ const entries = diffusionStagingEntries(plan.entries, repoId, {
+ ...opts,
+ checkpointBytes: plan.checkpoint_bytes,
+ });
if (entries.length === 0) {
pickToast.dismiss(pickToastId);
if (downloadOnly) return true;
diff --git a/studio/frontend/src/features/video/video-page.tsx b/studio/frontend/src/features/video/video-page.tsx
index 1d1a6ee7192..415de8f9095 100644
--- a/studio/frontend/src/features/video/video-page.tsx
+++ b/studio/frontend/src/features/video/video-page.tsx
@@ -2853,7 +2853,10 @@ function VideoGenerator({
// the shared envelope's half of the contract rather than a live path.
incompatible = plan.incompatible_reason ?? null;
if (!incompatible && plan.entries.length > 0) {
- const entries = diffusionStagingEntries(plan.entries, repoId, opts);
+ const entries = diffusionStagingEntries(plan.entries, repoId, {
+ ...opts,
+ checkpointBytes: plan.checkpoint_bytes,
+ });
if (entries.length === 0) return handleLoadRef.current(repoId, opts, advanced);
pendingStagedLoad.current = {
repoId,
diff --git a/studio/frontend/src/lib/diffusion-pipeline-load-target.ts b/studio/frontend/src/lib/diffusion-pipeline-load-target.ts
index 8c12c9935d1..cb74a1a5021 100644
--- a/studio/frontend/src/lib/diffusion-pipeline-load-target.ts
+++ b/studio/frontend/src/lib/diffusion-pipeline-load-target.ts
@@ -1,6 +1,8 @@
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+import { withPlanBreakdown } from "@/features/hub/download-manager/download-breakdown";
+
type DiffusionPickSource = "hub" | "lora" | "exported" | "local" | "external";
/** A cached row pinned to its validated snapshot loads by path; `displayRepoId` keeps the logical id for planning. */
@@ -20,22 +22,25 @@ export function diffusionStagingEntries(
repo_id: string;
files: string[];
bytes: number;
+ file_bytes?: Record<string, number>;
gguf_filename: string | null;
checkpoint?: boolean;
}[],
repoId: string,
- opts: { filename?: string; displayRepoId?: string },
+ opts: { filename?: string; displayRepoId?: string; checkpointBytes?: number },
) {
const planRepoId = opts.displayRepoId ?? repoId;
- return entries
+ const staged = entries
.map((e) => ({
repoId: e.repo_id,
files: e.files,
bytes: e.bytes,
+ fileBytes: e.file_bytes,
ggufFilename: e.gguf_filename,
// `??`, not `||`: a planner answering false is an answer; the fallback is only for older backends.
checkpoint:
e.checkpoint ?? (opts.filename ? e.files.includes(opts.filename) : e.repo_id === planRepoId),
}))
.filter((e) => planRepoId === repoId || !e.checkpoint);
+ return withPlanBreakdown(staged, opts.checkpointBytes);
}
diff --git a/studio/frontend/tests/download-breakdown.test.ts b/studio/frontend/tests/download-breakdown.test.ts
new file mode 100644
index 00000000000..061ac80fef0
--- /dev/null
+++ b/studio/frontend/tests/download-breakdown.test.ts
@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readSrc, registerBundlerResolver } from "./helpers/kit.ts";
+
+registerBundlerResolver();
+
+const {
+ breakdownOfPersisted,
+ downloadParts,
+ withPlanBreakdown,
+} = await import("../src/features/hub/download-manager/download-breakdown.ts");
+const { diffusionStagingEntries } = await import(
+ "../src/lib/diffusion-pipeline-load-target.ts"
+);
+const { checkpointFirst, selectDownloadEntries } = await import(
+ "../src/features/hub/download-manager/required-assets.ts"
+);
+
+const GB = 1e9;
+// Qwen-Image-2.1 Q2_K on the diffusers route: the GGUF is cached, Run fetches the rest.
+const qwen = {
+ fileBytes: {
+ "text_encoder/model-00001-of-00004.safetensors": 5 * GB,
+ "text_encoder/model-00002-of-00004.safetensors": 5 * GB,
+ "text_encoder/model-00003-of-00004.safetensors": 5 * GB,
+ "text_encoder/model-00004-of-00004.safetensors": 2.5 * GB,
+ "vae/diffusion_pytorch_model.safetensors": 1.4 * GB,
+ },
+ cachedCheckpointBytes: 2.5 * GB,
+};
+
+test("a companion download splits into the cached model, text encoder and VAE", () => {
+ const parts = downloadParts(qwen, 0);
+ assert.deepEqual(
+ parts?.map((p) => [p.kind, p.bytes, p.doneBytes]),
+ [
+ ["model", 2.5 * GB, 2.5 * GB],
+ ["encoder", 17.5 * GB, 0],
+ ["vae", 1.4 * GB, 0],
+ ],
+ );
+});
+
+test("progress fills the files in the order they download", () => {
+ const parts = downloadParts(qwen, 18 * GB);
+ assert.equal(parts?.find((p) => p.kind === "encoder")?.doneBytes, 17.5 * GB);
+ assert.equal(parts?.find((p) => p.kind === "vae")?.doneBytes, 0.5 * GB);
+ // The cached model is not part of the job's byte count.
+ assert.equal(parts?.find((p) => p.kind === "model")?.doneBytes, 2.5 * GB);
+});
+
+test("a resumed download's files already on disk don't fill the segments early", () => {
+ // The job counts 19 GB; 4.6 GB of it was on disk before this run, so it isn't in fileBytes.
+ const parts = downloadParts(qwen, 4.6 * GB + 10 * GB, 18.9 * GB + 4.6 * GB);
+ assert.equal(parts?.find((p) => p.kind === "encoder")?.doneBytes, 10 * GB);
+ assert.equal(parts?.find((p) => p.kind === "vae")?.doneBytes, 0);
+});
+
+test("one kind of file keeps the single bar", () => {
+ assert.equal(
+ downloadParts({ fileBytes: { "vae/diffusion_pytorch_model.safetensors": GB } }, 0),
+ null,
+ );
+ assert.equal(downloadParts(undefined, 0), null);
+});
+
+test("a malformed persisted breakdown is dropped", () => {
+ assert.deepEqual(breakdownOfPersisted({ fileBytes: { a: "1" } }), {});
+ assert.deepEqual(breakdownOfPersisted({ fileBytes: [1] }), {});
+ assert.deepEqual(breakdownOfPersisted(null), {});
+ assert.deepEqual(breakdownOfPersisted(qwen), { breakdown: qwen });
+});
+
+test("a cached checkpoint lands on the first companion", () => {
+ const companions = [
+ { repoId: "a", checkpoint: false },
+ { repoId: "b", checkpoint: false },
+ ];
+ assert.deepEqual(
+ withPlanBreakdown(companions, 2.5 * GB).map((e) => e.cachedCheckpointBytes),
+ [2.5 * GB, undefined],
+ );
+});
+
+test("every job of a plan shows all three parts from the start", () => {
+ // FLUX.2-klein-9B: the GGUF downloads as its own job before the companions.
+ const [gguf, companion] = withPlanBreakdown(
+ [
+ { checkpoint: true, fileBytes: { "flux-2-klein-9b-Q4_K_M.gguf": 5.9 * GB } },
+ {
+ checkpoint: false,
+ fileBytes: {
+ "text_encoder/model.safetensors": 16 * GB,
+ "vae/diffusion_pytorch_model.safetensors": 168e6,
+ },
+ },
+ ],
+ 5.9 * GB,
+ );
+ const halfway = downloadParts(
+ { fileBytes: gguf.fileBytes ?? {}, laterBytes: gguf.laterBytes },
+ 3 * GB,
+ );
+ assert.deepEqual(
+ halfway?.map((p) => [p.kind, p.bytes, p.doneBytes]),
+ [
+ ["model", 5.9 * GB, 3 * GB],
+ ["encoder", 16 * GB, 0],
+ ["vae", 168e6, 0],
+ ],
+ );
+ // The GGUF counts once: as the companion's earlier job, not also as a cached checkpoint.
+ assert.equal(companion.cachedCheckpointBytes, undefined);
+ const next = downloadParts(
+ { fileBytes: companion.fileBytes ?? {}, earlierBytes: companion.earlierBytes },
+ 0,
+ );
+ assert.deepEqual(next?.[0], { kind: "model", bytes: 5.9 * GB, doneBytes: 5.9 * GB });
+});
+
+test("tokenizer and scheduler files count as the text encoder, so the bar has three parts", () => {
+ const parts = downloadParts(
+ {
+ fileBytes: {
+ "model_index.json": 1e3,
+ "scheduler/scheduler_config.json": 1e3,
+ "text_encoder/model-00001-of-00002.safetensors": 16 * GB,
+ "tokenizer/tokenizer.json": 16e6,
+ "vae/diffusion_pytorch_model.safetensors": 168e6,
+ },
+ cachedCheckpointBytes: 5.9 * GB,
+ },
+ 0,
+ );
+ assert.deepEqual(
+ parts?.map((p) => p.kind),
+ ["model", "encoder", "vae"],
+ );
+});
+
+test("staging carries the plan's per-file sizes and the cached checkpoint", () => {
+ const entries = diffusionStagingEntries(
+ [
+ {
+ repo_id: "unsloth/Qwen-Image-2.1",
+ files: Object.keys(qwen.fileBytes),
+ bytes: 18.9 * GB,
+ file_bytes: qwen.fileBytes,
+ gguf_filename: null,
+ checkpoint: false,
+ },
+ ],
+ "unsloth/Qwen-Image-2.1-GGUF",
+ { filename: "qwen-image-2.1-Q2_K.gguf", checkpointBytes: 2.5 * GB },
+ );
+ assert.equal(entries.length, 1);
+ assert.deepEqual(entries[0].fileBytes, qwen.fileBytes);
+ assert.equal(entries[0].cachedCheckpointBytes, 2.5 * GB);
+});
+
+test("a hosted prequant transformer at the repo root is the model, its encoder twin is not", () => {
+ const parts = downloadParts(
+ {
+ fileBytes: {
+ "Qwen-Image-2.1-FP8.safetensors": 12 * GB,
+ "Qwen-Image-2.1-text_encoder-INT8-ConvRot.safetensors": 9 * GB,
+ "vae/diffusion_pytorch_model.safetensors": 1.4 * GB,
+ },
+ },
+ 0,
+ );
+ assert.deepEqual(
+ parts?.map((p) => [p.kind, p.bytes]),
+ [
+ ["model", 12 * GB],
+ ["encoder", 9 * GB],
+ ["vae", 1.4 * GB],
+ ],
+ );
+});
+
+test("two repos staging the same file name both count toward the other rows", () => {
+ const [first] = withPlanBreakdown(
+ [
+ { checkpoint: true, fileBytes: { "flux1-dev-Q4_K_M.gguf": 7 * GB } },
+ { checkpoint: false, fileBytes: { "model.safetensors": 9 * GB } },
+ { checkpoint: false, fileBytes: { "model.safetensors": GB } },
+ ],
+ 7 * GB,
+ );
+ assert.deepEqual(first.laterBytes, { "model.safetensors": 10 * GB });
+});
+
+test("a ComfyUI-layout single-file checkpoint under diffusion_models/ is the model", () => {
+ const parts = downloadParts(
+ {
+ fileBytes: {
+ "split_files/diffusion_models/qwen_image_fp8.safetensors": 20 * GB,
+ "split_files/text_encoders/qwen_2.5_vl_7b.safetensors": 9 * GB,
+ "split_files/vae/qwen_image_vae.safetensors": 0.25 * GB,
+ },
+ },
+ 0,
+ );
+ assert.deepEqual(parts?.map((p) => [p.kind, p.bytes]), [
+ ["model", 20 * GB],
+ ["encoder", 9 * GB],
+ ["vae", 0.25 * GB],
+ ]);
+});
+
+test("files of unknown size make no segment, so an all-unknown plan keeps the single bar", () => {
+ assert.equal(
+ downloadParts(
+ {
+ fileBytes: { "model_index.json": 0 },
+ earlierBytes: { "flux1-dev-Q4_K_M.gguf": 0 },
+ laterBytes: { "vae/diffusion_pytorch_model.safetensors": 0 },
+ },
+ 5 * GB,
+ ),
+ null,
+ );
+});
+
+test("LTX-2's vocoder is part of the VAE, and files fill in name order, not plan order", () => {
+ const parts = downloadParts(
+ {
+ fileBytes: {
+ "text_encoder/model-00001-of-00011.safetensors": 9 * GB,
+ "vocoder/diffusion_pytorch_model.safetensors": 0.1 * GB,
+ "audio_vae/diffusion_pytorch_model.safetensors": 0.1 * GB,
+ },
+ },
+ 0.1 * GB,
+ );
+ assert.deepEqual(
+ parts?.map((p) => [p.kind, p.bytes, p.doneBytes]),
+ [
+ ["encoder", 9 * GB, 0],
+ ["vae", 0.2 * GB, 0.1 * GB],
+ ],
+ );
+});
+
+test("the Hub queue sizes earlier and later parts in the order it runs the jobs", () => {
+ // The plan lists the encoder repo before the GGUF; the queue fetches the checkpoint first.
+ const plan: { repoId: string; bytes: number; checkpoint: boolean; fileBytes: Record<string, number> }[] = [
+ {
+ repoId: "unsloth/Qwen-Image-2.1-FP8",
+ bytes: 9 * GB,
+ checkpoint: false,
+ fileBytes: { "Qwen-Image-2.1-text_encoder-FP8.safetensors": 9 * GB },
+ },
+ {
+ repoId: "unsloth/Qwen-Image-2.1-GGUF",
+ bytes: 12 * GB,
+ checkpoint: true,
+ fileBytes: { "qwen-image-2.1-Q4_K_M.gguf": 12 * GB },
+ },
+ ];
+ const [first, second] = withPlanBreakdown(checkpointFirst(plan), 0);
+ assert.equal(first.repoId, "unsloth/Qwen-Image-2.1-GGUF");
+ assert.deepEqual(
+ downloadParts(first, 0.1 * GB)?.map((p) => [p.kind, p.doneBytes]),
+ [
+ ["model", 0.1 * GB],
+ ["encoder", 0],
+ ],
+ );
+ assert.deepEqual(
+ downloadParts(second, 0)?.map((p) => [p.kind, p.doneBytes]),
+ [
+ ["model", 12 * GB],
+ ["encoder", 0],
+ ],
+ );
+ // Assets left unticked: the checkpoint alone keeps the single bar.
+ const [only] = withPlanBreakdown(checkpointFirst(selectDownloadEntries(plan, false)), 0);
+ assert.equal(downloadParts(only, 6 * GB), null);
+ // The Hub hook sizes the breakdown after the include choice and the reorder.
+ assert.match(
+ readSrc("features/hub/catalog/use-required-assets-download.tsx"),
+ /withPlanBreakdown\(checkpointFirst\(entries\)/,
+ );
+});
+
+test("a checkpoint the plan stages without bytes still shows as the cached model", () => {
+ // An older snapshot holds the GGUF: the plan stages it to link the file but counts nothing.
+ const [, companion] = withPlanBreakdown(
+ [
+ { checkpoint: true, fileBytes: {} },
+ { checkpoint: false, fileBytes: { "text_encoder/model.safetensors": 9 * GB, "vae/diffusion_pytorch_model.safetensors": GB } },
+ ],
+ 7 * GB,
+ );
+ assert.equal(companion.cachedCheckpointBytes, 7 * GB);
+});
+
+test("FLUX.1's root-level ae.safetensors counts as the VAE", () => {
+ const parts = downloadParts(
+ { fileBytes: { "flux1-dev-Q4_K_M.gguf": 6.8 * GB, "ae.safetensors": 0.335 * GB } },
+ 0,
+ );
+ assert.deepEqual(parts?.map((p) => p.kind), ["model", "vae"]);
+});
diff --git a/studio/frontend/tests/family-override.test.ts b/studio/frontend/tests/family-override.test.ts
index c6370ba746d..a4fe932b114 100644
--- a/studio/frontend/tests/family-override.test.ts
+++ b/studio/frontend/tests/family-override.test.ts
@@ -12,8 +12,13 @@ import {
resolvedFamilyOverrideSelection,
taskOpaqueArtifactSupportsFamilyOverride,
} from "../src/features/model-picker/components/model-selector/family-override.ts";
-import { diffusionPipelineLoadTarget, diffusionStagingEntries } from "../src/lib/diffusion-pipeline-load-target.ts";
-import { readSrc } from "./helpers/kit.ts";
+import { readSrc, registerBundlerResolver } from "./helpers/kit.ts";
+
+// diffusion-pipeline-load-target.ts imports through the `@/` alias.
+registerBundlerResolver();
+const { diffusionPipelineLoadTarget, diffusionStagingEntries } = await import(
+ "../src/lib/diffusion-pipeline-load-target.ts"
+);
test("an explicit family selects exactly one structurally loadable artifact kind", () => {
for (const [family, modular, want] of [
@@ -104,11 +109,11 @@ for (const page of ["features/images/images-page.tsx", "features/video/video-pag
"displayRepoId: l.displayRepoId",
"opaqueKind={opaqueKind}",
"loadedModelIdOverride={selectorModelId}",
- "diffusionStagingEntries(plan.entries, repoId, opts)",
"!pipelineTarget.onDevice",
]) {
assert.ok(text.includes(needle), needle);
}
+ assert.match(text, /diffusionStagingEntries\(plan\.entries, repoId, \{\s*\.\.\.opts,/);
if (page.includes("images")) assert.ok(text.includes("downloadOnly ? currentLoadAdvanced(repoId, false)"));
});
}