Phase 13: Library Views & Phantom Tracks - Context

Gathered: 2026-03-16 Status: Ready for planning

## 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.

## 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.)

## 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.

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 13-library-views-phantom-tracks Context gathered: 2026-03-16

4.1 KiB Raw Blame History