muzick/docs/ui-rework.md

UI Rework Plan

Status: planned, not started. This document captures the target direction for a richer player UI (reference: the "LocalTunes" three-pane mockup) and what it implies for both the frontend and the backend. It is a plan to execute later, not a description of the current app.

1. Vision

Move from the current functional-but-plain single-content-column layout to a polished, artwork-forward three-pane music player in the spirit of modern desktop players (Spotify / Apple Music / the LocalTunes reference):

• Left: persistent navigation rail (library sections + a personal/"your music" group).
• Center: scrollable content (Home, Library, Vibe, etc.) — artwork-rich cards, horizontal carousels, hover-to-play.
• Right: persistent Now Playing panel — large artwork, track info, transport, and an Up Next / queue list.
• Bottom: full-width global playback bar (shuffle / prev / play / next / repeat, scrubber, volume, queue toggle) that's always visible regardless of route.
• Top: global search field + (future) user/account menu.

Accent-driven, rounded, soft-gradient cards; dark by default but fully themeable via tokens.

2. Layout structure

┌────────────────────────────────────────────────────────────────────────────┐
│  Top bar: [logo]            [ global search ⌘K ]            [bell] [avatar ▾] │
├───────────────┬────────────────────────────────────────────┬───────────────┤
│  Nav rail     │  Content (router Outlet)                    │  Now Playing   │
│  - Home       │   Good evening 👋                           │   [ artwork ]  │
│  - Songs      │   Quick Access cards                        │   Title/Artist │
│  - Albums     │   Recently Played  (carousel, View all)     │   scrubber     │
│  - Artists    │   Made for you     (mixes carousel)         │   transport    │
│  - Genres     │   ...                                       │   Up Next list │
│  - Playlists  │                                             │                │
│  - Folder     │                                             │   (collapsible)│
│  ──────────   │                                             │                │
│  Now Playing  │                                             │                │
│  Recently …   │                                             │                │
│  Most Played  │                                             │                │
│  Favorites    │                                             │                │
│  ──────────   │                                             │                │
│  Settings     │                                             │                │
│  Theme        │                                             │                │
│  About        │                                             │                │
├───────────────┴────────────────────────────────────────────┴───────────────┤
│  Bottom bar: [art] Title/Artist ♥   ⇄ ◀ ▶▶ ⏯ ▶▶ ↻      🔊──────   queue ▤  │
└──────────────────────────────────────────────────────────────────────────────┘

The right Now-Playing panel and the bottom bar are partly redundant by design (desktop players do this): the bottom bar is the always-on minimal transport; the right panel is the expanded view with queue and large art, and is collapsible.

3. Design tokens / theming

This rework is the right moment to finish theming. Today only the shell consumes tokens (--bg, --surface, --text, --accent from src/lib/theme.ts). Target:

• Expand the token set: --bg, --bg-elevated, --surface, --surface-hover, --border, --text, --text-muted, --accent, --accent-hover, --on-accent, plus gradient stops for cards (--card-grad-a/b).
• Drive Tailwind from the tokens: extend tailwind.config.js theme.colors to reference the CSS variables (e.g. bg: 'var(--bg)', surface: 'var(--surface)', accent: 'var(--accent)') so components use semantic classes (bg-surface, text-muted, bg-accent) instead of hard-coded bg-zinc-900 etc. This makes every component themeable without per-component edits.
• Keep the existing presets (Dark / Midnight / Forest / Plum), add a light option, and keep initTheme() applying the persisted choice before first paint.
• The reference's purple accent → add a "Default (Purple)" preset.

4. Component inventory (new / reworked)

Component	Purpose
AppShell	3-pane grid (rail / content / now-playing) + top bar + bottom bar. Replaces Layout.
NavRail	Sections + personal group + settings group; active state via --accent.
TopBar	Global search (debounced, ⌘K focus), account menu (stub until auth).
NowPlayingPanel	Right rail: large art, info, scrubber, transport, Up Next queue (reorder/remove). Collapsible.
PlaybackBar	Bottom global transport (always visible). Reworks NowPlayingBar.
MediaCard	Square artwork card with hover play overlay (used by carousels + grids).
Carousel / ShelfRow	Horizontal scroll row with title + "View all".
QuickAccessCard	Wide gradient card (Favorites / Recently Added / Most Played / Folder).
TrackRow	Reusable list row (replaces the per-page LibraryTrackRow) with art, actions, now-playing highlight.
Artwork	Resolves album/track artwork URL with a graceful gradient placeholder fallback.

State: keep Zustand usePlaybackStore (current/queue/isPlaying/position/volume) and useVibeStore; add a small useUiStore for panel collapse + theme if useful. The Up Next list is just the playback queue.

5. Backend work this UI implies (gaps)

The mockup assumes data we don't serve yet. Each is a discrete backend task:

1. Artwork serving — albums.artwork_id / Cover-Art URLs are stored but never served. Need GET /api/albums/:id/artwork (and/or per-track) that streams/redirects to the cached cover, plus a placeholder when absent. Without this every card is a gradient placeholder.
2. Playlists — the rail shows "Playlists"; there are no playlist tables/endpoints. Needs playlists + playlist_track schema and CRUD + reorder endpoints. (Net-new feature.)
3. "Most Played" — derivable now via GET /api/tracks?sort_by=play_count&order=DESC. Wire a dedicated view/shelf.
4. "Recently Added" — needs reliable mtime/created_at sorting (currently sorted client-side). Consider a created_at column + a sorted endpoint.
5. "Made for you" mixes — map to the Vibe engine: per-genre/seed mixes via /api/vibe/from-genre and saved seeds. No new engine work, just presentation + maybe a "mixes" endpoint that returns a handful of seed suggestions.
6. Folder browse — the rail shows "Folder"; there's no filesystem-browse endpoint. Needs a sandboxed GET /api/library/browse?path= under MUSIC_DIR (reuse the stream route's traversal guard). Optional / later.
7. Typesense search — the redesigned top-bar search wants fast fuzzy results; finish the Typesense indexing pipeline (collection + reindex job + index-on-enrich) so search graduates from the Postgres ILIKE fallback. (Already tracked in progress.md.)

6. Suggested phasing

1. Tokenise theming — extend tokens + wire Tailwind to CSS vars; migrate existing components to semantic colour classes. (Unblocks real theming; low risk, high leverage.)
2. AppShell + PlaybackBar + NowPlayingPanel — the structural 3-pane shell with the always-on transport and queue, reusing the current playback store/audio engine.
3. MediaCard / Carousel / Artwork + artwork backend endpoint — make the content artwork-forward; redesign Home around Quick Access + shelves.
4. Library/Discover/Vibe pages restyled onto the new components.
5. New features as desired: Playlists, Folder browse, Most Played/Recently Added shelves, Typesense search.

7. Non-goals (for the first rework pass)

• Auth / multi-user (still single-user).
• Mobile/responsive layout (target desktop first; the 3-pane collapses later).
• Real-time collaborative features.

8. Open questions

• Keep both the right Now-Playing panel and the bottom bar, or collapse to one? (Plan assumes both, panel collapsible.)
• Artwork storage: serve via a backend proxy/cache, or store files locally and serve static?
• Playlists: is this in scope for the rework, or a separate feature track?