inline HF model download badge on image + video gen forms

[atomantic]

Summary

Surfaces whether the picked HF model's weights are already in the local cache (~/.cache/huggingface/hub/) before the user hits Render — so a multi-GB pull is an opt-in pre-fetch instead of a silent surprise mid-generation. Cached models get a green "Available · 7.8 GB" badge under the model picker; missing ones get a "Download (~est)" button that pre-fetches the repo over SSE with a file-by-file progress bar. Lazy download remains the existing fallback for users who skip the pre-fetch.

The video form also surfaces the active text encoder (a separate ~7–25 GB Gemma pull) with its own button, since the encoder is a shared dependency across every video render.

What ships

Server:

• server/lib/hfCache.js — async hub-cache inspector. Walks the latest snapshot dir, follows blob symlinks, treats dangling links (partial downloads) as "not cached" so users get the Download button instead of an "Available" badge that fails at render time.
• server/lib/hfDownload.js — spawns scripts/hf_download_repo.py in the FLUX.2 venv (fallback: mflux pythonPath, gated on FLUX.2 venv health so a broken venv doesn't trap every download). Parses STAGE: / DOWNLOAD: / USER_ERROR: lines into SSE-friendly events.
• server/lib/sseDownload.js — shared SSE driver for both image and video routes (and any future HF pre-fetch endpoint). Owns the cross-route in-flight Map keyed by repo so a FLUX repo referenced by both pages can't spawn two python children. req.on('close') registers before the cache-inspect await so a mid-await disconnect still kills the child.
• server/lib/mediaModels.js — repoForModel() maps mflux's legacy dev / schnell ids to canonical Black Forest Labs repos so they get the same badge as every other entry. isHfRepoId() distinguishes org/name from localPath text-encoder entries.
• Routes: GET /api/{image,video}-gen/models/status (per-model {cached, sizeBytes}); GET /api/{image,video}-gen/models/:id/download (SSE); GET /api/video-gen/text-encoder/download (SSE). The status routes parallelize N inspections with Promise.all.

Client:

• client/src/hooks/useModelDownloadStatus.js — fetches status + drives the SSE pre-download. Memoizes the active model's enriched status so a new SSE frame only re-renders the active badge, not the whole ImageGenControls subtree.
• client/src/components/media/ModelDownloadBadge.jsx — three states: cached (green "Available · 7.8 GB"), unknown repo (no badge), needs-download (button → inline progress bar + stage label + cancel).
• ImageGen.jsx, VideoGen.jsx, ImageGenControls.jsx — wire the badge in. Callers that don't pass the props (Universe Builder batch render, etc.) simply get no badge.

Helper script:

• scripts/hf_download_repo.py — per-file hf_hub_download with STAGE: marker emission so the SSE bridge can drive a real progress bar. Sequential rather than snapshot_download() so the UI can show per-file granular progress; trade-off documented inline.

Context

This is the "rest of #515" — the fix-local-python-setup author deferred the hfDownload.js work out of that PR (see commit e0765909's body: "in a file not yet on origin and not part of this PR's surface; left for whichever branch ships hfDownload") and it ships here. The codex review finding about hfDownload.js falling back to a broken FLUX.2 venv is already addressed by the isFlux2VenvHealthy() gate in resolveHfDownloadPython().

Test plan

• server: 8073 passing (+ 8 new hfCache scenarios)
• client: 602 passing
• Local smoke: image-gen page with FLUX.1-dev shows "Available" badge after first generation; uncached model shows Download button + progress; cancel during download kills the python child cleanly
• Video-gen page surfaces text-encoder Download button when Gemma isn't cached; LM Studio localPath entry shows as Available without a Download button

[Copilot]

Pull request overview

Adds an inline HuggingFace cache-awareness + opt-in prefetch flow to the Image Gen and Video Gen model pickers, so users can see (and optionally download) multi‑GB model weights before starting a render. This is implemented via new server cache-inspection + SSE download endpoints and a shared client hook/badge component to render “Available” vs “Download” with live progress.

Changes:

• Server: implement HF hub cache inspection and an SSE-driven repo prefetch pipeline (shared across image/video routes with in-flight dedupe).
• Client: add a reusable download-status hook + badge UI and wire it into ImageGen/VideoGen pickers (including video text-encoder prefetch).
• Tests/docs/changelog: add hfCache unit tests, update route tests/mocks, and document the new library modules and release note.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
server/routes/videoGen.test.js	Updates fileUtils PATHS mock to include new PATHS fields needed by download helper.
server/routes/videoGen.js	Adds /models/status, /models/:id/download (SSE), and /text-encoder/download (SSE) endpoints for video gen.
server/routes/imageGen.js	Adds /models/status and /models/:id/download (SSE) endpoints for image gen.
server/lib/sseDownload.js	New shared SSE download driver with cross-route in-flight dedupe + disconnect cancellation.
server/lib/README.md	Documents new hfCache, hfDownload, and sseDownload modules.
server/lib/mediaModels.js	Adds repoForModel() mapping + isHfRepoId() helper for distinguishing HF repo ids vs local paths.
server/lib/index.js	Exports the new HF cache/download utilities from the server lib barrel.
server/lib/hfDownload.js	New Node-side spawner/parser for hf_download_repo.py, emitting SSE-friendly events.
server/lib/hfCache.test.js	New unit tests validating cache-root resolution and cache inspection scenarios (complete/partial/nested).
server/lib/hfCache.js	New async inspector for HF hub cache snapshots + weight size aggregation.
scripts/hf_download_repo.py	New Python helper that lists repo files and downloads sequentially with progress markers for SSE.
client/src/services/apiImageVideo.js	Adds API helpers for fetching model cache statuses (image + video).
client/src/pages/VideoGen.jsx	Wires model + text-encoder cache status and download badge into Video Gen UI.
client/src/pages/ImageGen.jsx	Installs the model download-status hook and passes status/handlers down to controls (local mode only).
client/src/hooks/useModelDownloadStatus.js	New hook to fetch statuses and drive SSE downloads with auto-refresh + error toast.
client/src/hooks/README.md	Documents the new hook in the hooks index table.
client/src/hooks/index.js	Exports useModelDownloadStatus.
client/src/components/media/ModelDownloadBadge.jsx	New UI component for cached/unknown/needs-download states with progress + cancel.
client/src/components/imageGen/ImageGenControls.jsx	Adds optional badge rendering under model select when props are provided.
.changelog/NEXT.md	Adds release note entry describing the new inline status + prefetch feature and endpoints.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.