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*