feat(indexing): surface encoder-model download progress in the album UI

[lstein]

Problem

On a fresh PhotoMapAI install, the very first indexing run must download the CLIP/SigLIP encoder weights (hundreds of MB) before any image can be encoded. Today this happens silently inside the encoder constructors — the album card just sits at "Processing 0/N" with a frozen 0% bar for a minute or more, looking hung.

What this does

Surfaces the download as a distinct "Downloading encoder model…" phase that drives the existing progress bar with real byte progress, then transitions cleanly into the normal scanning → indexing → mapping flow.

When the model is already cached, no download bar fires, so there's no spurious "Downloading…" flash — the card goes straight to scanning/indexing.

How it works

The three encoder backends each render their download through a tqdm byte-bar, but via different module-level references. A new capture_download_progress() context manager temporarily swaps those references for a subclass that forwards byte progress to a callback, restoring the originals on exit:

• clip.clip.tqdm — openai-clip URL download (the CPU-fallback default ViT-B/32)
• open_clip.pretrained.tqdm — open-clip URL downloads (non-HF tags)
• huggingface_hub.utils.tqdm.tqdm — HF Hub fetches (open-clip HF tags + all siglip)

It only patches when a callback is supplied, so the CLI/console path keeps its normal tqdm output, and only reports byte-unit bars (ignoring stray iteration counters). Callback exceptions are swallowed so a UI hiccup can never break a download.

Changes

• encoders.py — capture_download_progress() context manager + reporting tqdm subclass
• progress.py — IndexStatus.DOWNLOADING, report_download() (maps bytes onto the existing percentage/ETA fields), begin_indexing() (flips back once encoding starts), DOWNLOADING in is_running()
• embeddings.py — threads a download_callback through _process_images_batch (wrapping _build_encoder()); the async wrapper reports bytes and transitions DOWNLOADING→INDEXING on the first image. CLI/sync path passes None.
• album-manager.js / album-manager.css — downloading status branch (purple); existing bar/ETA logic reused. No endpoint change needed.
• Tests — test_progress.py (tracker), capture tests in test_encoders.py, album-manager-progress.test.js (Jest)

Known limitation

If a download server omits Content-Length, the total is unknown and the bar reads 0% while bytes stream (the shimmer animation still shows activity and the label still says it's downloading). In practice all three backends provide a total, so this is an edge case.

Verification

• make lint — ruff, eslint, prettier clean
• make test — 382 backend + 352 frontend, all passing
• Manually verified end-to-end: cleared the encoder caches, indexed an album, and confirmed the card shows "Downloading encoder model…" with the bar filling + ETA, then transitions to processing → mapping → complete. Re-indexing skips the download phase.

🤖 Generated with Claude Code

[lstein]

Tested working.