initial state: muzick music player + recommendation engine

ui/REVIEW_PROMPT.md

@@ -0,0 +1,38 @@
+You are reviewing screenshots of a self-hosted music player called **muzick**. The app has a fixed 3-pane layout: a left **NavRail** (icons + labels, groups: Library / Personal / System), a **TopBar** with a search input, a **main content** area, an optional right-hand **NowPlayingPanel** (queue + lyrics tabs), and a bottom **PlaybackBar** (track info on the left, transport + seek bar in the center, volume + lyrics/queue toggles on the right). It uses a dark theme with an accent color and faint ambient gradient glows in the background.
+
+The screenshots in this directory (`photo_1` through `photo_11`) show various pages of the app. Review each one against the criteria below.
+
+For each screenshot, tell me:
+
+1. **Which page/view it is.** The pages are: Home, Songs (`/tracks`), Albums, AlbumDetail, Artists, ArtistDetail, Genres, Vibe, Discover, Search, Quarantine, Settings, Jobs.
+
+2. **Layout integrity.** Any overlapping or clipped elements, content running under the playback bar, nav rail collapsing, now-playing panel covering content, horizontal scrollbars appearing where they shouldn't, elements touching edges with no padding.
+
+3. **Spacing & density.** Is anything cramped or conversely too sparse? Card grids — are gaps consistent, do cards align, are there orphan cards on the last row? List rows — is vertical rhythm even? Headers — do they breathe?
+
+4. **Typography & legibility.** Truncation that cuts off important text, text too small, low-contrast text (muted-on-surface), font rendering issues, inconsistent font weights/sizes between similar elements.
+
+5. **Color & theme.** Does the accent color work against the background? Any off-theme colors (raw grays, blues that don't match)? Are hover/active states visible? Do the ambient background glows add atmosphere or muddy the content?
+
+6. **Images / artwork.** Broken image icons, blank squares where album art should be, stretched/squished artwork, inconsistent corner radius between cards, no fallback gradient visible.
+
+7. **Affordances.** Buttons that don't look clickable, links that look like plain text, no visible hover state on things you'd expect, icon-only buttons missing tooltips (you can't see tooltips in a screenshot but note any icon button whose purpose isn't obvious from the icon alone).
+
+8. **Empty / loading / error states.** If a page looks empty, is there a helpful empty state or just blank space? Any bare "Loading…" text? Any visible error?
+
+9. **The PlaybackBar specifically.** Is the seek bar usable, are timestamps legible, does the track-info cluster on the left truncate gracefully, does the volume control feel right, are the lyrics/queue toggle icons clear?
+
+10. **The Vibe page specifically** (if shown): there's a "rolling vibe" feature with a timeline of upcoming tracks and seed controls. Is the concept understandable from the UI alone? Is the timeline readable? Are the controls clear?
+
+11. **Anything that just looks off** — even if you can't articulate why. List it; I'll diagnose against the source.
+
+Be specific about location (top-left, bottom bar, right panel, etc.) and severity (critical / major / minor / nit). If a screenshot is fine, say "no issues" and move on — don't invent problems.
+
+Group your findings by screenshot filename (e.g. `photo_1: …`, `photo_4: …`) so each can be mapped to the right source file.
+
+Note: these screenshots were taken **before** the following fixes were applied, so if you see any of these, they may already be resolved and you can mark them as "likely already fixed":
+- `scrollbar-hide` utility was missing (horizontal shelves showed scrollbars)
+- Geist webfont was loaded but not wired into the app
+- No `:focus-visible` outlines anywhere
+- `Artwork` component had no lazy-load or error fallback (broken images showed blank)
+- Settings theme toggle used an off-theme `bg-zinc-700` instead of the semantic border token

ui/REVIEW_RESULTS.md

@@ -0,0 +1,289 @@
+# muzick UI Review
+
+> Reviewed against criteria in `REVIEW_PROMPT.md`. Screenshots were taken **before** a set of known fixes (see bottom of file for pre-fix checklist).
+
+---
+
+## `photo_1` — Albums grid (close-up)
+
+**1. Page:** Albums  
+**2. Layout integrity:** No overlapping or clipped elements. Grid gaps are even. Cards do not touch edges. ✅  
+**3. Spacing & density:** Card gutters are consistent. No orphan cards visible in this partial view. ✅  
+**4. Typography & legibility:** Album titles and artist/year captions are small but legible. No awkward truncation in the visible titles. ✅  
+**5. Color & theme:** Gradients and dark background work well. Purple accent is not overused here. ✅  
+**6. Images / artwork:**
+- Most placeholders show a clear music-note icon on a colored gradient.
+- **Minor:** The top-left *Before Neon* card is extremely dark—almost black—making the title text below it harder to read against the dark page background (though the card itself has its own background).
+- **Minor:** One album in the bottom row has vivid neon-green/purple glitch-style art. If this is intentional album art, ignore; if it is corrupted decoding, it should be investigated.
+- **Nit:** *Blade Runner* and *Before Neon 2* appear multiple times consecutively (duplicate library entries), which makes the grid look repetitive.
+**7. Affordances:** Cards have clear hover area (whole card is a target). ✅  
+**8. Empty / loading / error states:** Not applicable.  
+**9. PlaybackBar:** Not visible in this crop.  
+**10. Vibe page:** Not shown.  
+**11. Anything off:** No critical issues.
+
+---
+
+## `photo_2` — Home / Dashboard
+
+**1. Page:** Home  
+**2. Layout integrity:** Clean three-pane feel (NavRail + main + playback bar). Nothing is running under the playback bar. The right edge of horizontal shelves shows a peeking card to imply scroll—good pattern, not a bug. ✅  
+**3. Spacing & density:**
+- Header section breathes well.
+- Horizontal shelves have consistent internal padding.
+- **Nit:** The gap between the "Start a Vibe" feature card and the three shortcut pills (Songs / Albums / Artists) feels slightly large; not broken, just spacious.
+**4. Typography & legibility:**
+- "Good listening" headline is crisp.
+- Muted subtitle "Your music, your way." has adequate contrast.
+- Shelf section headers ("Continue Listening", "Most Played") and "View all >" links are consistent in weight/size. ✅
+**5. Color & theme:** Ambient background glow is subtle and adds atmosphere without muddying content. ✅  
+**6. Images / artwork:**
+- Continue Listening uses gradient placeholders uniformly.
+- Most Played mixes real artwork and placeholders. No stretched images. ✅
+**7. Affordances:**
+- "Start a Vibe" card and shortcut pills look clickable.
+- **Minor:** The playback-bar lyrics/queue toggle icons on the far right are small and low-contrast; their purpose is only decipherable if you already know the app.
+**8. Empty / loading / error states:** Not applicable.  
+**9. PlaybackBar:**
+- "Nothing playing" state is clear.
+- Transport buttons are centered and evenly spaced.
+- Timestamps are tiny (0:00) but legible.
+- Volume slider looks usable.
+**10. Vibe page:** Not shown.  
+**11. Anything off:** No critical issues.
+
+---
+
+## `photo_3` — Songs (`/tracks`)
+
+**1. Page:** Songs  
+**2. Layout integrity:** List sits cleanly in the main area. No overlap. ✅  
+**3. Spacing & density:**
+- Row heights are uniform.
+- Vertical rhythm is even.
+- **Nit:** The list is very dense; there is no sticky alphabet header or subheader to orient the user while scrolling through hundreds of tracks.
+**4. Typography & legibility:**
+- Track titles are clear.
+- Artist names are appropriately muted.
+- Durations are right-aligned and consistent.
+- A few long Cyrillic titles appear slightly cramped but not truncated. ✅
+**5. Color & theme:** ✅  
+**6. Images / artwork:** Small thumbnails on the left are square and consistent. No broken images. ✅  
+**7. Affordances:** Rows look tappable/clickable. No visible row-hover state in the static screenshot, which is expected. ✅  
+**8. Empty / loading / error states:** Not applicable.  
+**9. PlaybackBar:** Same as photo_2. ✅  
+**10. Vibe page:** Not shown.  
+**11. Anything off:** No critical issues.
+
+---
+
+## `photo_4` — Albums
+
+**1. Page:** Albums  
+**2. Layout integrity:** Grid aligns to the container. No elements clipped by the viewport. ✅  
+**3. Spacing & density:**
+- 5-column grid feels appropriate for the width.
+- Gaps are consistent.
+- **Nit:** The last visible row appears to have 5 cards, but the page cuts off just below them; a tiny bit more bottom padding before the playback bar would help the grid feel fully "landed."
+**4. Typography & legibility:**
+- Long album titles truncate with ellipsis (e.g., "100 Favors (Feat. Detail, Birdman & Kendric..."). This is acceptable for a card grid.
+- **Minor:** The "50 on this page" subtitle under "Albums" is very muted; it could be slightly brighter to aid discoverability.
+**5. Color & theme:** ✅  
+**6. Images / artwork:**
+- Placeholder gradients are consistent corner-radius and icon sizing.
+- **Minor:** The neon green/purple zig-zag artwork (middle-bottom) is jarring compared to everything else. Verify it is real artwork and not a decode/render error.
+**7. Affordances:** Cards look clickable. ✅  
+**8. Empty / loading / error states:** Not applicable.  
+**9. PlaybackBar:** Same as photo_2. ✅  
+**10. Vibe page:** Not shown.  
+**11. Anything off:** No critical issues.
+
+---
+
+## `photo_5` — Artists
+
+**1. Page:** Artists  
+**2. Layout integrity:** Grid is tidy. No overlap. ✅  
+**3. Spacing & density:**
+- 5-column grid of circular avatars feels balanced.
+- Gaps are even.
+- **Minor:** Because avatars are circles inside square cards, the text below each card has a lot of horizontal space; very long artist names might still truncate, but none visible here do.
+**4. Typography & legibility:** Artist names are centered and readable. ✅  
+**5. Color & theme:** Placeholder gradients use a nice variety of hues; they add visual interest without clashing. ✅  
+**6. Images / artwork:**
+- Circles are well-cropped.
+- Real photos (21 Savage, ACRAZE) look good.
+- **Minor:** *2 Chainz* appears twice in the grid (row 2, columns 1 and 2). *Acryl madness* and *Acryl Madness* appear as two separate entries (row 4). This is almost certainly a **data-level duplicate** (case/whitespace normalization), but it makes the UI look buggy.
+**7. Affordances:** Cards look clickable. ✅  
+**8. Empty / loading / error states:** Not applicable.  
+**9. PlaybackBar:** Same as photo_2. ✅  
+**10. Vibe page:** Not shown.  
+**11. Anything off:** Duplicate artist entries are the only visible blemish.
+
+---
+
+## `photo_6` — Vibe (Start a Vibe)
+
+**1. Page:** Vibe  
+**2. Layout integrity:** Centered narrow column works well. Nothing overlaps. ✅  
+**3. Spacing & density:**
+- Top "Rolling Vibe" badge, headline, subhead, and "Surprise me" button have good vertical rhythm.
+- Seed track list is well-spaced.
+- **Nit:** The list only shows ~4.5 tracks before the screenshot ends; if the list is short, centering is fine, but for long lists it might feel odd to be center-constrained rather than left-aligned in the main area.
+**4. Typography & legibility:**
+- "Start a Vibe" is large and clear.
+- Subhead explains the concept succinctly.
+- Track titles/durations in the seed list are legible. ✅
+**5. Color & theme:** ✅  
+**6. Images / artwork:** Seed track thumbnails are small but clear. ✅  
+**7. Affordances:**
+- "Surprise me" is a strong primary action.
+- Seed rows look tappable.
+- **Minor:** It is not obvious from the UI what happens after you pick a seed (does playback start instantly? does a timeline appear?). A small hint or a secondary button like "Preview timeline" might help first-time users.
+**8. Empty / loading / error states:** Not applicable (there are seed tracks).  
+**9. PlaybackBar:** Same as photo_2. ✅  
+**10. Vibe page specifically:**
+- The concept is mostly understandable: "infinite recommendations from a track you love."
+- Because this is the **seed-selection** step, the actual rolling timeline is not visible here, so I cannot evaluate timeline readability from this screenshot.
+- The seed controls are clear.
+**11. Anything off:** No critical issues.
+
+---
+
+## `photo_7` — Quarantine
+
+**1. Page:** Quarantine  
+**2. Layout integrity:** Clean centered empty-state card. No overlap. ✅  
+**3. Spacing & density:** The empty-state box sits comfortably in the middle of the page. ✅  
+**4. Typography & legibility:** "No tracks in quarantine." and the helper sentence are readable. ✅  
+**5. Color & theme:** Shield icon uses a muted tone that fits the theme. ✅  
+**6. Images / artwork:** Not applicable.  
+**7. Affordances:** Not applicable.  
+**8. Empty / loading / error states:**
+- **Excellent.** This is a well-designed empty state: icon + headline + explanatory subtext ("Disliked tracks will appear here during the grace period."). It is not just blank space.
+**9. PlaybackBar:** Same as photo_2. ✅  
+**10. Vibe page:** Not shown.  
+**11. Anything off:** No issues.
+
+---
+
+## `photo_8` — Settings
+
+**1. Page:** Settings  
+**2. Layout integrity:** Vertical stack is clean. No overlap. ✅  
+**3. Spacing & density:**
+- Each section (Theme, Default volume, Library, Enrichment) has comfortable internal padding.
+- **Nit:** The page feels slightly narrow; the main content column is centered and does not use the full available width, leaving a lot of dead space on wider screens.
+**4. Typography & legibility:** Section headers and labels are clear. Toggle text is readable. ✅  
+**5. Color & theme:**
+- Theme selector shows 5 options. Default (Purple) has a visible active ring.
+- **Minor:** "Dark" and "Midnight" swatches are very similar; users may struggle to tell them apart at a glance.
+- **Pre-fix note:** The prompt mentions the theme toggle formerly used `bg-zinc-700`. I cannot confirm that raw gray is present from the screenshot alone; the active state now appears to use a semantic border.
+**6. Images / artwork:** Not applicable.  
+**7. Affordances:**
+- Toggle switches are standard and look interactive.
+- Buttons (Scan library, Reindex search, Reprocess artists) look clickable.
+- The volume slider is clear.
+**8. Empty / loading / error states:** Not applicable.  
+**9. PlaybackBar:** Same as photo_2. ✅  
+**10. Vibe page:** Not shown.  
+**11. Anything off:** No critical issues.
+
+---
+
+## `photo_9` — Jobs Overview
+
+**1. Page:** Jobs (Overview tab)  
+**2. Layout integrity:** Six stat cards in a horizontal row. No wrapping issues. ✅  
+**3. Spacing & density:** Cards are evenly distributed. Numbers are large and impactful. ✅  
+**4. Typography & legibility:**
+- Labels (WAITING, ACTIVE, etc.) are small and uppercase—appropriate for metadata.
+- Numbers are huge and readable.
+- **Nit:** The comma in "3,294" is slightly hard to see at this resolution because the numeral weight is heavy; still legible, just dense.
+**5. Color & theme:**
+- Completed (green) and Failed (red/coral) are standard semantic colors.
+- They are not strictly "on-theme" purple, but as status semantics they are acceptable.
+**6. Images / artwork:** Not applicable.  
+**7. Affordances:**
+- Refresh and Auto-refresh toggle in the top-right are clear.
+- **Minor:** It is not obvious whether the stat cards are clickable (e.g., to filter the History tab by status). If they are, a hover state or chevron would help.
+**8. Empty / loading / error states:** Not applicable.  
+**9. PlaybackBar:** Same as photo_2. ✅  
+**10. Vibe page:** Not shown.  
+**11. Anything off:** No critical issues.
+
+---
+
+## `photo_10` — Jobs History
+
+**1. Page:** Jobs (History tab)  
+**2. Layout integrity:** List fills the width correctly. No overlap. ✅  
+**3. Spacing & density:** Row heights are consistent. Timestamp column is right-aligned and does not collide with the arrow icon. ✅  
+**4. Typography & legibility:**
+- Job names and status badges are clear.
+- Timestamps ("about 1 hour ago", "5 days ago") are readable.
+- Durations below timestamps ("36min 13s") are small but legible. ✅
+**5. Color & theme:** Status pills ("Completed", "Scheduled") use muted backgrounds that fit the dark theme. ✅  
+**6. Images / artwork:** Not applicable.  
+**7. Affordances:**
+- Right-facing arrow on each row implies navigation/expansion.
+- Filter tabs (All / Completed / Failed / Running) are clear.
+- **Minor:** The "All Types" dropdown and "200 / 300 jobs" indicator are small but functional.
+**8. Empty / loading / error states:** Not applicable.  
+**9. PlaybackBar:** Same as photo_2. ✅  
+**10. Vibe page:** Not shown.  
+**11. Anything off:** No critical issues.
+
+---
+
+## `photo_11` — Search
+
+**1. Page:** Search  
+**2. Layout integrity:** Results list is cleanly contained. No overlap. ✅  
+**3. Spacing & density:** Same vertical rhythm as the Songs page. ✅  
+**4. Typography & legibility:**
+- "Search" headline and "50 results for 'Booker'" subhead are clear.
+- Cyrillic track titles render correctly. ✅
+**5. Color & theme:** ✅  
+**6. Images / artwork:** Thumbnails are consistent. No broken images. ✅  
+**7. Affordances:**
+- Search input shows an `×` clear button—good.
+- Rows look tappable.
+**8. Empty / loading / error states:** Not applicable (results present).  
+**9. PlaybackBar:** Same as photo_2. ✅  
+**10. Vibe page:** Not shown.  
+**11. Anything off:** No critical issues.
+
+---
+
+## Pre-fix checklist (from prompt)
+
+The following issues were noted in `REVIEW_PROMPT.md` as already fixed **after** these screenshots were taken. I did not observe clear evidence of them in the current screenshots, but I am recording them here for completeness:
+
+| Issue | Observed? | Notes |
+|-------|-----------|-------|
+| `scrollbar-hide` missing (horizontal shelves showed scrollbars) | Not visible | Horizontal shelves in photo_2 do not show native scrollbars; may be OS-hidden or already fixed. |
+| Geist webfont loaded but not wired in | Cannot verify | Static screenshot; text looks fine but font family cannot be determined from image alone. |
+| No `:focus-visible` outlines anywhere | Cannot verify | No focused elements are visible in any screenshot. |
+| `Artwork` component had no lazy-load or error fallback | Not observed | Placeholder gradients and music-note icons are visible everywhere artwork is missing; no broken-image icons seen. |
+| Settings theme toggle used `bg-zinc-700` | Cannot confirm | Theme toggles in photo_8 look acceptable, but exact token cannot be determined from image. |
+
+---
+
+## Summary
+
+| Screenshot | Page | Severity | Notes |
+|------------|------|----------|-------|
+| `photo_1` | Albums | Minor | Possible corrupted/glitched artwork; very dark album cover hard to read. |
+| `photo_2` | Home | Nit | Playback-bar utility icons are small/low-contrast. |
+| `photo_3` | Songs | — | No issues. |
+| `photo_4` | Albums | Minor | Neon glitch artwork looks suspicious; bottom grid row could use a hair more padding. |
+| `photo_5` | Artists | Minor | Duplicate artist entries visible (data issue leaking into UI). |
+| `photo_6` | Vibe | Nit | Seed selection is clear, but next-step affordance is implicit. |
+| `photo_7` | Quarantine | — | No issues; great empty state. |
+| `photo_8` | Settings | Nit | Content column is narrow; Dark/Midnight swatches are very similar. |
+| `photo_9` | Jobs Overview | Nit | Stat cards may benefit from a click affordance if they filter history. |
+| `photo_10` | Jobs History | — | No issues. |
+| `photo_11` | Search | — | No issues. |
+
+**No critical or major layout bugs found.** The app is visually coherent, spacing is generally consistent, and the dark theme with purple accents reads well.