mixboard/briefs/upload-state-indicators.md

Task: Shape upload state indicators on track rows

Context

Cloud upload v1 shipped (2026-03-18): single file upload via toolbar + right-click context menu on local tracks. The v1 UploadService tracks state globally (idle/uploading/success/error) but there's no per-track visual indicator of upload status.

We already have per-track download state indicators on track rows (downloaded/downloading/error icons, managed by DownloadManager and Track.downloadState). The user wants symmetrical upload indicators — so a track row shows whether it's been uploaded to the cloud, is currently uploading, or failed.

What needs shaping

1. Per-track upload state model: Currently UploadService is fire-and-forget — it doesn't associate uploads with Track objects. We need a way to track "this local Track has been uploaded to cloud" or "is currently uploading". Options:

   • Add uploadState to the Track SwiftData model (mirrors downloadState)
   • Keep it transient (in-memory only, lost on restart)
   • Persist upload history separately

2. Visual indicators on track rows: The row already shows download state icons. How should upload state appear?

   • Same position as download indicators? Or opposite side?
   • What icons/colors for: uploading (progress), uploaded (checkmark? cloud?), failed (red)?
   • Should "uploaded" persist after beets reorganizes the file (server-side the track ID changes)?

3. Interaction between upload and download states: A track could theoretically be both "downloaded from cloud" AND "uploaded to cloud" (if you download a cloud track, it becomes local, then re-upload). How to handle overlapping states?

4. Multi-file queue implications: If we later add batch upload (#1 from pre-brief), per-track state becomes essential for showing queue progress. Shape this with batch in mind.

Design questions for @designer

• Where on the track row should upload state appear?
• Icon vocabulary: what SF Symbols for uploading/uploaded/failed?
• Does it conflict with the existing download state indicators?
• Color coding: match download state colors or differentiate?

Existing code to review

• Sources/Models/Track.swift — has downloadState enum and property
• Sources/Views/TrackRow.swift — renders download state indicators
• Sources/Views/PlaylistView.swift — context menu with "Upload to Cloud"
• Sources/Services/UploadService.swift — current global state, no per-track tracking
• Sources/Services/DownloadManager.swift — per-track download state pattern to mirror

Pre-brief reference

See briefs/cloud-upload-v2-prebrief.md for the full list of deferred upload items and suggested grouping.