Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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_checkpointsreturn@@ -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.pyindex 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 nodiff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.pyindex 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.pyindex 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(monkeypaassert 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 Trueassert base["bytes"] > 0assert 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.tsxindex 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.tsnew file mode 100644index 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.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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.0import { 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>{indeterminatediff --git a/studio/frontend/src/features/hub/download-manager/poll-loop.ts b/studio/frontend/src/features/hub/download-manager/poll-loop.tsindex 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 !== undefineddiff --git a/studio/frontend/src/features/hub/download-manager/use-staged-download.ts b/studio/frontend/src/features/hub/download-manager/use-staged-download.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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)"));});}