docs(13): capture phase context

2026-03-16 02:40:44 -04:00
parent a586e13a3a
commit 963487f892
1 changed files with 70 additions and 0 deletions
@@ -0,0 +1,70 @@
 # Phase 13: Library Views & Phantom Tracks - Context
 **Gathered:** 2026-03-16
 **Status:** Ready for planning
 <domain>
 ## Phase Boundary
 Filtered presentation across all views, search, and phantom track display. The default view shows all libraries merged (unified). Users can filter to a specific library via a dropdown, and all browse views (tracks, albums, artists, genres) plus search respect that filter. Playlists can contain tracks from multiple libraries. When a library is removed, its playlist tracks become phantom entries using the existing phantom infrastructure.
 </domain>
 <decisions>
 ## Implementation Decisions
 ### Library filter placement & interaction
 - Compact dropdown select control in the top bar, next to the search bar
 - Shows current selection (default: "All Libraries"), click to open list of libraries
 - Filter selection persists across view changes within a session (resets on app restart — no localStorage persistence)
 - Search respects the active library filter — searching with a library selected returns only matches from that library; "All Libraries" searches everything
 ### Filter behavior across views
 - Backend filtering — new SQL queries with library_id WHERE clauses, not frontend JS filtering (matches existing roadmap decision for 150K+ track collections)
 - When filtering to one library, only show artists/albums/genres that have at least one track in that library — entities with zero tracks in the selected library are hidden
 - Detail views (artist detail, album detail, genre detail) also respect the active library filter
 - Switching the library filter triggers a backend re-fetch with brief loading state (existing loading skeleton) — no per-library caching
 - Scroll positions reset when switching library filter (new data set)
 ### Phantom track appearance
 - Use existing phantom track infrastructure already built in playlist-details component — no new visual treatment needed
 - Existing `.track-item.phantom` CSS styling, phantom-resolver component, locate/remove actions all apply
 - Full phantom resolver available for library-removal phantoms (users can re-locate/re-match)
 - Preserve title, artist, album metadata in phantom columns (matches existing phantom_title, phantom_artist, phantom_album schema columns)
 - Phantom tracks are included in playlist track counts (total count, not split)
 ### Cross-library playlist behavior
 - Playlists always show all tracks regardless of the active library filter — playlists are user-curated, not filtered
 - No per-track library indicator in playlist views — tracks look the same regardless of source library
 - Adding tracks to a playlist works identically whether from a filtered or unfiltered view — no special confirmation
 - Queue matches the filter context — playing from a filtered view populates the queue with only that library's tracks
 ### Claude's Discretion
 - Exact dropdown styling and animation (should match existing design tokens)
 - How "All Libraries" vs specific library queries are structured internally (separate SQL queries vs parameterized)
 - Loading skeleton behavior during filter switch transitions
 - How library filter state is stored in the frontend (new store, extension of existing store, etc.)
 </decisions>
 <specifics>
 ## Specific Ideas
 - Phantom track infrastructure is already built in `playlist-details.ts` — phantom CSS classes, phantom-resolver component, locate/remove buttons. Library-removal phantoms should flow through the same rendering path (is_phantom = 1 with cached metadata columns).
 - The existing `GetAudioFilesByLibrary` SQL query already exists but isn't wired into the main view data path. Backend filtering will need similar filtered queries for albums, artists, genres, and FTS search.
 - The `track_metadata` VIEW already includes `library_id` — can JOIN on it for filtered queries.
 - Phase 12 already pre-populates phantom metadata BEFORE cascade delete, so the phantom columns should already be filled correctly when a library is removed.
 </specifics>
 <deferred>
 ## Deferred Ideas
 None — discussion stayed within phase scope
 </deferred>
 ---
 *Phase: 13-library-views-phantom-tracks*
 *Context gathered: 2026-03-16*