# Frontend Specification

## Core Technology Stack
- **Framework:** React (Vite-based)
- **Routing:** TanStack Router (Type-safe routing)
- **Data Fetching:** TanStack Query (Managing server state & caching)
- **State Management:** Zustand (Managing local client-side playback and vibe state)
- **Styling:** CSS Variables (Enabling easy theme switching)

## 1. Key UI Patterns

### **The "Look-ahead Buffer" (Seamless Playback)**
To prevent playback gaps, the frontend implements a **Prefetching Queue**.
- **Mechanism:** The client maintains a `playback_buffer` in Zustand containing the next 20 tracks.
- **Implementation:** When the user reaches track $N$, TanStack Query triggers a fetch for the next chunk ($N+20$) in the background.
- **User Experience:** Tapping "next" is near-instantaneous as the track is already in memory.

### **The "Vibe" Interface**
The core feature is the **Active Vibe Page**.
- **Visuals:** Shows the current "Rolling Window" as a progress bar/timeline.
- **Real-time Updates:** Displays "Incoming Recommendations" (Probation tracks) as they are discovered.
- **Controls:** Quick-access "Keep" / "Dislike" buttons that trigger the lifecycle state machine.

### **The "Quarantine" Page**
A management view for the `PENDING_REMOVAL` state.
- **Features:** List of hidden tracks, "time remaining" timers, and "Restore" / "Delete" actions.

## 2. State Management Strategy

### **Zustand Stores**
- **`usePlaybackStore`:** Tracks `current_track`, `playback_position`, `is_playing`, and the `local_queue`.
- **`useVibeStore`:** Manages the `active_session_id` and the current "Center Track" context.

### **TanStack Query**
- Used for all standard CRUD operations (Library, Artists, Albums).
- Configured with aggressive `staleTime` for static data (Artists/Albums) and low `staleTime` for dynamic data (History/Stats).

## 3. Navigation Structure

- **Home:** Continue Listening, Recently Added, Recently Played.
- **Library:** Artists, Albums, Tracks, Genres (hierarchical).
- **Vibe:** The infinite player/discovery interface.
- **Discover:** Manual exploration of similar artists/tracks.
- **Search:** Global fuzzy search.
- **Settings:** Theme, playback modes, and automation rules.